Skip to main content

Everything you need to switch from Optimizely Classic to X in one place: See the Optimizely X Web Transition Guide.

Optimizely Knowledge Base

Make the transition to Optimizely X Full Stack

relevant products:
  • Optimizely Classic Mobile
  • Optimizely X Full Stack

  • Switch to the new Optimizely X Full Stack SDKs from the Optimizely Classic Mobile

Optimizely X Full Stack introduces new SDKs and fresh user interface for experimentation in native iOS and Android apps.

This article will help you decide whether to switch to Optimizely X Full Stack if you've been using Optimizely Classic Mobile. It'll also guide you through how to recreate existing experiments from Classic in X.

Not sure which product you're using? Here's how to figure out.

See additional resources
Here are all our articles about the Optimizely dashboard, which you'll use to create projects, add collaborators, manage privacy settings, and more: 

Here's our developer documentation, where you'll find code samples, full references for our SDKs, and getting started guides.

Wondering what's changed? If you've been using Optimizely Classic Mobile, check out this article to compare our legacy product to Optimizely X Full Stack.

Learn more about the advantages of Optimizely X Mobile on our blog.

Deciding to switch

Optimizely X is our new experimentation platform that's designed to empower companies to experiment everywhere. With Optimizely X, we've released a family of products that help you experiment across channels and devices.

In response to customer feedback, we've designed Optimizely X Full Stack for app development teams and included many advanced features to give developers full control over experiments. Read this article to learn more about what's new in Optimizely X Full Stack.

We highly recommend that all customers switch to Optimizely X as soon as possible. Currently, we continue to support Optimizely Classic Mobile but our development resources are focused on Optimizely X going forward. Start developing mobile experiments with our new SDK to gain the control, ease of use, and multi-channel experimentation potential of Optimizely X.

Who should wait to switch?

There are some features in Classic that aren't yet available in Optimizely X Full Stack. Some have been deprecated and others are still in development. Read the comparison article to learn what's being deprecated or developed. If your team's experimentation depends on these features, you may want to wait.

If your team blocked by features that aren't yet available, please contact the Optimizely Support team or your Customer Success Manager.

1. Create a mobile project in Optimizely X

First, create a new SDK project in Optimizely X. We redesigned Optimizely from the ground up, and have decided not to port Classic iOS and Android projects into X, since functionality differs.

Creating a new project is simple and will help you make a smooth transition with the our new SDKs.

You must be an Optimizely administrator to have permissions to create a new project.

Here's how to set up a new SDK project:

  1. Make sure Optimizely X is enabled. If you don't see a link in your account, contact Optimizely Support or your CSM.

    Click Optimizely X to switch.

  2. Click Create Project (or Switch Project) > New Project.

  3. Under Mobile, select iOS Project or Android Project.

If you have multiple mobile projects in Optimizely Classic, create a new SDK project in Optimizely X for each of your existing projects.  For example, if you have two iOS apps and one Android app, create three new SDK projects. And if each of those apps has a QA and a production environment, create six new projects.

You can use the same naming conventions for projects in Optimizely X as you used in Classic.

If you have questions or need help, contact Optimizely Support or email our developer support staff at

2. Install the Optimizely X SDK

Before moving over any of your existing production experiments, install the new iOS or Android SDK and set up an experiment in your development environment.  Here are two guides that walk through how to install the SDK and run a basic experiment:

Our SDKs include a demo app that shows an example usage of the SDK.

3. Update references to the Optimizely SDK in your app

The Optimizely X SDKs are not backwards compatible with the Optimizely Classic SDKs. So, you'll need to update references for the Optimizely Classic SDK for Optimizely X.

  1. Before updating any references, stop all running experiments with Optimizely Classic and wait for your experiment results to conclude.  This will ensure that future app releases won't affect your pre-existing experiment results.

  2. Once you're ready for a new app release, you’ll want to update any of the following references in the SDK:

    Initialization. Instead of usingstartOptimizely to synchronously or asynchronously load Optimizely in your app, create an OptimizelyManagerthat manages the state and synchronization of the datafile with your app. Refer to our developer documentation on syncing the datafile for iOS and Android.

    Live Variables. If you've defined live variables in your app that you’d like to use for future experiments in Optimizely X, use our updated function signatures for variable getters. Please refer to our developer documentation for iOS and Android to learn how to access live variables using the SDK. Any live variables you’ve added to the app will also need to be registered in your new Optimizely X project.

    Metrics. In Optimizely Classic, you can create custom goals for any events you track in the app.  In Optimizely X, goals have been replaced by events (for tracking), which are aggregated into metrics on your Results page (for display). Refer to our developer documentation for iOS and Android to learn how to track events from your app. You’ll also need to register events in your new Optimizely X project.

All other references to the Classic SDK can be safely removed.

3. Remove other references to Classic SDK in your app

All of the code for below should be removed from your app as these concepts no longer apply in Optimizely X:

  • Preview mode

  • Editor mode

  • Code blocks

  • Custom tags

  • Integrations

After removing these references you should be able to compile your app without the Optimizely Classic SDK installed.

4. Deploy your first experiment in Optimizely X

You’re now ready to run your first experiment in Optimizely X, using any live variables and metrics you’ve ported over from above.  

Refer to our developer reference on iOS and Android. Or, read our guide to getting started with Optimizely X to learn about configuring experiments.