@arcteryx/js-optimizely

OptimizelyWrapper

Overview

The OptimizelyWrapper is a singleton class that encapsulates the setup and usage of the Optimizely SDK. It provides a simple interface for managing feature flags, user context, and event tracking, with support for automatic client initialization and global event tracking.

This wrapper integrates the Optimizely SDK with additional functionality such as global event tracking using the window object. It helps manage the Optimizely client and user context while offering methods for checking feature flags and tracking events.

Features

• Singleton pattern for managing the Optimizely client and user context.
• Automatic Optimizely SDK initialization with support for feature flag checking and event tracking.
• User context management pass in a visitor ID and userAttributes for audience management.
• Global event tracking via window.trackEvent with support for eventTags when tracking custom events.
• Custom error handling on initialization with the onError function.
• Opt-in SDK enablement for flexibility in environments where Optimizely should be disabled.

Accessing the Optimizely Dashboard

To gain access to the Optimizely dashboard, please contact Ron or Olga.

You can log in to the Optimizely dashboard by visiting the following link:

Optimizely Login

Usage

Initializing the Wrapper

The OptimizelyWrapper uses a singleton pattern to ensure that only one instance is created. Use the getInstance method to initialize the wrapper and ensure the Optimizely SDK is ready to use.

You must pass either an sdkKey or a dataFile in the configuration. The wrapper now supports both these options, allowing flexibility depending on your Optimizely setup. You can also pass in an onError function for custom error handling during the SDK initialization.

After initializing, you must call createUserContext, which is used to create the userContext. Optimizely uses this user context for audience management, allowing feature flags to be evaluated based on the user's attributes.

Configuration

Option	Type	Description
sdkKey	string (optional)	Your Optimizely SDK key. If provided, a dataFile is optional.
dataFile	string (optional)	A local datafile for initializing the Optimizely client. If provided, a sdkKey is optional.
isEnabled	boolean	Whether Optimizely should be enabled. If false, feature flags and events are not used.
onError	(error: Error) => void	Optional custom error handling function for SDK initialization errors.

Example:

import OptimizelyWrapper from "@arcteryx/js-optimizely";

const setup = async () => {
  const userId = "user-12345"; // Required, used for creating userContext
  const userAttributes = {
    age: 25,
    country: "US",
  }; // Optional, custom attributes for audience management

  const optimizelyInstance = await OptimizelyWrapper.getInstance({
    sdkKey: "your-optimizely-sdk-key", // Optional if dataFile is provided
    dataFile: "your-optimizely-datafile", // Optional if sdkKey is provided
    isEnabled: true, // Set to false if Optimizely should be disabled
    onError: (error: Error) => {
      console.error("Custom error handling during initialization:", error);
    },
  });

  optimizelyInstance.createUserContext(userId, userAttributes);
};
// You can now use the OptimizelyWrapper instance to check features or track events.

Viewing Global Events via Adobe Tag Manager

You can set up custom rules in Adobe Tag Manager to track global events triggered by the OptimizelyWrapper. This is done by utilizing the window.trackEvent function, which is globally accessible.

You can log in to Adobe Tag Manager by visiting the following link:

Adobe TM

Setting Up a Custom Rule in Adobe Tag Manager

1. Create a new custom rule in Adobe Tag Manager.

2. In the rule's action, call the global window.trackEvent function. For example:

   window.trackEvent("event_name", {
     key1: "value1",
     key2: "value2",
   });

Checking if a Feature is Enabled

The isFeatureEnabled method allows you to check whether a specific feature flag is enabled for the current user, based on their user context and the feature flag configured in Optimizely.

Example:

const { enabled, variables, variationKey } = optimizelyInstance.isFeatureEnabled("new_feature_key");

if (enabled) {
  console.log("Feature is enabled:", variables);
  console.log("Variation key:", variationKey);
  // You can access feature variables like this:
  console.log("Variable example:", variables.someVariableKey);
} else {
  console.log("Feature is disabled.");
}