Configure Segment

Get started

📘

Note

This page has up-to-date information for Optimizely Feature Experimentation integration with Segment. The Segment-hosted docs update less frequently.

The first step is to verify that Feature Experimentation supports the source type and connection mode you have chosen to implement. To learn more about what dictates the connection modes Segment supports, see Connection Modes.

Segment’s Feature Experimentation (previously Optimizely Full Stack) destination supports the following Optimizely Experimentation products:

• Optimizely Full Stack (server)
• Optimizely Full Stack Android (Cloud-mode)
• Optimizely Full Stack iOS (Cloud-mode)

If you are interested in implementing Optimizely Web Experimentation or Feature Experimentation with the JavaScript SDK, see Segment’s Optimizely Web destination, which supports:

Optimizely Web Experimentation

Optimizely Full Stack (JavaScript)

Implementation prerequisite

For the integration to work, you will need to implement some of the Feature Experimentation functionality before the rest of the integration work.

Although Segment maps track events to the Optimizely Track method, customers must implement all decision-based methods, such as the Is Feature Enabled method, 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 Feature Experimentation experiments run.

Server Side

Get Started

1. In your Segment source dashboard, enable the “Optimizely Full Stack” destination (not the “Optimizely Web” destination).
2. Include your Feature Experimentation project’s projectId and datafile URL in your Segment settings.
3. Create a native Optimizely instance in your server environment so you can access methods like Is Feature Enabled and so on.
4. Finally, define any metrics and attributes in your Optimizely dashboard, and to associate metrics with the appropriate 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.

📘

Note

If you are using Full Stack Legacy SDKs from before 2019: if a visitor has any activate or isFeatureEnabled calls, their attributes object for these calls must match the attributes object passed to any track calls for that user id so that it can be correctly attributed on the Optimizely results page.

For information, see the Event API documentation. Configuration does not require maintaining the attributes of a user as long as the user id stays the same between decision-based methods, such as the Is Feature Enabled method, and Segment track calls to have metrics populated in the Optimizely results page. If you would like to segment your results by user attribute, then ensure the attributes passed in for the decision-based calls match the attributes passed in for the track calls for that user id.

For more details on how events are attributed on the Optimizely results page, see the documentation, Count conversions.

Example implementation

See the following example code for instructions on integrating the JavaScript SDK with your Segment analytics.

//Node server-side example

const optimizelySdk = require('@optimizely/optimizely-sdk');
const optimizelyEnums = require('@optimizely/optimizely-sdk').enums;
const Analytics = require('analytics-node');

const analytics = new Analytics('YOUR_WRITE_KEY');
const optimizely = optimizelySdk.createInstance({
  sdkKey: '<Your_SDK_Key>',
});

const segmentDecision = (decisionObject) => {
  const type = decisionObject.type
  //When a decision is generated by a Feature Flag, dispatch an event named Feature Flag, with properties denoting the feature key and other decision information
  if (type == "feature") {
    const info = decisionObject.decisionInfo;
    const featureKeyString = info.featureKey;
    const enabled = info.featureEnabled;
    const attributes = decisionObject.attributes;
    analytics.track('Feature Flag', {
      "key": featureKeyString,
      "enabled": enabled,
      info,
      attributes
    });
    //If the Feature Flag decision is a result of a feature test, dispatch an additional Experiment Viewed semantic event (https://segment.com/docs/connections/spec/ab-testing/)
    if (info.source == "feature-test") {
      const experimentKeyString =info.sourceInfo.experimentKey;
      const experimentVarString = info.sourceInfo.variationKey;
      analytics.track('Experiment Viewed', {
        'experiment_name': experimentKeyString,
        'variation_name': experimentVarString
      })
    }
  }
}

const listenerId = optimizely.notificationCenter.addNotificationListener(
  optimizelyEnums.NOTIFICATION_TYPES.DECISION,
  segmentDecision,
);

Track

Upon invocation of a Segment track event, Segment maps the event to an Optimizely Track event. To ensure that attribution of experiment views and events are consistent, ensure the same ID is used for decision-based calls, such as the Is Feature Enabled calls.

