Skip to main content
menu-icon.png

 

x
Optimizely Knowledge Base

Custom analytics integrations in Optimizely X

This article is about Optimizely X. If you're using Optimizely Classic, check this article out instead.
 
relevant products:
  • Optimizely X Web Experimentation
  • Optimizely X Web Recommendations
  • Optimizely X Web Personalization

THIS ARTICLE WILL HELP YOU:
  • Create and enable a new custom integration
  • Troubleshoot common and potential issues with your custom analytics integrations

Custom analytics integrations enables Optimizely users to build their own analytics integrations on top of Optimizely X. It is an open framework built to deliver:

  • Flexibility in timing and data sent to third party analytics tools

  • Improved data consistency between Optimizely and third party analytics tools

  • Opportunity to reduce the number of events sent to third party analytics tools, which may reduce costs for analytics tools that charge per event

  • A standardized process for experiment setup, reducing the number of mistakes from selecting incorrect custom dimensions or values  

Example integrations can be found in our GitHub library.

If you’ve built any open source integrations, we encourage you to contribute them to our GitHub library. Email partner-enablement@optimizely.com to begin the process of submitting a contribution.

Create a new integration

  1. Navigate to Settings > Integrations.  

  2. Click the Create Analytics Integration button. From here, you have two options:

  • Click Using Visual Editor to write your own custom integration via the integration builder screen

  • Click Using JSON to create a new instance of a custom analytics integration using JSON. This is most commonly used when copying an integration from our GitHub library, a third party knowledge base, or from another project in your account.

custom-int.png

See our Knowledge Base article on troubleshooting custom analytics integrations for solutions to common issues.

The Visual Editor

The visual editor in the integration builder has three main components:

  • The Editable Fields menu (left)

  • The Track Campaign Decision custom code field (center)

  • The Code Assistant list (right), which is hidden by default

custom-int-visual-editor.png

Editable Fields

The integrations builder allows you to add optional fields to your integration. Each field defines a property that you can customize per experiment. For example, you could provide a field for a custom dimension for an analytics integration. This field can have a default value set in the integration builder. When the integration is used for a single campaign, the default value can be overwritten for that campaign.

Each field requires an API name, which you can use to reference it in JavaScript. In the example above, there is a field with the API name custom_dimension, which you can reference in the custom JavaScript as extension.custom_dimension.

Examples of editable fields include:

  • Public API Key

    • Example: Special token that is required to send data to the integration.

  • Attribute to attach experiment info to

    • Example: Google Analytics Custom Dimensions or Adobe Analytics eVar/prop

  • String value that needs to change

    • Example: Custom Tracker for Google Analytics

Any editable field or custom code added to an integration will be exposed in the Optimizely client.js file and available publicly. Don’t put private keys or passwords here.

The following variables are available to use in your JavaScript code:

Variable

Type

Description

campaignId

string

the ID of the campaign into which the user was bucketed

experimentId

string

the ID of the experiment into which the user was bucketed

variationId

string

the ID of the variation into which the user was bucketed

isHoldback

boolean

whether the user fell into the campaign holdback

campaign

object

campaign data

┗campaign.id

string

 

┗campaign.name

string

 

┗campaign.policy

string

Personalization campaigns may have values of 'equal_priority' ,  'ordered', or 'random'.

A/B tests can have values of 'multivariate' or 'single_experiment'

extension

object

contains the fields configured for the extension

Create as JSON

You can expedite creating a custom analytics integration by using JSON instead of the Visual Editor.

To see the JSON of an existing extension, click the Edit JSON… button for a custom integration. You can copy all of the JSON code there to copy this custom analytics integration to another project: in the target project, use the Using JSON option when creating a new custom analytics integration.

custom-int-edit-json.png

Enable an integration

Before you can start using an integration in any experiments, you’ll need to enable it in the dashboard. To do so, set the integration's On/Off toggle (on the right menu of the Integration dashboard) to On.

integration-turn-on.png

Enabling integrations also includes them in your project snippet.

Enable an integration for all new experiments

Some integrations don’t require any custom properties to be defined for each experiment (e.g., custom dimension for Google Analytics) and can be enabled by default for all experiments. In these cases, you can enable the integration once and not have to enable it every time you create a new experiment.

To enable the integration by default for all new experiments:

  1. In the custom analytics integration editor, select Settings.

  2. Check the Enable this integration by default for all new experiments box.
    custom-int-turn-on.png

You can see the setting for all experiments in the Integration Details section in the main Integrations dashboard.

custom-int-listed.png

Custom code and timing

The custom JavaScript in the Track Campaign Decision tab will run every time a bucketing decision is made for a campaign. This hook is useful for tracking the experiments and variations a visitor has been bucketed into.

For more details, check out our Knowledge Base article on custom code and timing in Optimizely X.

Timing

The JavaScript for custom integrations executes on JavaScript API campaignDecided. At a high level, the order of operations for the Optimizely client is:

  1. Project JavaScript

  2. Evaluate pages

  3. Evaluate campaigns and experiments on active pages

  4. Execute custom integration code when campaignDecided triggers (for each experiment or campaign)

  5. Shared code for an experiment

  6. Variation code for an experiment’s variation

For more details, see our Knowledge Base article on Optimizely X client execution.

Use getDecisionString with custom analytics integrations

The getDecisionString and getDecisionObject APIs are designed to make it easier to write custom analytics integrations. These APIs consolidate all the data about a campaign decision into a string or object that can be passed to a third party analytics provider. You can see examples in our article on analytics strings.

However, in some cases these APIs will return a value of null. This usually happens when a decision is made, but the user is not bucketed into the campaign. For example, if a visitor is on a page where a campaign is running, but they do not match the audience conditions for the campaign, the campaignDecided event fires. But these APIs will return null because the visitor is not bucketed in the campaign. If these APIs return null, you might not want to send anything to your third party analytics, because there isn't a decision to track.