Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback
Hey! These docs are for version 2.0, which is no longer officially supported. Click here for the latest version, 3.0!

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

SDKs with out-of-the-box asynchronous dispatchers:

  • Java

  • C#

  • JavaScript

  • Objective-C

  • Swift

  • Android

SDKs with out-of-the-box synchronous dispatchers:

  • Python

  • Ruby

  • PHP


**Performance risks with synchronous dispatchers**: It is important to customize your event dispatcher when using an SDK for a blocking language (PHP, Ruby, and Python) to ensure that you can retrieve variations without waiting for the corresponding network request to return.

Regardless of the SDK you're using, we recommend 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. Customizing the event dispatcher allows you to take advantage of features like batching, which makes it easier to handle large event volumes efficiently or to implement retry logic when a request fails. You can build your dispatcher from scratch or start with the provided dispatcher.

To customize the event dispatcher, initialize the Optimizely client (or manager) with an event dispatcher instance:

The event dispatcher should implement a `dispatchEvent` function, which takes in three arguments: `httpVerb`, `url`, and `params`, all of which are created by the internal `EventBuilder` class. In this function, you should send a `POST` request to the given `url` using the `params` as the body of the request (be sure to stringify it to JSON) and `{content-type: 'application/json'}` in the headers.

## Android

The included event handler implementation includes queueing and flushing, so it will work even if an app is offline. The event handler uses an `IntentService` to queue up events to dispatch. If they fail to send, they are stored in a `sqlite` database and scheduled to be dispatched later. If you want to have events flushed when Wi-Fi is available or after reboot or reinstall using the default event handler, you need to augment your AndroidManifest.xml to include the intent filter declarations.

You will need to implement [EventHandler](🔗) to use your own event handler.


To handle backgrounding in Android O and later, you also need to register your event handler rescheduler in code. See the code sample above.

## iOS

The included event handler implementation, [OptimizelySDKEventDispatcher](🔗), includes queueing and flushing, so will work even if an app is offline. You will need to implement [OPTLYEventDispatcher](🔗) to use your own event handler.

## Java

We provide an asynchronous event dispatcher, [optimizely-sdk-httpclient](🔗), that requires `org.apache.httpcomponents:httpclient:4.5.2` and is parameterized by in-memory queue size and number of dispatch worker threads.

To use your own event dispatcher, implement the `dispatchEvent` method in our [EventHandler](🔗) interface. `dispatchEvent` takes in a [LogEvent](🔗) object containing all of the information needed to dispatch an event to Optimizely's backend. Events should be sent to `LogEvent.getEndpointUrl` as a `POST` request with `LogEvent.getBody` as the payload and `content-type: "application/json"` as the header.

## JavaScript

By default, our JavaScript SDK uses a [basic asynchronous event dispatcher](🔗).

## PHP

Our PHP SDK includes a [basic synchronous event dispatcher](🔗).

## Python

Our Python SDK includes a [basic synchronous event dispatcher](🔗). Examples of alternative approaches are available here:

  • [SDK Wrapper: Async Event Dispatcher by Cooper R](🔗)

  • [SDK Wrapper: Bulk Event Dispatcher with AWS SQS by Matt A](🔗)

## Ruby

Our Ruby SDK includes a [basic synchronous event dispatcher](🔗). If you are using the SDK in a production environment, you should provide your own event dispatcher using the networking library of your choice. Examples of alternative approaches are available here:

  • [SDK Wrapper: Cached Config by Ankit G](🔗)