Optimizely X Destination

This destination is currently in beta. If you are interested in joining, let us know!

Segment makes it easy to send your data to Optimizely X (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Optimizely X in the format they understand.

Getting Started

Segment’s Optimizely X destination supports the following Optimizely products:

If you’re interested in implementing Optimizely Classic, Optimizely X Web, or Optimizely X Full Stack (JavaScript), please see Segment’s Optimizely destination, which supports:

Implementation Prerequisite

Optimizely works differently than other Segment destinations: It requires that customers implement at least some Optimizely functionalities natively.

Although Segment maps track events to Optimizely’s track method, customers must implement all Optimizely decision-based methods, such as activate, isFeatureEnabled, etc., natively. Segment’s API does not include methods that correspond to decision-based methods.

This limitation requires that customers include a native Optimizely implementation before their Segment implementation on pages or in mobile apps where Optimizely experiments run.

Server Side

Getting Started

  1. In your Segment source dashboard, enable the “Optimizely X” destination (not the “Optimizely” destination).
  2. Include your Optimizely project’s projectId and datafile URL in your Segment settings.
  3. Create a native Optimizely instance in your server environment so you can access Optimizely methods like activate, isFeatureEnabled, etc.
  4. Finally, define any metrics and attributes in your Optimizely dashboard, and to associate metrics with the appropriate Optimizely experiments. Segment maps track event names to Optimizely eventName - the eventName corresponds to an experiment metric. In addition, Segment maps track event context.traits to Optimizely attributes.

Track

Upon invocation of a Segment track event, Segment maps the event to an Optimizely track event:

  • If the Segment event name matches exactly the name of an active experiment metric set up in the Optimizely dashboard;
  • If the experiment metric is associated with a running expeirment;
  • If the current user has been assigned a userId via Segment’s identify method (e.g. analytics.identify('123'));
  • If the current user is activated in a running experiment with the associated metric.

Segment also handles the following mapping:

  • Segment track event name to Optimizely eventName.
  • Segment track event properties to Optimizely eventTags.
  • Segment track event context.traits to Optimizely attributes.

revenue values should be passed as a Segment property. The value should be an integer and represent the value in cents, so, for example, $1 should be represented by 100.

Segment defaults to identifying users with their anonymousId. Enabling the “Use User ID” setting in your Segment settings means that only track events triggered by identified users are passed downstream to Optimizely. No option is available to use userId and fall back to anonymousId, as Optimizely does not support identity resolution.

Experiment Listeners

Segment’s server-side integration with Optimizely does not support experiment listeners.

Android

Getting Started

  1. In your Segment source dashboard, enable the “Optimizely X” destination (not the “Optimizely” destination).
  2. Include Optimizely X’s native SDK in your your app-level build.gradle file: compile 'com.optimizely.ab:android-sdk:1.5.1'.
  3. Initialize the OptimizelyManager class in your app’s Application subclass.
  4. Then, pass the Manager instance to Segment’s Optimizely X integration factory. Your application subclass may look something like this:

     import com.segment.analytics.android.integrations.optimizelyx.OptimizelyXIntegration;
     import com.optimizely.ab.android.sdk.OptimizelyManager;
    
     public class OptimizelyApp extends Application {
    
         private static final String WRITE_KEY = "<YOUR_WRITE_KEY>";
         public static final String PROJECT_ID = "<YOUR_PROJECT_ID>";
         private OptimizelyManager optimizelyManager;
    
         public OptimizelyManager getOptimizelyManager() {
             return optimizelyManager;
         }
    
         @Override
         public void onCreate() {
             super.onCreate();
    
             optimizelyManager = OptimizelyManager.builder(PROJECT_ID)
                     .build(this);
    
             optimizelyManager.initialize(this, new OptimizelyStartListener() {
                 @Override
                 public void onStart(OptimizelyClient optimizely) {
                     assert optimizely == optimizelyManager.getOptimizely();
    
                     Analytics analytics = new Analytics.Builder(OptimizelyApp.this, WRITE_KEY) //
                             .use(OptimizelyXIntegration.factory(optimizelyManager))
                             .logLevel(LogLevel.VERBOSE).build();
    
                     Analytics.setSingletonInstance(analytics);
                 }
             });
         }
     }
    

    Here, initializing Segment in Optimizely’s onStart callback is non-blocking since Optimizely returns a dummy OptimizelyClient if a valid client cannot be initialized immediately. Segment also queues events in memory if the Optimizely Manager is slow to initializing, preventing data loss.

  5. Finally, define any metrics and attributes in your Optimizely dashboard, and to associate metrics with the appropriate Optimizely Experiments. Segment maps track event names to Optimizely eventName - the eventName corresponds to an experiment metric. In addition, Segment maps identify traits to Optimizely attributes.

Cloud Mode Implementation

Segment’s native Optimizely Android SDK supports only up to Optimizely X Android 1.5.1. If you need to use a more recent version of Optimizely, including Optimizely X 2.x, we suggest implementing Optimizely X natively in your Android app (without registering an Optimizely integration with your Analytics client), then enabling the “Optimizely X” component in your Segment dashboard. Segment will map track events to Optimizely track events on our servers rather than via the SDK and deliver the data to your Optimizely project as usual. This is the same as using Optimizely X in “cloud mode.”

Track

Upon invocation of a Segment track event, Segment maps the event to an Optimizely track event:

  • If the Segment event name matches exactly the name of an active experiment metric set up in the Optimizely dashboard;
  • If the experiment metric is associated with a running expeirment;
  • If the current user is activated in a running experiment with the associated metric.

Segment also handles the following mapping:

  • Segment track event name to Optimizely eventName.
  • Segment track event properties to Optimizely eventTags.

revenue values should be passed as a Segment property. The value should be an integer and represent the value in cents, so, for example, $1 should be represented by 100.

Segment defaults to identifying users with their anonymousId. Enabling “Use User ID” setting in your Segment dashboard means that only track events triggered by identified users are passed downstream to Optimizely. No option is available to use userId and fall back to anonymousId, as Optimizely does not support identity resolution.

Identify

Invoking a Segment identify event sets Segment traits as Optimziely attributes. The attributes are sent downstream to Optimizely upon invocation of the next Segment track event.

Reset

Invoking this method invalidates the listener for the Experiment Viewed event.

Experiment Listeners

Track Experiment Event

When the “Track Experiment Event” setting is enabled in your Segment settings, Segment triggers an event like the following whenever the current user is activated into a new experiment, or whenever you access an Optimizely live variable:

analytics.track("Experiment Viewed", new Properties()
    .putValue("experimentId", "1234567890")
    .putValue("experimentName", "android_experiment")
    .putValue("nonInteraction", 1)
    .putValue("variationId", "0987654321")
    .putValue("variationName", "variation_name"));

iOS

Getting Started

  1. In your Segment source dashboard, enable the “Optimizely X” destination (not the “Optimizely” destination).
  2. Include Optimizely X’s native SDK in your app. Segment’s iOS integration supports up to Optimizely iOS SDK 1.5.2.
  3. Initialize the OPTLYManager and provide this to the Segment Optimizely-X Integration.
  4. Then, pass the Manager instance to Segment’s Optimizely X integration factory:

    
         SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"<YOUR_WRITE_KEY>"];
    
         // Initialize an Optimizely manager
         self.optlyManager = [OPTLYManager init:^(OPTLYManagerBuilder *_Nullable builder) {
             builder.projectId = @"<YOUR_PROJECT_ID";
         }];
    
         // Provide the OPTLYManager to SEGOptimizelyXIntegrationFactory
         [configuration use:[SEGOptimizelyXIntegrationFactory instanceWithOptimizely:self.optlyManager]];
         [SEGAnalytics setupWithConfiguration:configuration];
    
         // Initialize an Optimizely client by asynchronously downloading the datafile
         [self.optlyManager initializeWithCallback:^(NSError *_Nullable error, OPTLYClient *_Nullable client) {
             // Activate user in an experiment
             OPTLYVariation *variation = [client activate:@"<YOUR_VARIATION>" userId:@"<USER_ID>"];
             if ([variation.variationKey isEqualToString:@"variation1"]) {
             // execute code for variation1
             } else if ([variation.variationKey isEqualToString:@"variation2"]) {
             // execute code for variation2
             } else {
             // execute default code
             }
         }];
    

    If Optimizely Client initialization is delayed, the activate method may fail. You will want to consider wrapping the variation logic around a condition to check if Optimizely has been initialized.

  5. Finally, define any metrics and attributes in your Optimizely dashboard, and to associate metrics with the appropriate Optimizely Experiments. Segment maps track event names to Optimizely eventName - the eventName corresponds to an experiment metric. In addition, Segment maps identify traits to Optimizely attributes.

