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 HTML-first. On Shopify, conversions flow through the Web Pixel automatically — see Shopify Funnel Tracking — and you only need this guide if you’re firing custom events from theme-level JavaScript.

The API

Split Test Pro exposes a single 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.

Parameters

Parameter	Type	Required	Description
eventKey	string	yes	The event key matching the 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 in the Subscriptions column of the results view.

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,
});

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, Klaviyo) 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).

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 primary conversion 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.