• If the Segment event name matches exactly the name of an active experiment metric configured in the Optimizely dashboard;
• If the experiment metric is associated with a running experiment;
• If the current user has been assigned a userId through Segment’s identify method (for example, 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.

📘

Note

Custom Event Tags, which includes any Event Tag outside of revenue or value, will not be displayed on the Optimizely results page but they will be available in a Data Export report.

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. You may optionally fall back to anonymousId when userId is unavailable by setting fallbackToAnonymousId to true.

Android Cloud-mode Implementation

Get Started

• In your Segment source dashboard, enable the “Optimizely Full Stack” destination (not the “Optimizely Web” destination).
• Include the latest version of the Feature Experimentation native SDK in your app-level build.gradle file and implement Optimizely as you would natively.
• Finally, define any metrics and attributes in your Optimizely dashboard and to associate metrics with the appropriate experiments. Segment maps track event names to Optimizely eventName, which corresponds to an experiment metric. In addition, Segment maps identify traits to Optimizely attributes.

When implementing Feature Experimentation through cloud-mode, Segment will map track events to Optimizely track events on Optimizely's servers and deliver the data to your project as usual.

📘

Note

Using Optimizely SDKs v1.x or v2.x require teams to maintain attributes that are passed in for a user with any Activate or Is Feature Enabled call to any track made for that user id to be attributed on the results page.

For more details on how events are attributed on the Optimizely results page, refer to the documentation, Count conversions.

Example implementation

Segment has a semantic event that you can use to track A/B test variations for users.

The following example code adds a notification listener block callback to send Segment's A/B event.

import com.segment.analytics.Analytics;
import com.segment.analytics.Properties;


OptimizelyClient optimizelyClient = optimizelyManager.getOptimizely();
// Add a Activate listener
int notificationId = optimizelyClient.getNotificationCenter().addNotificationListener(NotificationCenter.NotificationType.Activate, new ActivateNotificationListener() {
  @Override
  public void onActivate(Experiment experiment, String userId, Map<String, ?> attributes, Variation variation, LogEvent event) {

    String experimentId = experiment.getId();
    String experimentKey = experiment.getKey();
    String variationId = variation.getId();
    String variationKey = variation.getKey();

    Properties properties = new Properties();
    properties.put("experimentId", experimentId);
    properties.put("experimentName", experimentKey);
    properties.put("variationId", variationId);
    properties.put("variationName", variationKey);

    Analytics.with(getApplicationContext()).track("Experiment Viewed", properties);

  }
});

#import <Analytics/SEGAnalytics.h>
  
NSString *notificationId = [self.optimizely.notificationCenter addDecisionNotificationListenerWithDecisionListener:^(NSString *type, NSString *userId, NSDictionary<NSString *,id> *attributes, NSDictionary<NSString *,id> *decisionInfo) {
       NSDictionary *properties = @{
           @"type" : type,
           @"userId" : userId,
           @"attributes" : attributes,
           @"decisionInfo" : decisionInfo
           };
       [[SEGAnalytics sharedAnalytics] track:@"Experiment Viewed" properties:properties];
}];

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 configure in the Optimizely dashboard;
• If the experiment metric is associated with a running experiment;
• 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. You may optionally fall back to anonymousId when userId is unavailable by setting fallbackToAnonymousId to true.

Identify

Invoking a Segment identify event sets Segment traits as Optimizely 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.

iOS Cloud-mode Implementation

Get Started

• In your Segment source dashboard, enable the “Optimizely Full Stack” destination (not the “Optimizely Web” destination).
• Include the latest version of the Feature Experimentation native SDK in your app and implement it as you would natively.
• Finally, define any metrics and attributes in your Optimizely dashboard and to associate metrics with the appropriate experiments. Segment maps track event names to Optimizely eventName, which corresponds to an experiment metric. In addition, Segment maps identify traits to Optimizely attributes.

When implementing Feature Experimentation through cloud-mode, Segment will map track events to Optimizely track events on Optimizely's servers and deliver the data to your project as usual.

📘

Note

Using Optimizely SDKs v1.x or v2.x require teams to maintain attributes that are passed in for a user with any Activate or Is Feature Enabled call to any track made for that user id to be attributed on the results page.

For more details on how events are attributed on the Optimizely results page, see the documentation, Count conversions.

Example implementation

Segment has a semantic event that you can use to track A/B test variations for users.

The following example code adds a notification listener block callback to send Segment's A/B event.

import Analytics

let notificationId = optimizely.notificationCenter.addDecisionNotificationListener(decisionListener: { (type, userId, attributes, decisionInfo) in
    let properties: [String: Any] = ["type": type,
                    "userId": userId,
                    "attributes": attributes!,
                    "decisionInfo": decisionInfo]

  SEGAnalytics.shared()?.track("Experiment Viewed", properties: properties)

})

#import <Analytics/SEGAnalytics.h>
  
NSString *notificationId = [self.optimizely.notificationCenter addDecisionNotificationListenerWithDecisionListener:^(NSString *type, NSString *userId, NSDictionary<NSString *,id> *attributes, NSDictionary<NSString *,id> *decisionInfo) {
       NSDictionary *properties = @{
           @"type" : type,
           @"userId" : userId,
           @"attributes" : attributes,
           @"decisionInfo" : decisionInfo
           };
       [[SEGAnalytics sharedAnalytics] track:@"Experiment Viewed" properties:properties];
}];

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 configured in the Optimizely dashboard;
• If the experiment metric is associated with a running experiment;
• 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. You may optionally fall back to anonymousId when userId is unavailable by setting fallbackToAnonymousId to true.

Identify

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

Personas

Follow the instructions on Using Segment Personas and Optimizely Full Stack for Omnichannel Experiments.

GDPR Support

Segment supports deleting/suppressing users in Optimizely through the Segment app. To do this, however, you will need to create a Personal Access Token in Optimizely and provide it as the value of the Access Token setting.

Supported Sources and Connection Modes

The first step is to verify that Feature Experimentation supports the source type and connection mode you have chosen to implement. For information about connection modes that Feature Experimentation supports, refer to the Segment documentation.

Segment offers an optional Device-based Connection Mode for Mobile data going to Feature Experimentation so that you can use features that collect data directly from the mobile device. To do this, you must package the Segment-Optimizely Full Stack mobile SDK with the Segment mobile SDK.

Settings

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

Account ID

To use Optimizely through server side, you must enter your Account ID from your Optimizely account. You can find this ID by visiting app.optimizely.com/v2/accountsettings/account-number/plan

Cache Expiration

To optimize the server-side integration, Optimizely caches 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

To use Optimizely server side, you must enter the entire URL for your datafile, like: <https://cdn.optimizely.com/json/9218021209.json>.

Fall Back To Anonymous Id

Optionally fall back to anonymousId when userId is not present.

Only Track Known Users

Feature Experimentation 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.

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 is triggered each time you access an Optimizely live variable. If you are regularly accessing live variables and want to reduce the number of track events triggered, pass the “false” flag, for example the Android library would be:

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

And for iOS:

let myVariable = try? optimizely.getFeatureVariableBoolean(featureKey: "", variableKey: "", userId: "")

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

Send Experiment Viewed as a non-interaction event

Use Optimizely SDKs v3+

Enable this setting to instantiate an Optimizely client using v3.2.2 of the SDK. The default client version Segment instantiates is v2.1.3.

📘

Note

Do not enable this setting if the SDK version you are using to activate users into your Optimizely experiments is less than version 3.0. You can find information on how migrating from Optimizely 2.x to 3.x will affect your experiment tracking in the documentation.

Use Optimizely User ID

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

Use User ID

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

Add Feature Experimentation to the integrations object

To add Feature Experimentation to the integrations JSON object (for example, to filter data from a specific source), use one of the following valid names for this integration:

• Optimizely X
• Optimizely Full Stack