Cloud Mode Implementation

Segment’s native Optimizely iOS SDK supports only up to Optimizely X iOS 1.5.2. If you need to use a more recent version of Optimizely, including Optimizely X 2.x, we suggest implementing Optimizely X natively in your iOS app (without registering the Optimizely integration with the Analytics client), then enabling the “Optimizely X” component in your Segment dashboard. Segment will map track events to Optimizely track events on our servers rather than via the SDK and deliver the data to your Optimizely project as usual. This is the same as using Optimizely X in “cloud mode.”

Track

Upon invocation of a Segment track event, Segment maps the event to an Optimizely track event:

  • If the Segment event name matches exactly the name of an active experiment metric set up in the Optimizely dashboard;
  • If the experiment metric is associated with a running expeirment;
  • If the current user is activated in a running experiment with the associated metric.

Segment also handles the following mapping:

  • Segment track event name to Optimizely eventName.
  • Segment track event properties to Optimizely eventTags.

revenue values should be passed as a Segment property. The value should be an integer and represent the value in cents, so, for example, $1 should be represented by 100.

Segment defaults to identifying users with their anonymousId. Enabling “Use User ID” setting in your Segment dashboard means that only track events triggered by identified users are passed downstream to Optimizely. No option is available to use userId and fall back to anonymousId, as Optimizely does not support identity resolution.

