Set Up Custom Events

Custom events let you measure storefront actions that matter to your test but are not covered by Shopify’s standard web pixel events. ABConvert supports four custom event types:

Event type	Use it to track
Click	A visitor clicks a specific storefront element.
Scroll depth	A visitor reaches a percentage of a page.
Page view	A visitor opens a page that matches a required URL scope.
Custom JS event	Your storefront code reports a successful action that the other event types cannot describe.

When to use custom events

Use a custom event when the action is important to your test and can be defined clearly. Good examples include clicking a size guide, reaching 75% of a long landing page, viewing a subscription page, or completing a custom product builder.

When not to use custom events

Do not create a custom event for a standard metric that ABConvert already reports, such as Added to Cart, Reached Checkout, or Completed Checkout. Standard metrics have built-in definitions and are easier to compare across tests. Do not use a custom event as your only evidence for a winner. Custom event results are directional and do not include statistical significance.

How custom events work

An active event listens for its saved condition on matching storefront pages. ABConvert uses the event definition for operational health signals and for eligible test Analytics. The same event can be used in more than one test.

Before you start

Custom events depend on the ABConvert theme connection and web pixel. Keep both enabled while you verify the event and run your test. An event must exist before a test starts and remain Active until that test ends. You can choose the event for a test after launch, but you cannot use an event that was created after the test started.

Create and verify the events you need before you launch a test. Archive them only after every test that uses them has ended. Archiving an event during a running test stops collection and removes that event from the test’s custom event results.

Understand the custom event library

Open Custom Events in ABConvert to see the event library. The columns describe both the event setup and its recent activity:

Event name identifies the event. The line below it shows how many running tests currently report the event.
Type shows whether the event tracks a click, scroll depth, page view, or Custom JS event.
First signal is the first accepted trigger ABConvert received for the event.
Last triggered is the most recent accepted trigger. This timestamp can take about 60 seconds to update.
Triggers 24h is a rolling count of accepted triggers from roughly the last 24 hours. It is a raw debugging count, not a unique visitor or session metric.
Status is either Active or Archived.

Use First signal, Last triggered, and Triggers 24h to confirm that an event started firing, still fires, and behaves as expected over time. These health signals are separate from test Analytics.

Custom Events library with Event name, Type, First signal, Last triggered, Triggers 24h, and Status columns — The custom event library and its activity columns

An Active event can fire on storefront pages where its conditions and page scope match. An Archived event no longer collects new triggers. You can keep up to 20 events active at once.

Create a custom event

Start a new event

Click Create event in the custom event library.

Choose an event type

Select Click, Scroll depth, Page view, or Custom JS event.

Set up the event

Give the event a clear name, then add the fields required for its type. Event names can contain up to 50 characters.

Set the page scope

Add URL rules when the event should fire only on certain pages. Page scope is optional for Click, Scroll depth, and Custom JS events. It is required for Page view events.

Create and verify the event

Save the event, trigger it on your storefront, and confirm that its activity columns update before you launch a test.

Create event dialog with Click, Scroll depth, Page view, and Custom JS event options — Choose one of the four custom event types

Click event

Use a Click event to track clicks on a specific storefront element, such as a button, link, image, or product option.

Enter an Event name.
Open Element Picker and navigate to the page that contains the element.
Click the element you want to track. ABConvert adds its CSS selector to the event setup.
Check the number of matching elements in the picker.
Add an optional page scope.
Create the event.

The click listener also counts clicks on child content inside the selected element. It can detect matching elements that the page adds after it loads. The event records at most once per page load. You can also enter a valid CSS selector directly. If the picker reports no matches, check the selector on the intended page before relying on the event.

Element Picker highlighting a Shop products button and showing its CSS selector, short selector option, and two matching elements — Use Element Picker to select a storefront element and capture its CSS selector

Use short selector is selected by default. It keeps the last part of the CSS selector, which can match similar elements elsewhere on the page. If you need one exact location, clear Use short selector and verify that the full selector matches only the intended element.

Scroll depth event

Use a Scroll depth event to learn whether a visitor reached a meaningful point on a page. It is an engagement signal, not proof that the visitor read the content.

Enter an Event name.
Set a scroll depth from 1% to 100%. The default is 75%.
Add an optional page scope.
Create the event.

The event fires when the visitor first reaches the selected depth and records at most once per page load.

Page view event

Use a Page view event when opening a particular page is the action you want to measure.

Enter an Event name.
Add at least one page URL rule. This required page scope defines the event.
Create the event.

The page URL is the only event-specific setting. If you add more than one URL rule, a page can match any one of them.

