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.

The metric key

Every custom event metric has a metric key: a short piece of text you choose when you create it, like signup_completed or added_to_cart. That key is the one argument avsb.track.event() needs, and it is shown on the metric in your project's Metrics page next to a ready-to-copy line of code.

Pick something readable and keep it stable, because it lives in your site's code:

avsb.track.event('signup_completed');

[avsb] track.event("signup") dropped: no metric has that key. Known: signup_completed, added_to_cart

How to create a custom event metric

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 key and an optional data object.

Basic usage:

// Record a conversion for the metric with the key "signup_completed"avsb.track.event('signup_completed');

Inside a form submit handler:

var checkoutForm = document.querySelector('#checkout-form');if (checkoutForm) {  checkoutForm.addEventListener('submit', function() {    avsb.track.event('checkout_submitted', { revenue: 49.99 });  });}

After an API call succeeds:

var formData = new FormData(); // whatever your form collectsfetch('/api/subscribe', { method: 'POST', body: formData })  .then(function(response) {    if (response.ok) {      avsb.track.event('subscribed');    }  });

Scroll depth tracking:

var fired = false;window.addEventListener('scroll', function() {  if (fired) return;  var scrollPct = (window.scrollY + window.innerHeight) / document.body.scrollHeight;  if (scrollPct >= 0.5) {    avsb.track.event('scrolled_half'); // fired when visitor reaches 50% scroll depth    fired = true;  }});

Time on page:

setTimeout(function() {  avsb.track.event('engaged_60s'); // fired after 60 seconds on page}, 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.

avsb.track.event('purchase_completed', { 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

A conversion-rate custom-event metric records at most one conversion per visitor. If you call avsb.track.event() multiple times for the same metric, only the first call moves the conversion rate; subsequent calls do not change it. Count and percentile metrics built on the same event are the exception: they take every call into account, so fire the event each time it genuinely happens.