JavaScript On-Device Evaluation Client SDK

Pros

• No need for a network request when changing user properties - just check the gate/config/experiment locally
• Can bring your own CDN or synchronously initialize with a preloaded project definition
• Lower latency to download configs cached at the edge, rather than evaluated for a given user (which can't be cached as much)

Cons

• Entire project definition is available client side: the names and configurations of all experiments and feature flags accessible by your client key are exposed. Refer to client key with server permission best practices.
• Payload size is strictly larger than what is required for the traditional SDKs
• Evaluation performance is slightly slower - rather than looking up the value, the SDK must actually evaluate targeting conditions and an allocation decision
• Does not support ID list segments with > 1000 IDs
• Does not support IP or User Agent based checks (Browser Version/Name, OS Version/Name, IP, Country)

Set Up the SDK

1. Install the SDK

   Install the Statsig SDK using npm, yarn, or jsdelivr:

   npmyarnCDN / <script>

   Copy

   npm install @statsig/js-on-device-eval-client
   

   Statsig is hosted on the jsDelivr CDN.

   To access the current primary JavaScript bundle, use:

   https://cdn.jsdelivr.net/npm/@statsig/js-client/build/statsig-js-client.min.js

   To access specific files/versions:

   https://cdn.jsdelivr.net/npm/@statsig/js-client@{version}/build/statsig-js-client.min.js

2. Initialize the SDK

   Initialize the SDK with a client SDK key from the "API Keys" tab on the Statsig console. These keys are safe to embed in a client application.Along with the key, pass in a User Object with the attributes you'd like to target later in a gate or experiment.

   For On-Device Evaluation, you'll need to add the "Allow Download Config Specs" scope. Client keys, by default, can't download the project definition for on-device evaluation.

   While client keys are safe to include, Server and Console keys should always be kept private.

   How to add the scope

   typescript

   Copy

   import { StatsigOnDeviceEvalClient } from '@statsig/js-on-device-eval-client';
   
   const myStatsigClient = new StatsigOnDeviceEvalClient(
     YOUR_CLIENT_KEY, 
     { environment: {tier: 'development'} }
   );
   
   // initialize and wait for the latest values
   await myStatsigClient.initializeAsync();
   

   In advanced use cases, you may want to Prefetch or Bootstrap (Provide) values for initialization. Go to Using EvaluationsDataAdapter to learn how to do this.

Working with the SDK

Setup a StatsigUser

const myUser = {
    userID: "a-user",
    email: "user@statsig.com"
};

Checking a Feature Flag/Gate

if (myStatsigClient.checkGate("new_homepage_design", myUser)) {
  // Gate is on, show new home page
} else {
  // Gate is off, show old home page
}

Reading a Dynamic Config

Feature Gates work well for simple on/off switches with optional advanced user targeting. To send different values (strings, numbers, and similar types) to your clients based on specific user attributes such as country, use Dynamic Configs. The API is similar to Feature Gates but returns a full JSON object you can configure on the server and fetch typed parameters from. For example:

const dynamicConfig = myStatsigClient.getDynamicConfig("awesome_product_details", myUser);
const itemName = dynamicConfig.value["product_name"] ?? "Some Fallback";
const price = dynamicConfig.value["price"] ?? 10.0;

if (dynamicConfig.value["is_discount_enabled"] === true) {
  // apply some discount logic
}

Getting a Layer/Experiment

// Values via getLayer
const layer = myStatsigClient.getLayer("user_promo_experiments", myUser);
const promoTitle = layer.get("title") ?? "Welcome to Statsig!";
const discount = layer.get("discount") ?? 0.1;

// or, via getExperiment
const titleExperiment = myStatsigClient.getExperiment("new_user_promo_title", myUser);
const priceExperiment = myStatsigClient.getExperiment("new_user_promo_price", myUser);

const promoTitle = titleExperiment.value["title"] ?? "Welcome to Statsig!";
const discount = priceExperiment.value["discount"] ?? 0.1;

Logging an Event

After you set up a Feature Gate or an Experiment, you can track custom events to measure how your new features or experiment groups affect those events. Call the Log Event API for the event, and optionally provide a value and/or a metadata object to log together with the event:

import type { StatsigEvent } from '@statsig/client-core';

// log a simple event
myStatsigClient.logEvent('my_simple_event');

// or, include more information by using a StatsigEvent object
const myEvent: StatsigEvent = {
  eventName: 'add_to_cart',
  value: 'SKU_12345',
  metadata: {
    price: '9.99',
    item_name: 'diet_coke_48_pack',
  },
};

myStatsigClient.logEvent(myEvent);

Flushing Logged Events

flush() sends queued events immediately. Use shutdown() when your app is exiting.

await myStatsigClient.flush();

Code Examples

Working sample apps are available in the repository:

• JavaScript & TypeScript Examples

Statsig User

Provide a StatsigUser object to check or get your configurations. Pass as much information as possible to take advantage of advanced gate and config conditions.

Besides userID, the email, ip, userAgent, country, locale, and appVersion fields are available as top-level fields on StatsigUser. You can also pass any key-value pairs in an object/dictionary to the custom field to create targeting based on them.

Client Event Emitter

import type {
  AnyStatsigClientEvent,
  StatsigClientEvent,
  StatsigClientEventCallback,
} from '@statsig/client-core';

const onAnyClientEvent = (event: AnyStatsigClientEvent) => {
  console.log("Any Client Event", event);
};

const onLogsFlushed = (event: StatsigClientEvent<'logs_flushed'>) => {
  console.log("Logs", event.events);
};

// subscribe to an individual StatsigClientEvent
myStatsigClient.on('logs_flushed', onLogsFlushed);

// or, subscribe to all StatsigClientEvents
myStatsigClient.on('*', onAnyClientEvent);

// then later, unsubscribe from the events
myStatsigClient.off('logs_flushed', onLogsFlushed);
myStatsigClient.off('*', onAnyClientEvent);

Statsig Options

Configure the SDK's behavior by passing a StatsigOptions object during initialization.

Manual Exposures

You can query your gates/experiments without triggering an exposure and manually log the exposures later.

Gates

// Check gate with exposure disabled
const result = myStatsigClient.checkGate('a_gate_name', { user, disableExposureLog: true });

// Manually log the exposure
myStatsigClient.checkGate('a_gate_name', { user });

Configs

// Get config with exposure disabled
const config = myStatsigClient.getConfig('a_dynamic_config_name', { user, disableExposureLog: true });

// Manually log the exposure
myStatsigClient.getConfig('a_dynamic_config_name', { user });

Experiments

// Get experiment with exposure disabled
const experiment = myStatsigClient.getExperiment('an_experiment_name', { user, disableExposureLog: true });

// Manually log the exposure
myStatsigClient.getExperiment('an_experiment_name', { user });

Layers

// Get layer with exposure disabled
const layer = myStatsigClient.getLayer('a_layer_name', { user, disableExposureLog: true });
const paramValue = layer.get('a_param_name', 'fallback_value');

// Manually log the exposure
const layer = myStatsigClient.getLayer('a_layer_name', { user });
const paramValue = layer.get('a_param_name', 'fallback_value');

Lifecycle & Advanced Usage

Shutting Statsig Down

To save users' data and battery usage and prevent logged events from being dropped, the SDK keeps event logs in client cache and flushes them periodically. Because of this, some events may not have been sent when your app shuts down.

To ensure all logged events are flushed or saved locally, call shutdown when your app is closing.

await myStatsigClient.shutdown();

Data Adapter

FAQs

Additional Resources

• On-Device Evaluation SDK Overview
• Client Keys with Server Permissions
• Using EvaluationsDataAdapter
• Debugging SDK Evaluations