SublimDocs

trackEvent

Sends a custom event: anything specific to your site that the tracker can't guess, such as a sign-up, a booking, a cancelled appointment or a video played.

JavaScript
sublim.trackEvent('appointment_booked', {
  props: { service: 'piercing', duration: 30 },
});

Signature

TypeScript
trackEvent(eventName: string, options?: {
  props?: Record<string, string | number | boolean>;
  revenue?: { amount: number; currency?: string };
  callback?: (result: { status?: number; error?: unknown }) => void;
}): void

Parameters

ParameterTypeDescription
eventNamestringRequired. The event's name. An empty name is ignored, with a console warning.
options.propsobjectProperties of this occurrence. You can then filter and split the event by them in the dashboard.
options.revenue.amountnumberRevenue attached to the event, used in revenue reports.
options.revenue.currencystringISO 4217 code (EUR, USD…). Defaults to USD here, so always set it.
options.callbackfunctionCalled once the request is done: { status } with the HTTP status, or { error } on a network error.

Naming events

  • Use snake_case and a verb: sign_up, quote_requested, appointment_cancelled.
  • Use one name per action, the same everywhere it can happen. Put the variants in properties ({ props: { source: 'header' } }) rather than in the name (sign_up_header).
  • Names are case-sensitive: Sign_Up and sign_up are two different events.
  • purchase is reserved for orders: use trackPurchase.

Properties

  • Keep properties flat. Strings, numbers and booleans are stored as they are, but nested objects and arrays are stored as plain text and can't be filtered on.
  • Never send personal data: no names, emails, phone numbers, addresses or free-text messages. Use IDs or categories instead.
  • Keep the same property names across events (plan, source…), so they line up in reports.
JavaScript
// ✅ Good
sublim.trackEvent('sign_up', { props: { plan: 'pro', source: 'pricing_page' } });

// ❌ Avoid: personal data, nested object, variant in the name
sublim.trackEvent('sign_up_pricing', { props: { email: 'jane@acme.com', user: { id: 42 } } });

Where to call it

Call trackEvent when the action has actually succeeded: after the API answered OK, in the success callback, or when the confirmation is shown. Don't call it on the button click, so that failed attempts and validation errors aren't counted.

JavaScript
async function cancelAppointment(id) {
  const res = await fetch(`/api/appointments/${id}`, { method: 'DELETE' });
  if (res.ok) {
    sublim.trackEvent('appointment_cancelled', { props: { reason: 'customer_request' } });
  }
}

Calling it before the script has loaded

sublim.trackEvent only exists once the tracker has loaded. If your code may run earlier, for example in an inline script at the top of the page, see Calling before the script loads. The npm package doesn't have this issue.

With revenue

Attach an amount to any event, for example a paid subscription:

JavaScript
sublim.trackEvent('subscription_started', {
  props: { plan: 'pro' },
  revenue: { amount: 49, currency: 'EUR' },
});

For orders, use trackPurchase: it sets the event name, the order ID and the currency default for you.

PreviousConfigurationNext trackPageview