Getting started with Optimizely's Classic iOS 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.

The following SDK Install Steps will allow you to install the SDK and run experiments with Optimizely's Visual Editor.

SDK Download

You can download the iOS SDK through Cocoapods, download it manually from GitHub, or install it through Fabric:

SDK Version

ZIP | TAR | GitHub

iOS SDK Install Video

1. Create an iOS Project

To create an iOS project, select "Create New Project" in the Optimizely Dashboard:

Drawing

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

Project Code Dialog

2. SDK Integration

To use Optimizely's iOS SDK you must first integrate the SDK into your app. You can either install the Optimizely SDK using CocoaPods (recommended) or via Manual Installation. Our SDK supports iOS 7.0 and above.

Using CocoaPods

  1. Your Xcode project must be set up for CocoaPods. Refer to CocoaPods Getting Started if you haven't yet configured your project to work with CocoaPods.

  2. Our SDK only supports iOS 7.0 and above, so please make sure your Podfile specifies a deployment target of iOS 7.0 (or above). Then, add Optimizely to your Podfile:

     platform :ios, '7.0'
     # Other Pods
     pod 'Optimizely-iOS-SDK'
    
  1. Run pod install from the command line. This will add and install the Optimizely iOS SDK in your generated CocoaPods workspace.

    Note: By default CocoaPods installs to the first build target in the project.

Manual Installation

For new installations, please follow all steps. For upgrades, please follow steps 1 and 2.

  1. Clone the Optimizely SDK using git clone https://github.com/optimizely/Optimizely-iOS-SDK

  2. Drag Optimizely.framework from the SDK repository into your project. Check "Copy items into destination group's folder" and make sure the appropriate targets are checked.

  3. Open the "Build Phases" tab for the app's target. Under "Link Binary with Libraries," add the required frameworks if they're not already included:

    • AudioToolbox.framework
    • CFNetwork.framework
    • Foundation.framework
    • libicucore.tbd (libicucore.dylib for XCode 7.0 and below)
    • libsqlite3.dylib
    • MobileCoreServices.framework
    • Security.framework
    • SystemConfiguration.framework
    • UIKit.framework
  4. Switch to the "Build Settings" tab. Add -ObjC to the "Other Linker Flags" build setting.

3. Add Your API token

Using Objective-C

  1. Now, you're ready to write some code! Include this file at the top of your AppDelegate class implementation. This is usually found in a file called AppDelegate.m in the Project Navigator.

     #import <Optimizely/Optimizely.h>
    
  2. Add the following to the beginning of application:didFinishLaunchingWithOptions: in your app delegate. The code can be copied from your Project Code, which you can find by selecting the appropriate iOS Project in your Optimizely Dashboard. For more details, you can refer back to Step 1: Create an iOS project.

     // You can find the following code snippet in your project code.
    
     [Optimizely startOptimizelyWithAPIToken:YOUR_API_TOKEN launchOptions:launchOptions];
    
     // The rest of your initialization code...
    

    Note: We recommend putting this code at the beginning of your application:didFinishLaunchingWithOptions: function.

  3. In order to enter Edit Mode (which will allow your app to be detected by Optimizely's Editor), you'll have to define a URL scheme for Optimizely.

    1. Add [Optimizely handleOpenURL:] to application:openURL in your app delegate. This will notify Optimizely when the application has been loaded from a URL:

         - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
            if ([Optimizely handleOpenURL:url]) {
               return YES;
            }
            return NO;
         }
      
    2. In the project editor, click on "Targets" -> Your app name -> "Info" tab.

    3. Locate the section called "URL Types" and click the plus icon (+) to expand the section.
    4. Paste the following into the field called "Identifer":

         com.optimizely
      
    5. Add optly{PROJECT_ID} to "URL Schemes." Your Project ID is available at the bottom of the Project Code dialog box. For instance, if your Project ID is 123456, your URL Scheme would be optly123456. Once completed, your URL Scheme should look like this: Drawing

    6. Once you run your app in DEBUG mode with the SDK installed, you should see the image below in your Optimizely Dashboard. Once the SDK is detected, the Create Experiment button will appear, and you can continue to Step 4 to create your experiment.

      Drawing

