Skip to main content

Quickstart

The Eppo JavaScript SDK enables feature flags and experiments in your JavaScript applications with only a few lines of code.

The SDK handles all the complexity of feature flag evaluation and experiment assignment locally in your application, with no network calls required after initial setup. This guide will walk you through installing the SDK and implementing your first feature flag, experiment, and contextual bandit.

Installation​

First, install the SDK into your current project.

The Eppo JavaScript SDK is available via a number of package managers or via a CDN. Use whichever one you prefer.

yarn add @eppo/js-client-sdk

Depending on whether you are running a feature flag, an experiment, or a bandit, the initialization code will be slightly different.

Feature Flags​

Feature flags are a way to toggle features on and off without needing to deploy code.

Initialize the SDK​

Create an SDK key if you don't already have one.

First, initialize the SDK using your SDK key. The SDK key is different from the project API key.

import init from "@eppo/js-client-sdk";

await init({apiKey: 'SDK_KEY'});
note

The SDK key is different from the project API key. You can find your SDK key in the SDK Keys section of the Eppo interface.

Assign a variant​

Once initialized, the SDK uses a singleton pattern, making it accessible from anywhere in your application. To make assignments, import the SDK and use getInstance() to access the SDK instance.

How assignments work​

The SDK periodically retrieves configuration rules from the Eppo server that define how subjects should be allocated to variants. When you call an assignment function, the SDK evaluates these rules locally without making additional network requests.

Each assignment requires:

  • Flag Key: Identifies which set of configuration rules to use
  • Subject Key: A unique identifier for the subject (usually a user ID)
  • Subject Attributes: Optional key-value pairs containing additional information used for rule evaluation
  • Default Value: Fallback value if assignment fails or rules don't match
import * as EppoSdk from "@eppo/js-client-sdk";

// Get SDK instance
const eppoClient = EppoSdk.getInstance();

// Define assignment parameters
const featureKey = "my-neat-feature";
const subjectKey = getCurrentUser() || "anonymous";
const subjectAttributes = {
    'country': user.country,
    'device': user.device,
};
const defaultValue = "default-value";

// Make an assignment
const variation = eppoClient.getStringAssignment(
  featureKey,
  subjectKey,
  subjectAttributes,
  defaultValue
);

Assignment Types​

The SDK provides different assignment functions based on the type of value you need:

FunctionReturn Type
getStringAssignment()String
getBooleanAssignment()Boolean
getJSONAssignment()JSON object
getIntegerAssignment()Integer
getNumericAssignment()Float
note

See more details about assignment functions in the Assignments page.

Using Assignments​

After receiving an assignment, your application should implement logic to modify the user experience accordingly:

// Example using a boolean assignment
const variation = eppoClient.getStringAssignment(
  featureKey,
  subjectKey,
  subjectAttributes,
  defaultValue
);

// Render different components based on assignment
if (variation === "landing-page-a") {
    return <LandingPageA />
} else if (variation === "landing-page-b") {
    return <LandingPageB />
} else {
    return <LandingPageC />
}

That's all the code you need to make a basic assignment. After that, you can do the rest of the work running the experiment from the Eppo UI. This is awesome both because it allows you to iterate quickly and because it gives you the ability to change the experiment configuration without redeploying your code.

You can see the full steps for setting up a feature flag including UI steps in the feature flag quickstart.

Experiments​

While feature flags are useful, they do not send you any information about how your users are interacting with the feature. Experiments provide a way to collect data about these interactions using whichever logging and data warehousing system you prefer.

To log events through the SDK, you need to define a logAssignment() function using the IAssignmentLogger interface to pass to the init() function.

For simplicity, we'll create a logAssignment() function that logs the assignment data to the console.

// Import Eppo's assignment logger interface and client initializer
import { IAssignmentLogger, init } from "@eppo/js-client-sdk";

// Define logAssignment so that it logs events
const assignmentLogger: IAssignmentLogger = {
  logAssignment(assignment) {
    console.log(assignment);
  }
};

// Initialize the SDK
await init({
  apiKey: "<SDK_KEY>",
  assignmentLogger,
});

note

In a production application, you would want to replace the console.log() statement with an actual logging system. We have documentation on how to set up logging with multiple popular data warehouses and logging systems in the Assignment page.

Assign a variant​

After initializing the SDK with the logAssignment() function, you can make assignments in the same way as for feature flags.

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

// Get SDK instance
const eppoClient = EppoSdk.getInstance();

// Define assignment parameters
const featureKey = "my-neat-feature";
const subjectKey = getCurrentUser() || "anonymous";
const subjectAttributes = {
    'country': user.country,
    'device': user.device,
};
const defaultValue = "default-value";

// Make an assignment
const variation = eppoClient.getStringAssignment(
  featureKey,
  subjectKey,
  subjectAttributes,
  defaultValue
);

if (variation === "landing-page-a") {
    return <LandingPageA />
} else if (variation === "landing-page-b") {
    return <LandingPageB />
} else {
    return <LandingPageC />
}

You can see the full steps for running an experiment including UI steps in the experiment quick start.

Contextual Bandits​

Contextual Multi-Armed Bandits are a way to dynamically optimize assignments based on user context. A bandit balances exploration of new actions with exploitation of known successful actions to maximize a specified metric.

Bandit Setup​

Setting up a bandit is very similar to setting up an experiment but with an additional logging function.

// Import Eppo's logger interfaces and client initializer
import { IAssignmentLogger, IBanditLogger, init } from "@eppo/node-server-sdk";

// Define an assignment logger for recording variation assignments
const assignmentLogger: IAssignmentLogger = {
  logAssignment(assignment: IAssignmentEvent) {
    console.log("TODO: save assignment information to data warehouse", assignment);
  }
};

// Define a bandit logger for recording bandit action assignments
const banditLogger: IBanditLogger = {
  logBanditAction (banditEvent: IBanditEvent) {
    console.log("TODO: save bandit action information to the data warehouse, ensuring the column names are as expected", banditEvent);
  }
};

// Initialize the SDK with both loggers provided
await init({
  apiKey: "<SDK_KEY>",
  assignmentLogger,
  banditLogger
});
note

In a production application, you would want to replace the console.log() statement with an actual logging system. We have documentation on how to set up logging with multiple popular data warehouses and logging systems in the Assignment page.

Query the bandit for actions​

Instead of making simple assignments with a bandit, you will want to query the bandit for actions.

import * as EppoSdk from "@eppo/js-client-sdk";
import { Attributes, BanditActions } from "@eppo/js-client-sdk-common";

const eppoClient = EppoSdk.getInstance();

const flagKey = "shoe-bandit";
const subjectKey = getCurrentUser() || "anonymous";
const subjectAttributes: Attributes = { age: 25, country: "GB" };
const defaultValue = "default";
const actions: BanditActions = {
  nike: { 
    numericAttributes: { brandAffinity: 2.3 }, 
    categoricalAttributes: { imageAspectRatio: "16:9" } 
  },
  adidas: {
    numericAttributes: { brandAffinity: 0.2 },
    categoricalAttributes: { imageAspectRatio: "16:9" }
  }
};



const { variation, action } = eppoClient.getBanditAction(
  flagKey,
  subjectKey,
  subjectAttributes,
  actions,
  defaultValue
);

if (action) {
  renderShoeAd(action);
} else {
  renderDefaultShoeAd();
}
note

For full steps to create a bandit including UI steps, see the bandit quickstart.

Next Steps​

Now that you've seen how to make assignments with the Eppo JavaScript SDK, we strongly recommend familiarizing yourself with the following topics: