Experiment Node.js SDK

Official documentation for Amplitude Experiment's server-side Node.js SDK implementation.

This documentation has separate sections for remote and local evaluation:

Remote evaluation

Implements fetching variants for a user via remote evaluation.

Install

1npm install --save @amplitude/experiment-node-server

1yarn add @amplitude/experiment-node-server

 1import { Experiment } from '@amplitude/experiment-node-server';
 2 
 3// (1) Initialize the experiment client
 4const experiment = Experiment.initializeRemote('<DEPLOYMENT_KEY>', {
 5    fetchTimeoutMillis: 500,
 6    fetchRetries: 1,
 7    fetchRetryBackoffMinMillis: 0,
 8    fetchRetryTimeoutMillis: 500,
 9});
10 
11// (2) Fetch variants for a user
12const user = {
13    user_id: 'user@company.com',
14    device_id: 'abcdefg',
15    user_properties: {
16        'premium': true,
17    },
18};
19const variants = experiment.fetchV2(user);
20 
21// (3) Access a flag's variant
22const variant = variants['YOUR-FLAG-KEY'];
23if (variant?.value === 'on') {
24    // Flag is on
25} else {
26    // Flag is off
27}

Initialize remote

The SDK client should be initialized in your server on startup. The deployment key argument passed into the apiKey parameter must live within the same project that you are sending analytics events to.

1initializeRemote(apiKey: string, config?: RemoteEvaluationConfig): RemoteEvaluationClient

1import { Experiment } from '@amplitude/experiment-node-server';
2 
3const experiment = Experiment.initializeRemote('<DEPLOYMENT_KEY>', config: {
4    fetchTimeoutMillis: 500,
5    fetchRetries: 1,
6    fetchRetryBackoffMinMillis: 0,
7    fetchRetryTimeoutMillis: 500,
8});

Configuration

The SDK client can be configured on initialization.

Fetch

Fetches variants for a user and returns the results. This function remote evaluates the user for flags associated with the deployment used to initialize the SDK client.

1fetchV2(user: ExperimentUser): Promise<Variants>

1const user = {
2    user_id: 'user@company.com',
3    device_id: 'abcdefg',
4    user_properties: {
5        'premium': true,
6    },
7};
8const variants = await experiment.fetchV2(user);

After fetching variants for a user, you may to access the variant for a specific flag.

1const variant = variants['YOUR-FLAG-KEY'];
2if (variant?.value === 'on') {
3    // Flag is on
4} else {
5    // Flag is off
6}

Local evaluation

Implements evaluating variants for a user via local evaluation. If you plan on using local evaluation, you should understand the tradeoffs.

Install

Install the Node.js Server SDK with npm or yarn.

1npm install --save @amplitude/experiment-node-server

1yarn add @amplitude/experiment-node-server

 1import { Experiment } from '@amplitude/experiment-node-server';
 2 
 3// (1) Initialize the local evaluation client with a server deployment key.
 4const experiment = Experiment.initializeLocal('<DEPLOYMENT_KEY>', {
 5  // (Recommended) Enable local evaluation cohort targeting.
 6  cohortSyncConfig: {
 7    apiKey: '<API_KEY>',
 8    secretKey: '<SECRET_KEY>'
 9  }
10});
11 
12// (2) Start the local evaluation client.
13await experiment.start();
14 
15// (2) Evaluate a user.
16const user = { device_id: 'abcdefg' };
17const variants = experiment.evaluateV2(user);

Initialize Local

Initializes a local evaluation client.

1initializeLocal(apiKey: string, config?: LocalEvaluationConfig): LocalEvaluationClient

Configuration

You can configure the SDK client on initialization.

LocalEvaluationConfig

AssignmentConfig

CohortSyncConfig

Start

Start the local evaluation client, pre-fetching local evaluation mode flag configs for evaluation and starting the flag config poller at the configured interval.

1start(): Promise<void>

You should await the result of start() to ensure that flag configs are ready to be used before calling evaluateV2()

1await experiment.start();

Evaluate

Executes the evaluation logic using the flags pre-fetched on start(). You must give evaluate a user object argument. You can optionally pass an array of flag keys if you require only a specific subset of required flag variants.

1evaluateV2(user: ExperimentUser, flagKeys?: string[]): Record<string, Variant>

 1// The user to evaluate
 2const user = { device_id: 'abcdefg' };
 3 
 4// Evaluate all flag variants
 5const allVariants = experiment.evaluateV2(user);
 6 
 7// Evaluate a specific subset of flag variants
 8const specificVariants = experiment.evaluateV2(user, [
 9  'my-local-flag-1',
10  'my-local-flag-2',
11]);

Local evaluation cohort targeting

Since version 1.10.0, the local evaluation SDK client supports downloading cohorts for local evaluation targeting. You must configure the cohortSyncConfig option with the analytics apiKey and secretKey on initialization to enable this support.

1const experiment = Experiment.initializeLocal('<DEPLOYMENT_KEY>', {
2  // (Recommended) Enable local evaluation cohort targeting.
3  cohortSyncConfig: {
4    apiKey: '<API_KEY>',
5    secretKey: '<SECRET_KEY>'
6  }
7});

Consider configuring the maxCohortSize to avoid downloading large cohorts which may cause your service to run out of memory. Cohorts that are too large will not be downloaded.

Access Amplitude cookies

If you're using the Amplitude Analytics SDK on the client-side, the Node.js server SDK provides an AmplitudeCookie class with convenience functions for parsing and interacting with the Amplitude identity cookie. This is useful for ensuring that the Device ID on the server matches the Device ID set on the client, especially if the client hasn't yet generated a Device ID.

 1import { AmplitudeCookie } from '@amplitude/experiment-node-server';
 2 
 3app.use((req, res, next) => {
 4  const { query, cookies, url, path, ip, host } = req
 5 
 6  // grab amp device id if present
 7  const ampCookieName = AmplitudeCookie.cookieName('amplitude-api-key');
 8  let deviceId = null;
 9  if (cookies[ampCookieName]) {
10    deviceId = AmplitudeCookie.parse(cookies[ampCookieName]).device_id;
11  }
12  if (!deviceId) {
13    // deviceId doesn't exist, set the Amplitude Cookie
14    deviceId = random22CharBase64String();
15    const ampCookieValue = AmplitudeCookie.generate(deviceId);
16    res.cookie(ampCookieName, ampCookieValue, {
17      domain: '.your-domain.com', // this should be the same domain used by the Amplitude JS SDK
18      maxAge: 365 * 24 * 60 * 60 * 1000, // this is currently the same as the default in the Amplitude JS SDK, can be modified
19      sameSite: 'Lax'
20    });
21  }
22 
23  next()
24});