Using Swift

  1. Now, you're ready to write some code! Include this file at the top of your AppDelegate class implementation. This is usually found in a file called AppDelegate.swift in the Project Navigator.

     import Optimizely
    
  2. Add the following to the beginning of application(_:didFinishLaunchingWithOptions:) in your app delegate. The code can be copied from your Project Code, which you can find by selecting the appropriate iOS Project in your Optimizely Dashboard. For more details, you can refer back to Step 1: Create an iOS project.

     // You can find the following code snippet in your project code.
    
     Optimizely.startOptimizelyWithAPIToken(YOUR_API_TOKEN, launchOptions:launchOptions);
    
     // The rest of your initialization code...
    

    Note: We recommend putting this code at the beginning of your application(_:didFinishLaunchingWithOptions:) function.

  3. In order to enter Edit Mode (which will allow your app to be detected by Optimizely's Editor), you'll have to define a URL scheme for Optimizely.

    1. Add Optimizely.handleOpenURL(_:) to application(_:openURL:) in your app delegate. This will notify Optimizely when the application has been loaded from a URL:

        func application(application: UIApplication, openURL url: NSURL, sourceApplication: String?, annotation: AnyObject) → Bool {
            if Optimizely.handleOpenURL(url) {
                return true
            }
            return false
        }
      
    2. In the project editor, click on "Targets" -> Your app name -> "Info" tab.

    3. Locate the section called "URL Types" and click the plus icon (+) to expand the section.
    4. Paste the following into the field called "Identifer":

         com.optimizely
      
    5. Add optly{PROJECT_ID} to "URL Schemes." Your Project ID is available at the bottom of the Project Code dialog box. For instance, if your Project ID is 123456, your URL Scheme would be optly123456. Once completed, your URL Scheme should look like this: Drawing

    6. Once you run your app in DEBUG mode with the SDK installed, you should see the image below in your Optimizely Dashboard. Once the SDK is detected, the Create Experiment button will appear, and you can continue to Step 4 to create your experiment.

      Drawing

4. Create an Experiment

After creating an iOS project and installing the SDK, reference this guide in our Knowledge Base, which will walk you through how to set up an experiment.

5. QA

Preview Mode

Preview mode allows you to view your app in a different variations 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, open the Preview menu, and click Launch Preview

Enter Preview Mode

Your app will restart and you will see the Optimizely preview menu icon displayed over your app content. The icon may be repositioned by dragging it. Tapping the icon will reveal the Preview Menu which allows you to switch variations, view the goals that have been triggered so far, and see the code blocks and live variables that are included in the experiment.

Preview Mode Demo

Now that you've created an experiment and successfully installed the Optimizely iOS 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, that are only set for certain QA devices. If you decide to go with setting up 2 separate projects, we recommend setting up an #ifdef 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? If you ran into issues, you can try out this troubleshooting tip.

  3. Configure your app so that non-technical members of your team can set up and run experiments using the visual editor on a physical device without the need of XCode. You can try downloading the development build on your device and try opening the link to make sure that this is set up properly.

  4. (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.

    • A useful debugging tool is to enable logging (be sure to disable this feature when your app is live in the app store) [Optimizely sharedInstance].verboseLogging = YES 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 Optimizely's dashboard 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.
  5. Once you've checked all these steps, you're ready to release to the app store! To learn more about how to use Optimizely's editor and get additional testing ideas, you can check out our articles in Optiverse.

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 enablePreview];
[Optimizely startOptimizelyWithAPIToken:YOUR_API_TOKEN launchOptions:launchOptions];

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 App 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

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