Custom Events

The custom events API is how your site tells Split Test Pro that a visitor converted. It’s the bridge between your conversion goal definitions (Conversion Goals) and the data that drives your results.

This guide is for HTML sites. On Shopify, conversions flow through the Web Pixel automatically — see Shopify Funnel Tracking. The Shopify storefront script exposes only window.SplitTestPro.activate() (for event activation) and has no trackConversion, so on Shopify use the standard goals or a Page view goal instead.

The API

The HTML snippet exposes a conversion function on the window object:

window.SplitTestPro.trackConversion(eventKey, options);

There’s also an alias SplitTestPro.track(eventKey, options) that’s identical — use whichever reads better in your codebase. (The same object also has SplitTestPro.activate(eventName), which starts deferred experiments rather than recording a conversion — see Custom Events vs Activation Events.)

Parameters

Parameter	Type	Required	Description
eventKey	string	yes	The event key of a JavaScript event goal you defined in Settings → Conversion goals (e.g., signup, purchase).
options.value	number	no	Numeric value attached to the event (e.g., revenue in your store currency). Enables continuous-metric reporting.
options.amount	number	no	Alias for value. Use whichever feels natural.
options.currency	string	no	ISO 4217 currency code (e.g., "USD"). Optional — passed through for downstream tools.
options.hasSubscription	boolean	no	Set to true when the conversion is a recurring purchase. Surfaces as the Subscriptions row of the Other goals table on Results.

Examples

Simple count event (binary conversion):

window.SplitTestPro.trackConversion("signup");

Revenue event (continuous metric):

window.SplitTestPro.trackConversion("purchase", {
  value: 49.0,
  currency: "USD",
});

Recurring purchase:

window.SplitTestPro.trackConversion("subscription_started", {
  value: 19.0,
  currency: "USD",
  hasSubscription: true,
});

Page view goals

Not every conversion needs code. If the conversion is “the visitor reached a page” — a thank-you page, a confirmation URL, a pricing page — define a Page view goal instead of firing an event:

1. Open Settings → Conversion goals (/settings#goals) and click Create goal.
2. Set Kind to Page view.
3. Enter a URL pattern and how it matches: Exact match, Contains, Starts with or Regex. The pattern is checked against the page’s full URL.
4. Click Save goals.

The script records the conversion when an enrolled visitor loads a matching page, for every experiment that tracks the goal. Page view goals also work on Shopify. See Conversion Goals for the full goal settings.

When to Fire It

Fire the event at the moment the conversion happens — typically on a confirmation page or in a success handler. The script reads the visitor’s variant assignment from the cookie and posts the event tagged with that assignment.

// On the order confirmation / thank-you page
document.addEventListener("DOMContentLoaded", () => {
  const total = parseFloat(document.querySelector("[data-order-total]")?.dataset.total || 0);
  window.SplitTestPro.trackConversion("purchase", { value: total, currency: "USD" });
});

// On a form submit success callback
async function submitSignup(formData) {
  const result = await api.signup(formData);
  if (result.success) {
    window.SplitTestPro.trackConversion("signup");
  }
}

Event Naming Conventions

Use snake_case keys that describe the action. Good keys read like English and are stable across experiments:

• signup, paid_signup, enterprise_inquiry
• purchase, subscription_started, subscription_renewed
• lead_form_submitted, whitepaper_downloaded
• add_to_cart, checkout_completed

Avoid:

• Generic numeric keys (event_1, goal_a).
• DOM-event-collision names (click, submit, change) — these can clash with event activation listeners.
• Per-variant keys (signup_variant_b). The variant is recorded automatically; you don’t need to bake it into the event name.

Verifying Events Arrive

Test in your browser before relying on the data:

1. Open your site in DevTools, Network tab, filter for analytics.
2. Trigger the action that fires the event.
3. Confirm a POST to /api/html/experiment/analytics with status 200 (or 204).
4. Inspect the request body — it should contain event_type matching your event key plus the experiment and variant IDs.

If you don’t see the request, the event isn’t firing. Check the browser console for errors and verify window.SplitTestPro exists.

Multi-Experiment Visitors

If a visitor is in multiple concurrent experiments, a single trackConversion call records the conversion against every experiment they’re assigned to. You’ll see one POST /api/html/experiment/analytics per assignment in the Network tab — that’s expected. See Running Multiple Experiments for how concurrent assignments work.

Triggering Events From Tag Managers

The API is just a window function call, so any tag manager (Google Tag Manager, Segment and similar tools) can fire events:

GTM (Custom HTML tag):

<script>
  if (window.SplitTestPro) {
    window.SplitTestPro.trackConversion("{{Event}}", {
      value: parseFloat({{Order Total}}),
      currency: "USD"
    });
  }
</script>

Set the trigger to your conversion event in GTM (e.g., a purchase data-layer push).

Sending Conversions From Your Server

Some conversions only your backend sees — a subscription renewal, an order confirmed by a webhook, a signup that completes after email verification. Send those to POST /api/html/flags/conversion (or the /api/shopify/ path) with a server API key, using the same goal event keys as trackConversion. Each call needs an event_id, so a retried request counts once. See Evaluation API and, from Node, recordConversion in Node SDK & Hybrid Tests.

Custom Events vs Activation Events

Two different features use the word “event” in Split Test Pro — don’t confuse them:

• Custom events (this doc) — fired from your site to record that a visitor converted on a goal. Drives results data.
• Event activation — used to defer when an experiment activates for a visitor. See Event Activation.

You can use both at once: an experiment that activates on cta_click and tracks signup as its Default goal.

Next Steps

• Use the value field to track revenue and other quantitative outcomes: Continuous Metrics.
• Wire up the goal definitions that match your event keys: Conversion Goals.
• Defer experiment activation until a custom event fires: Event Activation.