Events Overview

Events are the foundation of conversion tracking, goal measurement, and integrations in Ttoolab.

Event types

| Event | Source | Description | | :---- | :----- | :---------- | | $exposure | Automatic (SDK) | Sent when a visitor is assigned to active experiments | | Custom events | ttoolab.track() | Any named event you send from your application | | Survey events | Automatic (SDK) | CES survey lifecycle events (shown, accepted, dismissed, completed) |

How events flow

sequenceDiagram
  participant Site as Your site
  participant Pixel as Ttoolab Pixel
  participant Edge as SDK Edge

  Site->>Pixel: ttoolab.track("purchase", payload)
  Pixel->>Pixel: Push to dataLayer / Clarity (if enabled)
  Pixel->>Edge: POST /sdk/event
  Edge-->>Pixel: { success: true }

Event payload

Each event sent to Ttoolab includes:

| Field | Description | | :---- | :---------- | | projectKey | Your project’s public key | | anonymousId | Browser-generated visitor ID | | eventName | Event name (e.g. add_to_cart, $exposure) | | payload | Custom key-value data | | url | Current page URL | | referrer | Document referrer | | userAgent | Browser user agent | | assignments | Active experiment assignments | | createdAt | ISO timestamp |

When events are sent

The SDK sends events only when:

1. The pixel has loaded experiment data (hasActiveExperiments is true)
2. The visitor has at least one active assignment
3. The event name is valid (1–128 characters)

If the network request fails, events are queued in localStorage and retried on the next page load.

Revenue tracking

Include a numeric revenue field in the event payload to attribute revenue to experiments:

window.ttoolab?.track("purchase", {
  revenue: 199.9,
  order_id: "ORD-12345",
  currency: "USD"
});

Integrations side effects

When integrations are enabled for your project, the SDK also:

• Pushes events to window.dataLayer (Google Analytics / GTM)
• Sets Clarity tags and fires Clarity custom events

See Google Analytics and Microsoft Clarity.

Next steps

• Tracking events
• Goals
• SDK endpoints