Skip to main content


Optimizely Knowledge Base

Upgrade to version 2.x of Android, iOS, and tvOS SDKs

  • Compare versions 1.x and 2.x of Optimizely’s iOS and Android SDKs
  • Upgrade from version 1.x to 2.x SDKs

Version 2.x of Optimizely’s Android, iOS, and tvOS SDKs introduces a number of significant changes. Here’s an overview of what’s new:

  • Feature Management decouples code deploys from launches so you can safely launch new features to a subset of your users. Roll out new features and monitor them. Roll back features with a toggle control if unanticipated issues arise.

  • Feature tests allow you to integrate experimentation into product development. Deploy new features behind a feature flag, then use the flag to trigger tests. Experiment with different feature configurations and show them to users without deploying code.

  • Environments allow you to QA more effectively. Run a single experiment in one environment so your team can QA but leave it turned off for users.

  • iOS, Android, tvOS, Android TV, and Full Stack are consolidated to use a shared project interface. If Full Stack or tvOS and Android TV is part of your account, you can now create Full Stack project, then use that project with any combination of SDKs. You can convert existing projects to the new UI after you discontinue use of variables.

  • Variables are deprecated and replaced by feature variables. Feature variables are scoped to a feature, and their values are set using feature rollouts and feature tests.

We recommend that you create a new project and upgrade your SDK to version 2.x or higher to use the new features above. If you do so, you won't have access to live variables in the new project. To keep using live variables, run your experiments in your existing Mobile project.

Version 2.x introduces a few small breaking changes, which you may need to address when upgrading from 1.x SDKs. See the release notes

Upgrade a new project

To upgrade to a 2.x SDK project, no special steps are required aside from installing the new SDK:

  1. Install the 2.x SDK in the language of your choice.

  2. Create a Full Stack project.

  3. Create Full Stack experiments.

If your account includes Full Stack, your Create Project modal will look like this:


If your account has access to Mobile projects only, you may see grayed out icons.

Upgrade an existing project

If you’re an existing Mobile project user, you'll need to upgrade to use new features such as environments and feature management. First, make sure that you’re using the latest version of your Optimizely SDK. To take advantage of the new features, you’ll need to complete two steps:

  1. Pause and archive all experiments that use live variables. Instead, use feature variables, which allow you to use feature tests and feature rollouts.

  2. Contact your Customer Success Manager or file a support ticket. After we verify that your project is ready to be converted, we’ll migrate you to the new UI.

After you upgrade, learn about Feature Management and read our developer documentation to learn about associated APIs.