/Docs

Custom Events

Custom events let you record a conversion from your own JavaScript code at exactly the right moment. Instead of relying on a click or a URL change, you call avsb.track.event() yourself — inside a form submit handler, after a successful API call, when a user reaches a certain scroll depth, or at any other meaningful point in your application.

When to use custom events

Custom events are the right choice whenever a conversion cannot be captured by a click on a static element or by a URL change. Common use cases include:

  • Form submissions— the "submit" event on a form fires before the server processes it, so you can track the submission attempt. Or wait for the API response to confirm success before recording the conversion.
  • Purchases and checkouts — track the exact moment an order is confirmed, and pass the order total as a revenue value.
  • Scroll depth — fire when a visitor scrolls to 50% or 100% of a long-form content page.
  • Time on page — fire after a visitor spends 60 seconds on a page as a proxy for engagement.
  • Video completions — fire when a video player emits its ended event.
  • Multi-step flows — fire when a visitor completes a specific step in a wizard or onboarding flow.

Finding the metric short ID

Every custom event metric has a numeric short ID that you use when calling avsb.track.event(). This ID is shown in the metrics list on your project's Metrics page, next to the metric name. It is also shown inside the metric detail panel when you click on a metric.

The short ID is a number — for example 12345. You will pass it as the first argument to avsb.track.event().

The short ID is a number, not a string
Pass the short ID as a number, not a string. Writing avsb.track.event('12345', ...) with quotes will not work. Always write avsb.track.event(12345, ...) without quotes.

How to create a custom event metric

1

Go to the Metrics page

From your project dashboard, click Metrics in the left navigation.
2

Click New Metric

Click the New metric button to open the metric creation form.
3

Choose Custom as the type

Select Custom from the metric type options.
4

Give it a name

Enter a descriptive name like Checkout Form Submitted, Purchase Completed, or Video Finished.
5

Save the metric

Click Save. The metric is created and its short ID is now visible in the metrics list.
6

Note the short ID

Find the metric in the list and note its numeric short ID — you will need it in the next step.

Calling avsb.track.event()

Place a call to avsb.track.event()in your JavaScript at the moment you want to record a conversion. The function takes two arguments: the metric's short ID and an optional data object.

Basic usage
javascript
1// Record a conversion for metric with short ID 12345
2avsb.track.event(12345);
Inside a form submit handler
javascript
1document.querySelector('#checkout-form').addEventListener('submit', function() {
2  avsb.track.event(12345, { revenue: 49.99 });
3});
After an API call succeeds
javascript
1fetch('/api/subscribe', { method: 'POST', body: formData })
2  .then(function(response) {
3    if (response.ok) {
4      avsb.track.event(12345);
5    }
6  });
Scroll depth tracking
javascript
1var fired = false;
2window.addEventListener('scroll', function() {
3  if (fired) return;
4

5  var scrollPct = (window.scrollY + window.innerHeight) / document.body.scrollHeight;
6  if (scrollPct >= 0.5) {
7    avsb.track.event(12345); // fired when visitor reaches 50% scroll depth
8    fired = true;
9  }
10});
Time on page
javascript
1setTimeout(function() {
2  avsb.track.event(12345); // fired after 60 seconds on page
3}, 60000);

Passing revenue data

When the conversion involves a monetary transaction, pass the amount as a revenue property in the second argument. This unlocks Revenue Impact calculations in your experiment results.

javascript
1avsb.track.event(12345, { revenue: 49.99 });

Revenue should be a number representing the transaction amount in your primary currency. Do not pass currency symbols or formatted strings — only a plain number.

One conversion per visitor

Like all metric types in A vs B, custom events record at most one conversion per visitor. If you call avsb.track.event()multiple times for the same metric, only the first call is counted. Subsequent calls are silently ignored.

Tip
If you need to track total revenue rather than just whether a conversion happened, keep in mind that only the revenue value from the firstconversion call is stored. For experiments where visitors may make multiple purchases, consider whether your primary metric should be "first purchase" rather than total lifetime value.