2. Create an Android Project

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

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:

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.

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:

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:

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.

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

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.

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:

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.

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.

(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:

Trigger events in the app and keep the app foregrounded for 2 minutes

Background the app so that events are sent to our servers.

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: