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 a ?int $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 $userId = null,
    bool $validate = true,
);

By default the event name is validated. Pass validate: false to skip that 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: