The Full Stack Developer Guide Developer Hub

Welcome to the Full Stack Developer Guide developer hub. You'll find comprehensive guides and documentation to help you start working with the Full Stack Developer Guide as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Define audiences and attributes

You define which types of users to include in an Experiment or Rollout using the Audiences feature in the Optimizely UI to create an audience. In an Audience, you can describe which users to include based on custom attributes like their location, device type, or subscription plan. After creating an Audience, you can go to an A/B Test, Feature Test, or Feature Rollout and set all target audiences for that particular experiment.

A single Audience is defined based on user attributes. These attributes are properties of a user that you pass in when calling APIs like Activate or Is Feature Enabled. When you pass attribute values, Optimizely uses them to determine whether the user qualifies for an experiment or feature. For more information, see Target Your Visitors.

For information on using attributes from other analytics platforms, see Integrate analytics platforms: Audiences.

Create an attribute

Use attributes to build the audiences that see your experiments, and use the Attributes tab to manage all your user attributes. In Full Stack, you can have up to 100 attributes.

To create a new attribute:

  1. Navigate to Audiences > Attributes.
  2. Click New Custom Attribute.
  3. Enter a key for the attribute.
    Attribute keys must be unique within your project. For example, an attribute for visitors located in the United States might be called "US_VISITOR". You can pass attributes to the Full Stack SDK in your code, so always make sure to update your code with any changes made to your keys.
  4. Click Save.

Create an audience

After you've created a few attributes, you can start building audiences. Audiences help you target your experiments to certain groups of users. You can reuse audiences that you've created across multiple experiments, but they’re limited to each Full Stack project.

Full Stack v3.0 supports several match types that you can use in audience conditions:

  • has any value
  • String equals
  • String contains substring
  • Boolean is false
  • Boolean is true
  • Number equals
  • Number is less than
  • Number equals
  • Number is greater than

The Edit Audience window lets you define audience conditions by either dragging and dropping attributes from the right side pane or defining complex JSON objects using the Code Mode window.

To drag and drop attributes:

  1. Navigate to Audiences > Saved.
  2. Click Create New Audience.
  3. Drag and drop the desired attributes into the Audience Conditions field.
    For example, to create an audience of visitors who are located in the US, based on specific location values, add the "LOCATION" attribute.
  4. Define the attributes.
    Add other attributes to help create your audience. They can be can be added as "and" or "or" conditions. Note: When you choose any match type option other than String equals for exact matching, a message displays that the option requires using an SDK version of 3.0, at minimum.
  5. Click Save Audience.

To use Code Mode to create a custom JSON object:

  1. Create a new audience or select an existing audience to edit. The Edit Audience window appears.
  2. Click Code Mode to access the Edit Code Mode window.
  3. Create the necessary JSON object for your use case. For more information, see Audience Conditions.
  4. Clear the Code Mode checkbox to exit the editing mode.

Pass in attributes

You can pass strings, numbers, booleans, and null as user attribute values in a 3.0 SDK.

When you pass attribute values to an SDK method, if the method tracks an impression or conversion event, then that event becomes available for audience evaluation and results segmentation. The Track method always sends a conversion event. Manage impressions explains when methods may send impression events.

If an event is tracked, the user attribute values from that event can also be used to segment other events from the user's current session, as well as events that the user generates in future sessions. (For more details, learn how Optimizely counts conversions: filtering by segment.) This may be helpful if the user visits parts of your ecosystem where you may want to activate experiences or track events but where you don't have all the user's attribute values. However, you should pass user attributes whenever possible.

The examples below show how to pass in attributes. The Android, Java, JavaScript and Objective-C examples show passing in string, number, and boolean attributes to the 3.0 SDKs.

import com.optimizely.ab.config.Variation;

Map<String, Object> attributes = new HashMap<>();
attributes.put("device", "iPhone");
attributes.put("lifetime", 24738388);
attributes.put("is_logged_in", true);

// Activate an A/B Test
Variation variation = optimizelyClient.activate(experimentKey, userId, attributes);
// Track an event
optimizelyClient.track(eventKey, userId, attributes);
using OptimizelySDK;
using OptimizelySDK.Entity;

var optimizelyClient = new Optimizely(datafile);
var experimentKey = "app_redesign";
var userId = "userId";

