Event tracking

Event tracking is on by default (events.enabled = true). Use it to record custom events from anywhere in your application.

Privacy model

From Ranetrace::trackEvent(), each event ships with:

The event name and properties.
The authenticated user's ID (or an int|string $userId you pass explicitly).
A timestamp and the request's full URL.
user_agent_hash: the user agent hashed, not stored raw.
session_id_hash: the session ID hashed.

The IP address is not included in the event payload.

Tracking a custom event

use Ranetrace\Laravel\Facades\Ranetrace;

Ranetrace::trackEvent('button_clicked', [
    'button_id' => 'header-cta',
    'page' => 'homepage',
]);

Full signature:

Ranetrace::trackEvent(
    string $eventName,
    array $properties = [],
    int|string|null $userId = null,
    bool $validate = true,
);

By default the event name is validated: it must be lowercase snake_case, start with a letter and be 3 to 50 characters long. A name that fails throws an InvalidArgumentException, even while event capture is off, so a bad name surfaces in development rather than in production. RanetraceEvents::custom() checks the same way. Pass validate: false to skip the check.

Convenience helpers

The RanetraceEvents facade exposes typed helpers (see the @method block on Ranetrace\Laravel\Facades\RanetraceEvents):

use Ranetrace\Laravel\Facades\RanetraceEvents;

// Sales
RanetraceEvents::sale(
    orderId: 'ORDER-456',
    totalAmount: 89.97,
    products: [
        ['id' => 'PROD-123', 'name' => 'Widget', 'price' => 29.99, 'quantity' => 3],
    ],
    currency: 'USD',
);

// Cart additions
RanetraceEvents::productAddedToCart(
    productId: 'PROD-123',
    productName: 'Widget',
    price: 29.99,
    quantity: 1,
);

// Authentication
RanetraceEvents::userRegistered(userId: $user->id);
RanetraceEvents::userLoggedIn(userId: $user->id);

// Page views (server-recorded)
RanetraceEvents::pageView(pageName: 'pricing');

// Generic custom event
RanetraceEvents::custom('newsletter_signup', ['source' => 'footer']);

All helpers accept an array $additionalProperties = [] as their final argument for ad-hoc fields.

Testing your setup

php artisan ranetrace:test-events

Configuration

From config/ranetrace.php:

'events' => [
    'enabled' => env('RANETRACE_EVENTS_ENABLED', true),
    'queue' => env('RANETRACE_EVENTS_QUEUE', true),
    'queue_name' => env('RANETRACE_EVENTS_QUEUE_NAME', 'default'),
    'timeout' => env('RANETRACE_EVENTS_TIMEOUT', 10),
],

To disable: