Enhanced web targeting: Triggering

Triggering lets you control exactly when an experiment triggers. This is especially useful for single-page applications (SPAs), where the conditions for showing an experiment can change dynamically without a full page reload.

How targeting works

This feature triggers an experiment when a specific dataLayer event occurs. When you choose the dataLayer event trigger option, you set the event name that launches the experiment—for example, engagement.activate.

Experiments with a dataLayer event trigger don't start immediately. Instead, they wait for the required event in the window.dataLayer object. For example, if you configure an experiment with the event name engagement.activate, trigger it using the following JavaScript:

dataLayer.push({"event": "engagement.activate"});

The SDK listens for pushes to window.dataLayerand picks up any object with anevent property, evaluating it against the experiment's trigger conditions. The dataLayer name is always dataLayer. This isn't configurable for experiment triggering. The format follows the standard GTM dataLayer format: an array of objects pushed via dataLayer.push().

When an experiment triggers, all its targeting rules are evaluated. The experiment only applies changes if its targeting rules are met.

If an experiment triggers again, one of 3 scenarios applies:

1. If targeting rules no longer allow the experiment, it reverts changes.
2. If targeting rules still permit the experiment, no changes occur.
3. If targeting rules still permit the experiment, any run script modifications configured to execute repeatedly are executed again.

🚧

Experiments with custom triggers aren't managed automatically

Experiments with custom triggers need manual management. Unlike "on page load" triggering, with custom triggers, you display and hide experiments as needed. Triggering an experiment doesn't mean it will be displayed — an experiment only applies changes after all its targeting rules are met.

dataLayer event processing

The dataLayer object processes events after the Engagement JS SDK starts. The SDK also processes events added before it started, so there's no risk of missing early pushes. If dataLayer doesn't exist on the page yet, the SDK creates it automatically.

General guidelines for working with the dataLayer object apply to experiment triggering as well. The key rule: only use the push() method to add new objects to dataLayer after it's created.

To re-evaluate experiments during SPA navigation—for example, after a route change—use webxpClient.reset(). Refer to our SPA Experiments documentation for more details.

Use case examples

• Cart-value banner: Display a banner when the cart value exceeds a threshold (for example, "free shipping over $50"). On an SPA, cart updates happen without a page reload, so a page-load trigger would never fire. A dataLayer event lets you react the moment the cart changes.
• Post-flow changes: Trigger changes after a user completes a specific flow on an SPA, such as a multi-step checkout or onboarding sequence. This lets you show contextually relevant content at exactly the right moment in the journey, rather than guessing at page load.
• Async page variables: Use page variables in experiment templates when loading page variable data asynchronously. Before, only values known at page load were available, which meant experiments depending on late-loaded data (such as pricing or inventory) couldn't personalize accurately.
• Custom SPA routing: Run experiments on websites with custom SPA routing that don't follow standard URL-change patterns. Because the trigger is event-driven rather than URL-driven, you control exactly when experiments re-evaluate—regardless of how your routing is implemented.

Limitations

• Experiments can only have 1 trigger type. Select either "On page load" or "Datalayer event."
• Only 1 event name is supported per "Datalayer event" trigger.