Skip to main content

Eppo Randomization SDK

Overview

You can use Eppo’s SDK to randomly assign subjects to your Eppo experiment variations. Given a subject and experiment, the SDK assigns a variation based on your experiment traffic allocation and variations configured in Eppo. If the traffic allocation changes, subjects already assigned to a variation are not reassigned.

Getting Started

Generating an API Token

You will need to generate an API token that allows your application to communicate with Eppo’s experiments API. Do not share your API token with anyone outside your organization.

1. Navigate to the Admin tab in the Eppo homepage and click Create Key

generating-api-token-1

2. Fill in a unique name for the key and give it read access

generating-api-token-2

3. Click Create

A modal will pop up with the API key -- download it or copy it somewhere else for safe-keeping. generating-api-token-3

4. Close your modal to see your API token

generating-api-token-4

Install the SDK package in your preferred language

note

Eppo’s Node SDK is meant for use in server applications only. It is not compatible with browser or client JS applications.

yarn add @eppo/js-client-sdk

Initialize the Eppo SDK in your application code

Initialize the SDK once when your application starts up to generate a singleton client instance. The initialize method should be called once per application lifecycle; do not initialize the SDK on every request.

Client SDKs

note

API Keys used with Client SDKs should have only ‘Randomization READ’ permissions

import * as EppoSdk from '@eppo/js-client-sdk';

const eppoClient = await EppoSdk.init({ apiKey: 'YOUR_API_KEY' });

Server SDKs

Upon initialization, server-side SDKs will begin polling Eppo’s API at regular intervals to retrieve your experiment configurations.

import * as EppoSdk from '@eppo/node-server-sdk';

const eppoClient = await EppoSdk.init({ apiKey: 'YOUR_API_KEY' });

Retrieving Assignment Configurations

Each SDK client exposes a variation assignment function. This function takes 2 inputs:

  • experimentKey - this is the value from the “Feature Flag” input on the Experiment “Setup” tab as seen in the below screenshots
  • subjectKey - the entity ID that is being experimented on, typically represented by a uuid.

Screen Shot 2022-05-04 at 4.51.42 PM.png

For the SDK to assign an experiment variation to a subject, the experiment must have a non-zero Experiment Traffic Allocation.

If the experiment has zero experiment traffic allocation, you may still initialize the SDK in your application, but the variation assignment function will return null if the subject input does not belong to the experiment sample population. For example, if the traffic allocation is 25%, the assignment function will return a variation for 25% of subjects and null for the remaining 75%.

See the below language-specific examples for how to invoke the assignment function:

Client SDKs

import * as EppoSdk from '@eppo/js-client-sdk';

const client = EppoSdk.getInstance();
const variation = client.getAssignment("user-1", "my-experiment")

Server SDKs

import * as EppoSdk from '@eppo/node-server-sdk';

const client = EppoSdk.getInstance();
const variation = client.getAssignment("user-1", "my-experiment")

Logging

In order to capture assignment data, you need to log which variations the experiment subjects are exposed to. The Eppo SDK integrates with your event logging system to log this information whenever the getAssignment function is invoked. The below code examples shows how to integrate the SDK with Segment for logging events, but you could also use any other logging system. The SDK will use the provided logging implementation to log assignments.

Client SDKs

note

API Keys used with Client SDKs should have only ‘Randomization READ’ permissions

import { init, IAssignmentLogger, IAssignmentEvent } from '@eppo/js-client-sdk';

// Create a custom logging implementation
// This implementation uses the Segment track API:
// https://segment.com/docs/connections/spec/track/
const logger: IAssignmentLogger = {
logAssignment(assignment: IAssignmentEvent) {
analytics.track({
userId: assignment.subject,
event: "Eppo Randomization Assignment",
properties: assignment,
});
},
};

// Initialize the SDK with the logging object
init({
apiKey: '<API_KEY>',
assignmentLogger: logger,
});

Server SDKs

import { init, IAssignmentLogger, IAssignmentEvent } from '@eppo/node-server-sdk';

// Create a custom logging implementation
// This implementation uses the Segment track API:
// https://segment.com/docs/connections/spec/track/
const logger: IAssignmentLogger = {
logAssignment(assignment: IAssignmentEvent) {
analytics.track({
userId: assignment.subject,
event: "Eppo Randomization Assignment",
properties: assignment,
});
},
};

// Initialize the SDK with the logging object
init({
apiKey: '<API_KEY>',
assignmentLogger: logger,
});