Identify

Invoking a Segment identify event sets Segment traits as Optimziely attributes. The attributes are sent downstream to Optimizely upon invocation of the next Segment track event.

Experiment Listeners

Track Experiment Event

When the “Track Experiment Event” setting is enabled in your Segment settings, Segment triggers an event like the following whenever the current user is activated into a new experiment, or whenever you access an Optimizely live variable:

[[SEGAnalytics sharedAnalytics] track:@"Experiment Viewed", properties: @{
    @"experimentId" : @"8734392016",
    @"experimentName" : @"variation_view",
    @"nonInteraction" : @1,
    @"variationId" : @"8729081299",
    @"variationName" : @"variation1"
}];

Personas

You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

Segment offers an optional Device-based Connection Mode for Mobile data with Optimizely X. If you’d like to use those features that require client-based functionality, follow the steps above to ensure you have packaged the Optimizely X SDK with Segment’s.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

Account ID

In order to use Optimizely X via server side, you must enter your Account ID from your Optimizely account. You can find this ID by visiting https://app.optimizely.com/v2/accountsettings/account/plan

Cache Exp

To optimize the server side integration, we will cache the fetched Datafile that you have provided for this amount of time (in seconds) in Redis. Since the datafile should not change unless you modified the conditions or variation rules of your experiments, it is advised to have a minimum floor of 300 seconds (5 minutes).

Datafile URL

In order to use Optimizely X server side, you must enter the entire URL for your datafile. It should look something like https://cdn.optimizely.com/json/9218021209.json

Sends the experiment and variation information as properties on a track call.

Send experiment data to other tools (as a track call). An “Experiment Viewed” track event will be triggered each time you access an Optimizely live variable. If you’re regularly accessing live variables and want to reduce the number of track events triggered, pass the “false” flag, for example our Android library would be:

Boolean myVariable = optimizelyClient.getVariableBoolean("myVariable",
                                                         userId,
                                                         false);

And for our iOS library:

bool myVariable = [optimizely variableBoolean:@"myVariable"
                                       userId:userId]
                           activateExperiment:False];

Specifies the Experiment Viewed as a non-interaction event for Google Analytics

Send Experiment Viewed as a non-interaction event

Only Track Known Users

Optimizely does not alias known and unknown users. By default, Segment will only send the anonymousId to Optimizely. Enable this to only send the userId to Optimizely. Important: This setting only applies if you are bundling this integration for mobile sources.

Use User ID

Enable this if you want the server side integration to use User ID instead of anonymous ID in your identify calls


If you have any questions, or see anywhere we can improve our documentation, please let us know!