Custom Integrations
Create JavaScript integrations that send experiment and variation data to other tools, for example to the data layer for Google Tag Manager.
Custom Integrations are JavaScript snippets that run in the visitor's browser when an experiment event happens. A typical use is sending the experiment and variation a visitor saw to another tool, for example with dataLayer.push(...) for Google Tag Manager or GA4.
An integration belongs to one project. It is not workspace-wide and not tied to a single experiment. Every active integration is delivered with the project snippet and runs for every experiment and variation the visitor is bucketed into.
Where to find it
Open Project → Integrations → Custom Integrations. The badge shows how many integrations the project has. An active subscription is required.
The list shows the name, whether the integration is active, its trigger, whether it runs synchronously or asynchronously, a preview of the code and the last update. Use the row actions to Edit, Clone or Delete an integration. You can also select several rows and delete them together.
Create an integration
Click to create a new integration and fill in the three sections.
General
| Field | Rules |
|---|---|
| Name | Required, up to 191 characters, unique within the project. |
| Description | Optional, up to 2048 characters. |
| Active | On by default. Inactive integrations are not delivered to the snippet. |
Trigger Settings
When should this integration be triggered?
| Option | Runs |
|---|---|
| User bucketed | Only the first time a visitor is assigned to a variation. |
| Experiment viewed (default) | Every time the visitor views the experiment, so on each page view or re-run where the experiment is evaluated. |
Two more switches control the timing:
- Run synchronously (off by default): runs the integration immediately instead of queuing it. See Sync and async.
- Run in preview mode (off by default): also runs the integration while the visitor is in preview mode. In preview mode, integrations always run directly and are never queued.
Integration Code
Enter the JavaScript code. It is required and can be up to 32,768 characters long. The code runs whenever the integration is triggered.
Available data
Your code can read the current project, experiment and variation from project, experiment and variation. Each has a data object:
| Object | Fields |
|---|---|
project.data | id, name |
experiment.data | id, name |
variation.data | id, name |
The same values are also available as local constants: projectId, projectName, experimentId, experimentName, variationId and variationName.
dataLayer.push({
'event': 'experimentViewed',
'experiment_name': experiment.data.name,
'variation_name': variation.data.name
});How it runs on the site
- Publishing is automatic. The snippet is republished when you create, delete or restore an integration, or change its name, code, active state, trigger, sync flag or preview flag. You don't need to publish manually.
- Only active integrations are included, ordered by name. The code is minified if the project setting for shrinking JavaScript is on.
- Execution waits for DOM ready, then tries immediately and retries every 100 ms, up to 20 attempts (about 2 seconds), until the code runs without throwing an error. This helps when
dataLayeror a third-party library loads late. If it still fails, the browser console logsIntegration "<name>" did not complete after N attempts. - Nothing runs when tracking is disabled for the visitor (opt-out or Do Not Track), except in preview mode.
Write idempotent code
If your code partly succeeds and then throws an error, it is retried and may run more than once. Make sure running it twice does no harm.
Sync and async
An integration runs directly if Run synchronously is on for the integration or the experiment's run mode is Synchronous. Otherwise it is queued and runs together with the tracker events.
To override the mode for one experiment, open the experiment's code settings and choose Override integration run mode if necessary:
- Asynchronous
- Synchronous
- Inherit from integration (default)
Manage integrations
- Clone creates a copy named
<name> (Copy)and keeps all settings, including Active. - Delete removes the integration. It disappears from the snippet on the next publish.
- View activities on the edit page shows the change history. There is no versioning or rollback.