Configure the JavaScript SDK event dispatcher v6+

4 min

Minimum SDK version

v6.0.0+

For versions 5.3.5 and below, see JavaScript (Browser) SDKJavaScript (Browser) SDK or JavaScript (Node) SDKJavaScript (Node) SDK. See the SDK compatibility matrixSDK compatibility matrix documentation for a list of current SDK releases and the features they support.

Event dispatcher

The JavaScript SDK has a built-in event dispatcher for handling decision event or conversion eventdecision event or conversion event. The built-in event dispatcher should be sufficient enough for most of the cases, but you can override it based on the specifics of your environment.

An event dispatcher is required to conform to the following interface:

export interface EventDispatcher {
  dispatchEvent(event: LogEvent): Promise<EventDispatcherResponse>
}

The following code is an example of a custom event dispatcher that logs the event before passing it to the default dispatcher.

Note You are not required to use the default dispatcher. You can send events to Optimizely Feature Experimentation using your own implementation. This could involve using an HTTP client of your choice or even selectively dropping events before dispatching them.

import {
  eventDispatcher,
  EventDispatcher,
  EventDispatcherResponse,
  LogEvent,
} from "@optimizely/optimizely-sdk";

export class CustomEventDispatcher implements EventDispatcher {
  private baseDispatcher: EventDispatcher;

  constructor() {
    this.baseDispatcher = eventDispatcher;
  }

  async dispatchEvent(event: LogEvent): Promise<EventDispatcherResponse> {
    // Custom behavior: Log the event
    console.log("[CustomEventDispatcher] Dispatching event:", {
      url: event.url,
      method: event.httpVerb,
      payload: event.params,
    });

    // Forward the event to the default dispatcher
    return this.baseDispatcher.dispatchEvent(event);
  }
}

Important If you are using a custom event dispatcher, modifying the event payload alters your results on the Experiment Results pageExperiment Results page. Only modify the payload if you want to drop certain events.

The closingEventDispatcher Option

You can optionally provide a custom closing event dispatcher in addition to the regular event dispatcher. The event processor invokes the closing dispatcher to handle any remaining events before shutdown.

If a custom event dispatcher is provided (and not a closing one), that same dispatcher is used for closing as well.

In the browser environment, if neither dispatcher is provided, a default closing dispatcher is used. This default implementation leverages the navigator.sendBeacon API to help ensure that events are sent reliably, even if the user navigates away from the page before the request completes.