Optimizely will be sunsetting Full Stack Experimentation on July 29, 2024. See the recommended Feature Experimentation migration timeline and documentation.

Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket
These docs are for v2.0. Click to read the latest docs for v3.0.

Initialize a mobile SDK

In our iOS and Android SDKs, you don't need to manage the datafile directly. These SDKs have an additional abstraction called a manager that handles getting the datafile and instantiating the client for you during the SDK's initialization process. The manager includes:

  • A built-in User Profile Service for storing variation assignments on the device.
  • A built-in event dispatcher for sending events in the background. It also retries sending using exponential backup if it fails.
  • Support for datafile polling to automatically update the datafile on a regular interval while the application is in the foreground.

The manager is implemented as a factory for Optimizely client instances. To use it:

  1. Create a manager object by supplying your SDK Key and optional configuration settings for datafile polling and datafile bundling. You can find the SDK key in the Settings > Environments tab of a Full Stack project.



Earlier versions of the SDK used a project ID rather than an SDK Key to create a manager. Project IDs are still supported in 2.x for backwards compatibility. If you supply a project ID, the SDK retrieves the primary environment's datafile. We recommend using SDK keys because they enable you to retrieve datafiles for other environments.

  1. Choose whether to instantiate the client synchronously or asynchronously and use the appropriate initialize method to instantiate a client.
// In your Application#onCreate

import com.optimizely.ab.android.sdk.OptimizelyManager;
import com.optimizely.ab.android.sdk.OptimizelyClient;
import com.optimizely.ab.android.sdk.OptimizelyStartListener;
import com.optimizely.ab.config.Variation;

// Build a manager
OptimizelyManager optimizelyManager = OptimizelyManager.builder()
    .withEventDispatchInterval(60L * 10L)
    .withDatafileDownloadInterval(60L * 10L)

// Instantiate a client synchronously with a bundled datafile
OptimizelyClient optimizelyClient = optimizelyManager.initialize(this, datafile);

// Or, instantiate it asynchronously with a callback
optimizelyManager.initialize(this, null, new OptimizelyStartListener() {
    public void onStart(OptimizelyClient optimizelyClient) {
        // Activate experiments
        Variation variation = optimizelyClient.activate("experimentKey", userID);
// In AppDelegate.m
#import <OptimizelySDKiOS/OptimizelySDKiOS.h>

// Build a manager
OPTLYManager *manager = [[OPTLYManager alloc] initWithBuilder:[OPTLYManagerBuilder  builderWithBlock:^(OPTLYManagerBuilder * _Nullable builder) {
        builder.sdkKey = @"SDK_KEY_HERE";

// Instantiate a client synchronously using cached datafile
OPTLYClient *client = [manager initialize];
OPTLYVariation *variation = [client activate:@"experimentKey"

// Or, instantiate it asynchronously with a callback
[manager initializeWithCallback:^(NSError * _Nullable error,
                                  OPTLYClient * _Nullable client) {
  OPTLYVariation *variation = [client activate:@"experimentKey"
// In AppDelegate.swift
import OptimizelySDKiOS

// Build a manager
let optimizelyManager = OPTLYManager(builder: OPTLYManagerBuilder(block: { (builder) in
            builder?.sdkKey = "SDK_KEY_HERE"
// Synchronously initialize the client, then activate an experiment
let optimizelyClient : OPTLYClient? = optimizelyManager?.initialize(withDatafile:jsonDatafile!)
let variation = optimizelyClient?.activate("experimentKey",

// Or, instantiate it asynchronously with a callback
optimizelyManager?.initialize(callback: { [weak self] (error, optimizelyClient) in
  let variation = optimizelyClient?.activate("experimentKey",

For full examples, see:

Get a Client

Each manager retains a reference to its most recently initialized client. You can use the getOptimizely function to return that instance.

If this method is called before any client objects have been initialized, a dummy client instance is created and returned. This dummy instance logs errors when any of its methods are used.

OptimizelyClient optimizelyClient = optimizelyManager.getOptimizely();
let optimizelyClient = [manager getOptimizely];
let optimizelyClient = optimizelyManager?.getOptimizely();