Configure the Swift SDK event dispatcher

7 min

The Optimizely Feature Experimentation SDKs make HTTP requests for every decision event or conversion event that gets triggered. Each SDK has a built-in event dispatcher for handling these events, but You should overriding it based on the specifics of your environment.

You should customizing the event dispatcher you use in production to ensure that you queue and send events in a manner that scales to the volumes handled by your application. You can build your dispatcher from scratch or start with the provided dispatcher.

Unlike most other SDKs, the provided dispatcher for Swift includes event queueing, event batching, and flushing. Events will be queued if an app is offline and will be forwarded to the server when the app is online again.

On watchOS, the SDK cannot observe app lifecycle changes. Call WatchBackgroundNotifier.applicationDidEnterBackground() and WatchBackgroundNotifier.applicationDidBecomeActive() from your extension delegate. The SDK then flushes queued events when the app moves to the background.

The examples show that to customize the event dispatcher, initialize the Optimizely client (or manager) with an event dispatcher instance.

// create OptimizelyClient with a custom EventDispatcher
let customEventDispatcher = CustomEventDispatcher()
 
// or you can simply adjust parameters of DefaultEventDispatcher to disable batching (timerInterval=0), etc
let customEventDispatcher = DefaultEventDispatcher(timerInterval: 0)    

optimizely = OptimizelyClient(sdkKey: "<Your_SDK_Key>",
                              eventDispatcher: customEventDispatcher)

// create OptimizelyClient with a custom EventDispatcher
CustomEventDispatcher *customEventDispatcher = [[CustomEventDispatcher alloc] init];
     
self.optimizely = [[OptimizelyClient alloc] initWithSdkKey:@"<Your_SDK_Key>"
                       			logger:nil
                       			eventDispatcher:customEventDispatcher
                       			userProfileService:nil
                         		periodicDownloadInterval:@(5*60)                       
                       			defaultLogLevel:OptimizelyLogLevelInfo];

Warning The maximum payload size is 3.5 MB. Optimizely rejects requests with a 400 response code, Bad Request Error, if the batch payload exceeds this limit.

The size limitation is because of the Optimizely Events API, which Feature Experimentation uses to send data to Optimizely.

The most common cause of a large payload size is a high batch size. If your payloads exceed the size limit, try configuring a smaller batch size.

Configure the default event dispatcher

You can adjust the provided DefaultEventDispatcher with these initializer parameters:

Parameter	Type	Default	Description
`batchSize`	`Int`	`10`	Maximum number of events combined into one batch. Set to `1` to send each event individually. Values of `0` or less use the default.
`backingStore`	`DataStoreType`	`.file`	Where queued events are stored: `.file`, `.memory`, or `.userDefaults`.
`dataStoreName`	`String`	`"OPTEventQueue"`	Name of the event queue store.
`timerInterval`	`TimeInterval`	`60` (seconds)	Interval for flushing batched events. Set to `0` to disable batching and send events immediately. Negative values use the default.
`maxQueueSize`	`Int`	`10000`	Maximum number of events held in the queue. Values below `100` use the default. If the value is smaller than `batchSize`, the SDK raises it to `batchSize`.

Store the event queue in a custom directory

Store the event queue file in a directory you choose to keep SDK files out of the iOS Files app. By default, DefaultEventDispatcher stores the file in the Documents directory on iOS and watchOS. On tvOS and macOS, it uses the Caches directory. On iOS, the Files app can show users the files in the Documents directory.

Swift SDK version 6.0.1 and later provide a DefaultEventDispatcher initializer with a dataStoreDirectory parameter. Pass it a FileManager.SearchPathDirectory value. The following example stores the event queue in the Application Support directory, which the Files app does not show:

let eventDispatcher = DefaultEventDispatcher(dataStoreDirectory: .applicationSupportDirectory)

optimizely = OptimizelyClient(sdkKey: "YOUR_SDK_KEY",
                              eventDispatcher: eventDispatcher)

This initializer differs from the standard initializer in the following ways:

The dataStoreDirectory parameter has no default value, so you must pass it.

The event queue is file-based. The initializer has no backingStore parameter.

The batchSize, dataStoreName, timerInterval, and maxQueueSize parameters work as described in the default event dispatcher parameters.

The SDK creates the directory if it does not exist. If the SDK cannot access the directory, it uses the default directory.

When you switch directories, the SDK does not move an existing queue file or send the events in it. The dataStoreDirectory setting also does not apply to the queue for Optimizely Data Platform events, which stays in the default directory. To move the cached datafile, go to Store the cached datafile in a custom directory.

Implement a custom event dispatcher

The event dispatcher must conform to the OPTEventDispatcher protocol and implement these functions:

dispatchEvent(event: EventForDispatch, completionHandler: DispatchCompletionHandler?)

flushEvents()

In Objective-C, conform to the OPTEventDispatcher protocol, whose completion handler is (NSData *, NSError *).

The SDK creates EventForDispatch, which carries the target url and the JSON body of the event. In dispatchEvent, send a POST request to that url. Use body as the request body and set content-type: application/json in the headers.

Important If you are using a custom event dispatcher, do not modify the event payload returned from Optimizely. Modifying this payload will alter your results.

Source files

The included event handler implementation for the Swift SDK is available on GitHub.