UserAttributes attributes = new UserAttributes
{
  { "DEVICE", "iPhone" },
  { "AD_SOURCE", "my_campaign" }
};

// Conditionally activate a test for the provided user
Variation variation = optimizelyClient.Activate(experimentKey, userId, attributes);
import com.optimizely.ab.config.Variation;

Map<String, Object> attributes = new HashMap<>();
attributes.put("device", "iPhone");
attributes.put("lifetime", 24738388);
attributes.put("is_logged_in", true);

// Activate an A/B Test
Variation variation = optimizelyClient.activate(experimentKey, userId, attributes);
// Track an event
optimizelyClient.track(eventKey, userId, attributes);
var attributes = {
  device: 'iPhone',
  lifetime: 24738388,
  is_logged_in: true,
};

// Activate an A/B Test
var variation = optimizelyClient.activate(experimentKey, userId, attributes);
// Track an event
optimizelyClient.track(eventKey, userId, attributes);
// Conditionally activate an experiment for the provided user
var variation = optimizelyClient.activate("my_experiment", userId, {
  plan_type: "silver"
});

var isDiscountEnabled = optimizelyClient.isFeatureEnabled(
  "product_discount",
  userId,
  { plan_type: "silver" }
);
NSDictionary *attributes = @{
  @"device": @"iPhone",
  @"lifetime": @24738388,
  @"is_logged_in": @true
};

OPTLYVariation *variation = [optimizely activate:experimentKey,
                                          userId:userId,
                                      attributes:attributes];
$experimentKey = 'my_experiment';
$userId = 'user123';
$attributes = [
    'device' => 'iphone',
    'ad_source' => 'my_campaign'
];

// Conditionally activate the experiment for the provided user
$variation = $optimizelyClient->activate($experimentKey, $userId, $attributes);
# Conditionally activate an experiment for the provided user
variation = optimizely_client.activate(
  'my_experiment',
  'user123',
  {'plan_type': 'silver'}
)

# Conditionally toggle a feature for the provider user
is_discount_enabled = optimizely_client.is_feature_enabled(
  'product_discount',
  'user_123',
  {'plan_type': 'silver'}
)
experiment_key = 'my_experiment'
user_id = 'user123'
attributes = {'DEVICE' => 'iPhone', 'AD_SOURCE' => 'my_campaign'}

# Conditionally activate a test for the provided user
variation = optimizely_client.activate(experiment_key, user_id, attributes)
let attributes = ["device" : "iPhone", "ad_source" : "my_campaign"]

let variation: OPTLYVariation? = optimizely?.activate("my_experiment", userId:"user123", attributes:attributes)

Important

During audience evaluation, note that if you don't pass a valid attribute value for a given audience condition—for example, if you pass a string when the audience condition requires a boolean, or if you simply forget to pass a value—then that condition will be skipped. The SDK logs will include warnings when this occurs.

Differences between 3.0 SDKs and prior versions

Only the 3.0 SDKs can activate audiences that use match types other than String equals. The v1.x and v2.x SDKs only allow you to pass in string values and compare them using the String equals match type. An audience that uses any other match type can't be activated by the 1.x and 2.x SDKs. An experiment or feature that is targeted to such an audience can only be activated if it is also targeted to a different, backwards-compatible audience.

You can pass numeric, boolean, and null attribute values only to the 3.0 SDKs. If you pass a null value or a non-string value for a custom attribute in a 1.x or 2.x SDK, your code may or may not compile. If it does run, audience evaluation is negatively affected and conversions and impressions are lost.

You can always pass string attribute values to any SDK version.

Audience conditions that rely on unknown attribute values are handled differently. Audience conditions that use does not match negation are handled differently between the 1.x and 2.x SDKs and the 3.0 SDKs.

The image shows an example of a custom attribute device being targeted with does not match. If you pass a value like "Android" or "iPhone" for this attribute, the negation in the condition ensures that the condition passes or fails, respectively. However, if you pass an invalid (null, non-string, or empty) attribute in this scenario:

  • The 1.x and 2.x SDK negation logic allows the overall condition to pass, which may result in audience activation.
  • The 3.0 SDKs determine that the condition can't be evaluated and consequently won't use it to activate the audience.