Getting started with Optimizely's Classic Android SDK

Optimizely Classic will sunset on September 30, 2018. Please transition to Optimizely X Full Stack. Have questions? Our support team is here to help.

SDK Download

You can download the Android SDK through gradle or install it through Fabric.

JAR | GitHub

Releases | Change History

Android SDK Install Video

1. SDK Installation

To use Optimizely for Android you must first integrate the SDK into your app using Gradle.

We strongly recommend using a version control system (such as Git) and checking in your app before installing Optimizely.

Using Gradle

Your project must be set up to build with Gradle. Refer to Gradle Getting Started if you haven't yet configured your project to work with Gradle.

Our SDK only supports Android API 14 (Ice Cream Sandwich) and above, so please make sure your build.gradle specifies a minimum sdk of 14 (or above). Then, add the Optimizely-Android-SDK repository as a maven repository to your project's top-level build.gradle file:

allprojects {
  repositories {
    maven {
      url ''

Make sure you add the repository to the allprojects configuration, not the buildscript configuration.

Then, add Optimizely as a dependency in your app's build.gradle:

dependencies {
    compile('com.optimizely:optimizely:+@aar') {
        transitive = true

2. Create an Android Project

To create an Android project, select "New Project" from the left drawer in your Optimizely Home:

Create Project Dialog

Once you've created a project, please take a look at the Implementation section under the Settings tab to find your project ID and API key which you will use during integration:

Project Code Dialog

3. Activate Optimizely

Now, you're ready to add some code so your app can connect with your Optimizely account.

Optimizely assigns each project a unique identifier known as an API token. Your app identifies itself to the Optimizely Android SDK by initializing the SDK with this token.

Open the Java source file corresponding to your app's main activity (the one declared as a launcher activity in your AndroidManifest.xml), and add the following import:

  import com.optimizely.Optimizely;

Add the following to the end of your main activity's onCreate() function. The code can be copied from your Implementation Settings, which you can find by selecting on the appropriate Android Project in your Optimizely Home. For more details, you can refer back to Step 2: Create an Android project.

Optimizely must be started from your main launcher activity's onCreate() method. Starting anywhere else, such as Application#onCreate() will not be supported and may lead to unpredictable behavior.
protected void onCreate(Bundle savedInstanceState) {

    // more create logic

    // Crash reporting tool initialization

    // You can find the following code snippet in your project code.
    Optimizely.startOptimizelyWithAPIToken("<API Token>", getApplication());

This call will block until Optimizely is started. For a non-blocking call, use the following version which takes a callback listener as the third argument. If you are not interested in the callback, you can pass in null:

private static void mOptimizelyEventListener = new DefaultOptimizelyEventListener() {
    @Override onOptimizelyStarted() {}
    @Override onOptimizelyFailedToStart(String message) {}

protected void onCreate(Bundle savedInstanceState) {
    // More startup code here
    Optimizely.startOptimizelyAsync("<API Token>", getApplication(), mOptimizelyEventListener);

Note: startOptimizelyAsync must be initialized on the UI (main) thread to coordinate with the activity lifecycle.

Optimizely needs to connect to the internet to allow you to use our online editor and to download new experiments once you've published them. If you don't already have the INTERNET permission declared in your AndroidManifest.xml, you will need to add the following permission line:

 <uses-permission android:name="android.permission.INTERNET" />

For more information on Android permissions, see the Android Manifest Intro.

Starting with version 1.1, Optimizely's Android SDK uses a unique URL scheme handler to help you edit and test your experiments.

Add the following intent filter to the MainActivity entry of your AndroidManifest.xml

       <!-- Existing intent-filters -->
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />
       <data android:scheme="optly[PROJECT_ID]" />

Note: The scheme includes a unique identifier. Be sure to replace [PROJECT_ID] with your project id (e.g. optly123456). Also, we recommend that url handlers are not registered in the production version of your app. You should only register it in the AndroidManifest.xml in the src/debug source set. This way browsing to a short link to enter edit and preview mode will only work for your debug builds.

At this point you should run your application to register the SDK installation. The Optimizely SDK will register itself in the background. You will see your project overview display light up, allowing you to create an experiment:

<img src="/assets/img/android/sdk-detected.png", style="width: 70%"/>

4. Create an Experiment

After creating an Android project and installing the SDK, click the Create Experiment button in the upper right hand side of your project overview.

Custom View Tagging

The Optimizely Android SDK identifies Views within your application using the view hierarchy of the view-- in some cases you may need to specify your own ID or mark a specific view in a collection view as unique.

See this section on configuring the visual editor.

5. QA

Preview Mode

Preview mode allows you to force your app into a certain variation for a given experiment in order to check that your app and the experiment are both running smoothly. To enter preview mode, connect your device to the editor, select your desired variation, open the variation settings drawer, and click Preview

Enter Preview Mode

Programmatically Enable Preview Mode

While preview mode can be enabled from the dashboard it can also be enabled from code. This allows you to preview variations across all of your experiments without needing to connect to the editor. Preview mode has UI that allows you easily switch variations and view event logs.

Optimizely.startOptimizelyWithAPIToken(getOptimizelyToken(), getApplication());

Pre-launch Checklist

Now that you've created an experiment and successfully installed the Optimizely Android SDK, below is a checklist to go through prior to releasing your app to the app store with the SDK:

  1. In order to set up your app such that you can QA experiments (beyond using Preview), we recommend either having a separate Project for development and production or inserting Custom Tags, which are only set for certain QA devices. If you decide to go with setting up 2 separate projects, we recommend setting up an if (DEBUG) to ensure that only one project code snippet is defined at any given time.

  2. Were you able to connect to Optimizely's Visual Editor? Before your release to the app store, you will want to make sure that Optimizely.setEditGestureEnabled(false) is called before Optimizely.startOptimizelyWithAPIToken.

  3. (Optional) If you have a separate project for development and production, you can run your experiments in your development environment to check that results are updating and that you are seeing the different variations are being seen.

    • A useful debugging tool is to enable logging (be sure to disable this feature when your app is live in the Play Store) Optimizely.setVerboseLogging(true); For each event that is triggered, you will see a log statement. Be sure to check that verboseLogging is not enabled in production.
    • You will want to make sure that each experiment does not make changes to the same element (otherwise only one of the experiments will run).
    • Optimizely tracks unique visitors, so that we make sure that the same user sees the same experience. If you would like to check that you are getting a random experience, you will need to delete the app to be counted as a new visitor.
    • By default, Optimizely sends network calls every 2 minutes or upon backgrounding. (You can find more details about modifying the SDK network settings here). In order to check that your event data is being updated in the Optimizely Results Page as expected, you can either:
      1. Trigger events in the app and keep the app foregrounded for 2 minutes
      2. Background the app so that events are sent to our servers.
  4. Once you've checked all these steps, you're ready to release to the Play Store!

Advanced Setup

Once you have run your first few visual editor experiments or tried out Optimizely's SDK, you may find you would like to include programmatic experiments, additional tracking calls, or analytics integrations. For advanced setup, below are a subset of advanced features we recommend utilizing prior to releasing to the Play Store:

  1. Live Variables
  2. Code Blocks
  3. Custom Tags
  4. Track Event (for key metrics you would like to track in your app)
  5. Revenue Tracking
  6. Analytics Integration
  7. Optimizely Event Listeners

For a comprehensive list of all additional methods available in the SDK you can refer to the Reference section or the Java Docs.