Custom JS event

Use a Custom JS event when your storefront code knows that an action succeeded, but Click, Scroll depth, or Page view cannot describe it reliably. Creating the event registers its name and slug in ABConvert. It does not track anything by itself. Copy the JavaScript shown for the event and run it in your storefront code at the moment the action succeeds.

window.ABConvertQueue = window.ABConvertQueue || [];
window.ABConvertQueue.push(function (ABConvert) {
  ABConvert.track('product_builder_completed');
});

The example reports a completed product builder. Replace product_builder_completed with the exact slug shown in ABConvert. Calls with an unknown or archived slug are ignored. A Custom JS event records at most once per page load, even if your code calls it more than once. A Custom JS slug remains reserved after archive. Give a replacement event a distinct name and update your storefront code to use its new slug. You can also add an optional page scope. ABConvert checks that scope when the page loads and ignores calls from pages outside it. See Track custom JS events on the JavaScript API page.

Set the page scope

Page scope controls which storefront URLs can trigger an event:

Exactly matches matches one storefront path, such as /pages/size-guide.
Starts with includes paths that begin with the value.
Contains includes paths that contain the value.

Multiple URL rules use OR logic, so a page can match any one rule. For Click, Scroll depth, and Custom JS events, page scope is optional. Leave it blank to allow the event on every storefront page where its other conditions match. For a Page view event, you must add at least one URL rule because the page itself is the trigger.

Set up event scope step with an empty optional page scope and Add URL button — Leave an optional page scope blank for all storefront pages, or add URL rules

Verify an event before launch

Open your storefront and perform the action once. Then return to the custom event library and check:

First signal appears for a new event.
Last triggered reflects the recent action. Allow about 60 seconds for this column to update.
Triggers 24h increases when a new page load produces another accepted trigger.

The 24-hour count includes raw storefront triggers from outside tests. It does not equal the unique visitor or session counts in Analytics. Custom event Analytics is processed separately and is not real-time. In the test creation wizard, the final Review and launch step lists your active custom events before you click Launch test. This list helps you check which events are ready before the test starts. It does not select events for reporting. After launch, use Manage custom metrics in the test’s Analytics dashboard to choose which eligible events to report.

Review and launch step listing two active custom events that can be reported after launch — Review active custom events before launching a test

Edit, duplicate, or archive an event

You can rename an event without changing its tracking slug. You cannot change its type, selector, scroll depth, or page scope after creation. Duplicate the event when you need a different setup, then verify the new event before using it in a future test. Archived events cannot be restored. You can duplicate an archived event to create a new active event, but the new event is not eligible for a test that already started. To stop tracking an event:

Open the event from the custom event library.
Click Archive event.
Review the warning and the listed running tests.
Click Archive event to confirm.

The event moves to the Archived tab and no longer counts toward the 20-active-event limit. Archive replaces deletion: the event definition remains available as a read-only record. When you archive an event, ABConvert shows the running tests that report it. Archiving stops new collection and makes the event ineligible for those running tests. Results from a test that ended while the event was still active remain available.

Archive custom event warning listing two running tests that currently report the event — The archive warning lists running tests that would lose the event

Common mistakes

Creating the event after launch. A new event cannot be added to a test that already started.
Archiving before the test ends. The event becomes ineligible for the whole running test, not only for future dates.
Treating Triggers 24h as an Analytics metric. It is a raw health signal and is not deduplicated by visitor or session.
Using a broad click selector. Check the match count, or clear Use short selector when you need one exact element.
Registering a Custom JS event without calling its code. The dashboard creates the event definition, but your storefront must call ABConvert.track().
Expecting repeat actions on one page to add repeat triggers. Click, Scroll depth, and Custom JS events record at most once per page load.

Next step

See Use Custom Events in Analytics to add an event to a visitor filter, the session-based funnel, or the Custom Events results section.

FAQ

Why can't I find the event I want to measure?

Check whether the event was created before the test started. Only events created before the test started can appear in that test’s Analytics.

Can I add an existing event after a test launches?

Yes. The event must have been created before the test started and must stay active until the test ends. Open Manage custom metrics in Analytics to add it.

Can I restore an archived event?

No. Duplicate it to create a new active event. The duplicate is a new event and cannot be added to a test that already started.

Why does Last triggered update before Analytics?

The library columns are operational health signals. Analytics uses processed test data and can take longer to update.

Can I change an event's selector or page scope?

No. You can edit the name only. Duplicate the event and create a corrected setup for future tests.

Get Started

Experiments

Targeting

Personalization

Analytics

Configuration

Integrations

AI integration (MCP)