HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

Use the `start` method to initialize the Swift SDK and instantiate an instance of the Optimizely client class that exposes API methods like [Get Enabled Features](🔗). Each client corresponds to the datafile representing the state of a project for a certain environment.

## Version

SDK v3.1.0

## Description

The constructor accepts a configuration object to configure Optimizely.

Some parameters are optional because the SDK provides a default implementation, but you may want to override these for your production environments. For example, you may want override these to set up an error handler and logger to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing.

## Parameters

The table below lists the required and optional parameters in Swift.

**sdkKey** _required_StringSDK Key
**logger** _optional_OPTLoggerA custom logger
**eventDispatcher** _optional_OPTEventDispatcherA custom event handler
**userProfileService** _optional_OTPUserProfileServiceA custom user profile service
**periodicDownloadInterval** _optional_IntA custom interval for periodic background datafile download in seconds (default = 10 * 60 secs)
**defaultLogLevel** _optional_OptimizelyLogLevelLog level (default = `OptimizelyLogLevel.info`)

## Returns

Instantiates an instance of the Optimzely class.


We currently support a single concurrent instance per SDK key

## Examples

In our Swift SDK, you do not need to manage the datafile directly. The SDK includes a datafile manager that provides support for datafile polling to automatically update the datafile on a regular interval while the application is in the foreground.

To use it:

  1. Create a `OptimizelyClient` by supplying your **SDK Key** and optional configuration settings. You can find the SDK key in the **Settings** > **Environments** tab of a Full Stack project on the [Optimizely Application](🔗).

  2. Choose whether to start the client [synchronously or asynchronously](🔗) and use the appropriate `start` method to instantiate a client.

See the [Swift example: `AppDelegate.swift`](🔗). We also provide an [Objective-C example: `AppDelegate.m`](🔗).

## Use synchronous or asynchronous initialization

You have two choices for when to instantiate the Optimizely client: **synchronous** and **asynchronous**. The _behavioral_ difference between the two methods is whether your application pings the Optimizely servers for a new datafile during initialization. The _functional_ difference between the two methods is whether your app prioritizes accuracy or speed.

### Synchronous initialization

The synchronous method prioritizes speed over accuracy. Instead of attempting to download a new datafile every time you initialize an Optimizely client, your app uses a local version of the datafile. This local datafile can be cached from a previous network request.

When you initialize a client synchronously, the Optimizely manager first searches for a cached datafile. If one is available, the manager uses it to complete the client initialization. If the manager can't find a cached datafile, the manager searches for a bundled datafile. If the manager finds a the bundled datafile, it uses the datafile to complete the client initialization. If the manager can not find a bundled datafile, the manager can't initialize the client.


To initialize an `OptimizelyClient` object synchronously, call `optimizelyClient.start(datafile:datafile)`.


The datafile you pass must have the same project ID that you provided when initializing the Optimizely manager.

### Asynchronous initialization

The asynchronous method prioritizes accuracy over speed. During initialization, your app requests the newest datafile from the CDN servers. Requesting the newest datafile ensures that your app always uses the most current project settings, but it also means your app cannot instantiate a client until it downloads a new datafile, discovers the datafile has not changed, or until the request times out. This process takes time.

Initializing a client asynchronously executes like the [synchronous initialization](🔗), except the manager will first attempt to download the newest datafile. This network activity is what causes an asynchronous initialization to take longer to complete.

If the network request returns an error (such as when network connectivity is unreliable) or if the manager discovers that the cached datafile is identical to the newest datafile, the manager then uses the synchronous approach. If manager discovers that the datafile has been updated and now differs from the cached datafile, the manager downloads the new datafile and uses it to initialize the client.


To initialize an `OptimizelyClient` object asynchronously, call `optimizelyClient.start(completion:)` and pass it a callback function.


The datafile you pass must have the same project ID that you provided when initializing the Optimizely manager.

## Configure datafile polling

During its initialization, the manager attempts to pull the newest datafile from the CDN servers. After this, the Optimizely manager can periodically check for and pull a new datafile at the time interval you set during its initialization. The process of checking for and downloading a new datafile is called _datafile polling_.

By default, datafile polling is disabled, so the client only checks for a new datafile during initialization. To enable polling, set a non-zero interval value. This value is the number of seconds the manager waits between datafile polling attempt.

### Usage notes

  • The minimum polling interval is 2 minutes while the app is open. If you specify shorter polling intervals than the minimum, the SDK will automatically reset the intervals to 2 minutes.

  • The Optimizely manager only checks for new datafiles when the SDK is active and the app is running on iOS/tvOS. You must configure background updates in iOS using the app delegate and calling the datafile manager download.

  • **If you have datafile polling enabled, the Swift SDK automatically updates when a new datafile is detected to ensure that you are always working with the latest datafile**. To be notified when the project has updated, register for a datafile change via the datafile change notification listener. The [Swift demo app](🔗) shows an example where we re-run our [Is Feature Enabled](🔗) method based on a new datafile.

  • If you wish to have your datafile just update when the app comes to foreground, you can do the following:

    1. Set the periodicDownloadInterval = 0

    2. Just call start when coming from foreground:

## Enable bundled datafiles

When your customer opens your app for the first time after installing or updating it, the manager attempts to pull the newest datafile from Optimizely's CDN. If your app is unable to contact the servers, the manager can substitute a datafile that you included (_bundled_) when you created your app.

By bundling a datafile within your app, you ensure that the Optimizely manager can initialize without waiting for a response from the CDN. This lets you prevent poor network connectivity from causing your app to hang or crash while it loads.

Datafile bundling works with both synchronous and asynchronous initialization because reverting to a bundled datafile happens during the Optimizely manager's initialization, before a client is instantiated.

## More Sample Code

## Source files

The language/platform source files containing the implementation for Swift are at [OptimizelyClient.swift](🔗).

Initialize SDK

This topic describes how to initialize the Optimizely Swift SDK in your application.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.