Pan Product Analytics

Pan operates using a two-part system:

1. Client-side: A lightweight JavaScript library is injected into your HTML via middleware. It listens for viewed, clicked, or hovered events on elements with data-pan attributes. Events are batched to minimize server requests and do not collect personal information (no IP addresses or user agents).
2. Server-side: The library sends data to your Laravel application. Pan only stores the analytic name and a counter for each event type. It does not track user identity.

Pan tracks impressions, hovers, and clicks automatically by listening for the data-pan attribute on HTML elements.

Important: Event names must only contain letters, numbers, dashes (-), and underscores (_).

Example of tracking different tabs or buttons:

<div>
    <button data-pan="tab-1">Tab 1</button>
    <button data-pan="tab-2">Tab 2</button>
</div>

You can track Filament actions by passing the data-pan attribute through the extraAttributes method.

Track a specific action:

Action::make('subscribe')
    ->extraAttributes(['data-pan' => 'subscribe-button'])

Track all actions globally: Add this to a service provider's boot method to automatically track every action using its label as the analytic name:

use Filament\Actions\Action;

public function boot(): void
{
    Action::configureUsing(function (Action $action): void {
        $action->extraAttributes(fn () => ['data-pan' => $action->getLabel()]);
    });
}

To use Pan, you must first require the package via Composer and then run the installation command to set up the necessary Laravel components.

Requirements:

• PHP 8.3+
• Laravel 11.0+

Steps:

1. Install the package:

   composer require panphp/pan

2. Run the Pan installer:

   php artisan install:pan

The default route for tracking events is /pan. You can change this using PanConfiguration::routePrefix. If you set the prefix to internal-analytics, the tracking endpoint will be /internal-analytics/events.

PanConfiguration::routePrefix('internal-analytics');

By default, Pan limits the number of analytics records to 50 to prevent unwanted data from bad actors. You can manage this using PanConfiguration in your application (e.g., in a Service Provider).

Whitelist specific analytics: Only the names provided in the array will be stored.

use Pan\PanConfiguration;

PanConfiguration::allowedAnalytics([
    'tab-profile',
    'tab-settings',
]);

Set a custom maximum limit:

PanConfiguration::maxAnalytics(10000);

Allow unlimited analytics:

PanConfiguration::unlimitedAnalytics();

The Pan client initializes using a global __pan object on the window. This object holds configuration injected by the server-side implementation.

Configuration Keys

• csrfToken: The CSRF token used for authenticating event submissions.
• routePrefix: The URL prefix used for the analytics endpoint (e.g., if prefix is api/pan, events are sent to /api/pan/events).

Internal State

The __pan object also maintains references to active listeners and observers, which are cleaned up automatically if the script is re-initialized.

Use these commands to manage your stored analytics data.

Flush all analytics: Clears all analytics records.

php artisan pan:flush

Delete a specific analytic: Delete a record by its unique ID.

php artisan pan:delete <id>

Use the pan Artisan command to view a table of the analytics you have been tracking in your terminal.

View all analytics:

php artisan pan

Filter analytics by name:

php artisan pan --filter=tab-profile