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.

Install the SDK

Follow the installation instructions below for your platform and language.


The C# SDK is distributed through NuGet. To install, run the command Install-Package Optimizely.SDK in the Package Manager Console.

The full source code is at https://github.com/optimizely/csharp-sdk.


The Java SDK is distributed through Bintray. The core-api and httpclient Bintray packages are optimizely-sdk-core-api and optimizely-sdk-httpclient, respectively. You can find repository information and also instructions on how to install the dependencies on Bintray. Gradle repository and dependency configurations are shown on the right. The SDK is compatible with Java 1.6 and above.

core-api requires org.slf4j:slf4j-api:1.7.16 and a supported JSON parser. We currently integrate with these parsers (listed in their selection order priority):

  1. Jackson
  2. GSON
  3. json.org
  4. json-simple

If more than one of these parsers are available at runtime, the core-api chooses one for use per the selection order priority. If none of these packages are already provided in your project's classpath, you must add one.

core-httpclient-impl requires org.apache.httpcomponents:httpclient:4.5.2 and provides an asynchronous event dispatcher that is described in Configure the event dispatcher. This library isn't required and you may provide a custom EventHandler implementation that uses a different networking stack.

repositories {

dependencies {
  compile 'com.optimizely.ab:core-api:2.0.1'
  compile 'com.optimizely.ab:core-httpclient-impl:2.0.1'

  // The SDK integrates with multiple JSON parsers. Here, we use Jackson.
  compile 'com.fasterxml.jackson.core:jackson-core:2.7.1'
  compile 'com.fasterxml.jackson.core:jackson-annotations:2.7.1'
  compile 'com.fasterxml.jackson.core:jackson-databind:2.7.1'

The full source code is at https://github.com/optimizely/java-sdk.


The JavaScript SDK can be used in browser or in Node.js environments, and is distributed through npm. Add it to your package:

"npm install --save @optimizely/optimizely-sdk",

We also distribute a prebuilt UMD bundle of the SDK, which may be helpful if you're prototyping in a browser. This is immediately usable with code like this:

<script src="https://unpkg.com/@optimizely/optimizely-sdk/dist/optimizely.browser.umd.min.js"></script>
  window.optimizelySdk.createInstance(/* ... */);

The full source code is available on GitHub.


Our PHP SDK is available through Composer. To install, use composer require optimizely/optimizely-sdk or add optimizely/optimizely-sdk in the require section of your composer.json.

The SDK requires PHP 5.5+.

The full source code is at https://github.com/optimizely/php-sdk.


The Python SDK is distributed through PyPi. To install, use pip install optimizely-sdk or add optmizely-sdk your requirements.txt.

The full source code is at https://github.com/optimizely/python-sdk.


The gem for the Ruby SDK is distributed through RubyGems. To install, use gem install optimizely-sdk or bundler to install the gem optimizely-sdk.

The full source code is at https://github.com/optimizely/ruby-sdk.


The Android SDK packages are available on Jcenter:

The android-sdk module transitively depends on the datafile-handler, event-handler, user-profile, and shared modules. It also includes the latest version of gson and slf4j logger. Gradle can be used to exclude any dependency if you want to replace one with another version or implementation.

To add the android-sdk and all modules to your project, include this line in your app's build.gradle in the dependencies block:

implementation 'com.optimizely.ab:android-sdk:2.1.2'

To exclude the default implementation of parser and slf4j, include this code:

implementation ('com.optimizely.ab:android-sdk:2.1.2') {
        exclude group: 'com.google.code.gson', module:'gson'
        exclude group: 'com.noveogroup.android', module:'android-logger'

Access the android-sdk repository on Bintray to determine the latest version. Note that you should be pinning your dependency to a major or minor version of the SDK to prevent breaking changes from major version upgrades from affecting your build.

Also check out the test-app in the SDK repository.

repositories {

dependencies {
  compile ('com.optimizely.ab:android-sdk:2.1.0') {
      // exclude default implementation of slf4j if you want to provide 
      // your own.  Multidex can fail if you have more than one 
      // implementation present. If you are having a multidex error
      // this is most likely the issue.
      exclude group: 'com.noveogroup.android', module:'android-logger'


The full source code is at https://github.com/optimizely/android-sdk.

iOS and tvOS

Our iOS and tvOS SDKs are available for distribution through CocoaPods, Carthage, or manual installation. You can use these SDKs with apps written in Objective C and Swift.


iOS 8.0+ or tvOS 9.0+



In the instructions below, <platform> is used to represent the platform on which you are building your app. Currently, we support iOS and tvOS platforms. You should be pinning your dependency to a major or minor of the SDK to prevent breaking changes from major version upgrades from affecting your build.


  1. Add this line to the Podfile:

     pod 'OptimizelySDKiOS','2.1.0'

    Alternatively, if you are developing on tvOS, use:

    pod 'OptimizelySDKTVOS','2.1.0'

    Make sure use_frameworks! is also included in the Podfile:

    target 'Your App' do
        pod 'OptimizelySDKiOS','2.1.0'
  2. Run the command:

    pod install

For more installation information, see the Cocoapods Getting Started Guide.


  1. Add this line to the Cartfile:
github "optimizely/objective-c-sdk" "2.1.0"
  1. Run the command:
carthage update
  1. Link the frameworks to your project.
    Go to your project target's Link Binary With Libraries and drag over these frameworks from the Carthage/Build/ folder:
  1. To ensure that proper bitcode-related files and dSYMs are copied when archiving your app, you must install a Carthage build script:
    a. Add a new Run Script phase in your target's Build Phase.
    b. Include this line in the script area:
/usr/local/bin/carthage copy-frameworks
  c. Add the frameworks to the **Input Files** list:</br>

For more installation information, see the Carthage GitHub repository.

Manual installation

The universal framework can be used in an application without the need for a third-party dependency manager. The universal framework packages up all Optimizely X Mobile modules, which include:


The universal framework for iOS includes builds for these architectures:


The universal framework for tvOS includes build for these architectures:


Bitcode is enabled for both the iOS and tvOS universal frameworks.

To install the universal framework:

  1. Download the iOS or tvOS framework.

  2. Unzip the framework, then drag the framework to your project in Xcode. Xcode should prompt you to select a target. Go to Build Phases and make sure that the framework is under the Link Binary with Libraries section.

  3. Go to the General tab and add the framework to the Embedded Binaries section. If the Embedded Binaries section is not visible, add the framework in the Copy Files section (you can add this section in Build Settings).

  4. The Apple store will reject your app if you have the universal framework installed as it includes simulator binaries. You must run a script to strip the extra binaries before you upload the app.
    To do this, go to Build Phases and add a Run Script section by clicking the + symbol. Copy and paste the script below, replacing the FRAMEWORK_NAME with the proper framework name:

for ARCH in $ARCHS
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"

To build the universal framework:

  1. Build the OptimizelySDKiOS-Universal or OptimizelySDKTVOS-Universal schemes.
  2. Update our third-party dependencies, which are pulled in as Git submodules, by running this command:
git submodule init

followed by:

git submodule update

After building these schemes, the frameworks are output in the OptimizelySDKUniversal/generated-frameworks folder.

The full source code is at https://github.com/optimizely/objective-c-sdk.