Tracking Events

Use ttoolab.track() to send custom events from your site. Custom events can trigger goals and appear in experiment reports.

Basic usage

window.ttoolab?.track("add_to_cart", {
  product_id: "SKU-123",
  value: 199.9,
  currency: "USD"
});

The optional second argument is a plain object with any properties you need. Keep property names stable for reliable reporting.

Wait for the SDK to be ready

Events are only sent when the visitor has active experiment assignments. Use ready() for code that depends on the SDK state:

window.ttoolab?.ready(() => {
  document.getElementById("buy-btn")?.addEventListener("click", () => {
    window.ttoolab?.track("cta_click", {
      button: "buy-now"
    });
  });
});

E-commerce examples

Add to cart

window.ttoolab?.track("add_to_cart", {
  product_id: "SKU-123",
  quantity: 1,
  value: 49.99,
  currency: "USD"
});

Purchase with revenue

window.ttoolab?.track("purchase", {
  order_id: "ORD-98765",
  revenue: 149.99,
  currency: "USD",
  items: 3
});

The revenue field (number) is used for revenue-type goals and daily stats aggregation.

Link events to goals

In the dashboard, create a goal of type custom_event and set the event name to match your track() call. When a visitor with an active assignment triggers that event, it counts as a conversion.

Event name rules

Must be a non-empty string
Maximum 128 characters
Use snake_case or dot notation for consistency (e.g. signup.completed)

Automatic exposure event

The SDK sends $exposure automatically. Do not send this event manually unless you have a specific advanced use case.

Queue and retry

If POST /sdk/event fails, the SDK stores the event in a local queue (max 50 events) and retries on the next page load via flushQueue.

Google Tag Manager

If GTM events are enabled for your project, each tracked event also pushes to dataLayer:

// Pushed automatically by the SDK when GTM integration is enabled
window.dataLayer.push({
  event: "ttoolab_conversion",
  ttoolab_test: "ttoolab_test",
  ttoolab_experimentKey: "EXPERIMENT_KEY",
  ttoolab_variantKey: "variant-b",
  ttoolab_eventName: "purchase",
  ttoolab_eventType: "conversion",
  ttoolab_revenue: 149.99
});

Debugging

Open DevTools → Network and filter for /sdk/event. A successful request returns:

{ "success": true }

If events are not sent, see Common issues.

SDK reference