README

scoby is an ethical analytics tool that helps you protect your visitors' privacy without sacrificing meaningful metrics. The data is sourced directly from your web server, no cookies are used and no GDPR, ePrivacy and Schrems II consent is required.

Start your free trial today on https://app.scoby.io/

Did you know?

Scoby is available for free for non-profit open-source projects.
Request your free account now

Installation

composer require scoby/analytics

Requirements

The Scoby Analytics client uses the php-http/discovery package to automatically find and use installed PSR-18 compliant HTTP clients. This change allows for greater flexibility and interoperability with various HTTP client implementations.

To use Scoby Analytics, you need to have a PSR-18 compliant HTTP client installed in your project. If you don't have a specific client, the package will fallback to using Guzzle if it's available.

Important: If no PSR-18 compatible adapter is found, an error will be logged, typically stating No PSR-18 clients found. Make sure to install a package providing "psr/http-client-implementation". Example: "php-http/guzzle7-adapter". In such cases, you should manually install a PSR-18 compliant client. As a convenient fallback, you can install Guzzle by running:

composer require guzzlehttp/guzzle

Prerequisites

You need two values to instantiate your scoby analytics client: your API key and a salt. The salt is used to anonymize your traffic before it is sent to our servers. You can generate a cryptographically secure using the following command:

openssl rand -base64 32

Please find your API key in your workspace's settings - don't have a workspace yet? Create one for free here

Usage

Instantiate your scoby analytics client using your API key and salt.

use Scoby\Analytics\Client;
$client = new Client('INSERT_YOUR_API_KEY_HERE', 'INSERT_YOUR_SALT_HERE');

After that the client supports synchronous and asynchronous logging of page views

// count page view synchronously ...
$client->logPageView(); 

// ... count page view asynchronously
$client->logPageViewAsync();

Disclaimer: PHP scripts are always blocking. The logPageViewAsync executes after all the main work is done right before your script exits.

The client will automatically scan the super global $_SERVER variable for all data it needs to work properly. All values can be overridden with fluent setters:

Enabling Debugging with a PSR-3 Logger

To facilitate debugging and gain more insights into the operations of the Scoby Analytics client, you can use the $client->setLogger method. This method accepts a PSR-3 compliant logger instance, allowing you to integrate your preferred logging solution.

PSR-3 is a standard that defines a common interface for logging libraries in PHP, ensuring compatibility and flexibility. By using a PSR-3 logger, you can easily log messages of various severity levels, such as debug, info, warning, and error.

To enable logging, simply pass a PSR-3 compliant logger instance to the setLogger method. Here's an example using Monolog, a popular logging library:

use Scoby\Analytics\Client;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// Create a logger instance
$logger = new Logger('name');
$logger->pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING));

// Instantiate your Scoby Analytics client
$client = new Client('INSERT_YOUR_API_KEY_HERE', 'INSERT_YOUR_SALT_HERE');

// Set the logger
$client->setLogger($logger);

// Now you can use your client as usual

With the logger set, you will receive log messages that can help you debug issues or understand the client's behavior better.

IP Address

// set IP address manually
$client->setIpAddress('1.2.3.4');

User-Agent

// set User Agent manually
$client->setUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:103.0) Gecko/20100101 Firefox/103.0');

Requested URL

// set requested URL manually
$client->setRequestedUrl('https://example.com/some/path?and=some&query=parameters');

Referring URL

// set referrer manually
$client->setReferringUrl('https://eyample.com/the/page/that?was=visited&before=yay');

Visitor Segments

Visitor segmentation is a powerful tool for improving your website's performance and user engagement. By dividing your audience into different segments based on their common characteristics or behaviors, you can better understand their needs and tailor your website content, marketing messages, and user experience to meet their specific preferences.

To use visitor segments, you need to define the characteristics or behaviors that you want to segment your audience by, such as age, gender, location, interests, or purchase history. Once you have defined your segments, you can assign them to your website visitors based on the data you collect from their interactions with your website. It's important to note that segments should always be used in plural, as this makes the most sense in the Scoby Analytics dashboard, where you can view and analyze your visitor segments data. Additionally, all future interactions of a visitor are associated with the segment they belong to at the time of the interaction.

To log visitor segments using the Scoby Analytics library in your PHP code, you can use the addVisitorToSegment method to assign a visitor to a specific segment, and the logPageView method to log a page view event with the assigned segments. Here's an example:

use Scoby\Analytics\Client;
$client = new Client('INSERT_YOUR_API_KEY_HERE', 'INSERT_YOUR_SALT_HERE');
$client
    ->addVisitorToSegment('Subscribers')
    ->addVisitorToSegment('Women')
    ->addVisitorToSegment('Young Adults')
    ->logPageView();

In this example, we are logging a page view event and assigning the visitor segments Subscribers, Women, and Young Adults to the visitor who triggered the event. You can replace these segments with your own segment names based on your segmentation strategy.

Scoby Analytics is designed to be privacy-preserving, and applies a k-Anonymity of 25 to visitor segments. This means that each segment must have at least 25 unique visitors before it is included in the analytics report, in order to protect the anonymity of individual visitors.

Visitor ID

To enhance the accuracy of visitor counting, you have the option to supply a custom identifier, such as an account ID or similar value. Before being transmitted to our servers, this identifier is hashed to prevent the sharing of personally identifiable information. Nonetheless, it is crucial to consult your data protection officer to ensure that using this feature aligns with your organization's legal and privacy requirements.

$client->setVisitorId('some-anonymous-identifier');

Complete example:

use Scoby\Analytics\Client;
$client = new Client('INSERT_YOUR_API_KEY_HERE', 'INSERT_YOUR_SALT_HERE');
$client
    ->setIpAddress('1.2.3.4')
    ->setUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:103.0) Gecko/20100101 Firefox/103.0')
    ->setVisitorId('some-anonymous-identifier')
    ->setRequestedUrl('https://example.com/some/path?and=some&query=parameters')
    ->setReferringUrl('https://eyample.com/the/page/that?was=visited&before=yay')
    ->logPageViewAsync();

IP Blacklisting

By default, Scoby does not exclude any traffic from your measurements. However, we understand that you may need to filter out traffic from specific IP addresses or ranges. The blacklistIpRange method allows you to do this, supporting both wildcard patterns and CIDR subnet notation for your convenience. You can add multiple IPs, patterns, and ranges as needed.

$client
    ->blacklistIpRange('12.34.*.*')
    ->blacklistIpRange('87.65.43.21/16')
    ->blacklistIpRange('1.2.3.4')
    ->blacklistIpRange('::1');