Skip to main content
Tip: Get started quickly with one of our sample apps!
Source code: statsig-io/js-client-monorepo
Statsig’s normal (remote evaluation) SDKs are recommended for most client applications. Understand the use case and privacy risks by reading the On-Device Eval SDK overview. On-device evaluation SDKs are for Enterprise & Pro Tier only.
These SDKs use a different paradigm than their precomputed counterparts: JS, Android, iOS, they behave more like Server SDKs. Rather than requiring a user up front, you can check gates/configs/experiments for any set of user properties, because the SDK downloads a complete representation of your project and evaluates checks in real time.

​
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 cannot 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. See our 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)
Since @statsig/react-native-bindings-on-device-eval works in conjunction with @statsig/js-on-device-eval-client, documentation on the JavaScript On-Device Evaluation SDK is also relevant for React Native implementations.

​
Set Up the SDK

1

Install the SDK

​
Installation

Since the @statsig/react-native-bindings-on-device-eval works in conjunction with @statsig/js-on-device-eval-client, documentation on those packages is also relevant for React Native implementations.
Statsig uses a multi-package strategy, so you will need to install both the Statsig client and the React Native specific bindings.
npm install @statsig/react-native-bindings-on-device-eval

​
Peer Dependencies

The @statsig/react-native-bindings-on-device-eval package has peer dependencies which may also need to be installed if they are not already in your project.
npm install @react-native-async-storage/async-storage
2

Initialize the SDK

Next, 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 on in a gate or experiment.
For On-Device Evaluation, you’ll need to add the “Allow Download Config Specs” scope. Client keys, by default, are not able to download the project definition for on-device evaluation.While client keys are safe to include, Server and Console keys should always be kept private.
  • New SDK Keys
  • Existing SDK Keys
When creating a new client key, select “Allow Download Config Specs”Add DCS Scope to New Key

​
React Native Specific Setup

To get setup with Statsig in a React Native component tree, you should use the RN specific StatsigProviderOnDeviceEvalRN. This automatically switches out the storage layer used by the SDK, utilizing AsyncStorage instead of LocalStorage (which isn’t available in RN environments).
import {
  StatsigProviderOnDeviceEvalRN,
  useFeatureGate,
} from '@statsig/react-native-bindings-on-device-eval';

function Content() {
  const gate = useFeatureGate('a_gate');

  return <div>Reason: {gate.details.reason}</div>; // Reason: Network or NetworkNotModified
}

function App() {
  return (
    <StatsigProviderOnDeviceEvalRN
      sdkKey={YOUR_CLIENT_KEY}
      loadingComponent={<Text>...</Text>}
    >
      <Content />
    </StatsigProviderOnDeviceEvalRN>
  );
}

​
Working with the SDK

​
Setup a StatsigUser

To interact with the SDK, you will need to create a StatsigUser object. The full definition of this object can be found here. 
const myUser = {
    userID: "a-user",
    email: "user@statsig.com"
};

​
React Hooks

​
useGateValue or useFeatureGate

import { useGateValue } from '@statsig/react-native-bindings-on-device-eval';

const gateValue = useGateValue('a_gate', { userID: "a-user" }); // <-- Returns the boolean value
if (gateValue) {
  // 
}

import { useFeatureGate } from '@statsig/react-native-bindings-on-device-eval';

const gate = useFeatureGate('a_gate', { userID: "a-user" }); // <-- Returns the FeatureGate object
if (gate.value) {
  // 
}

​
useDynamicConfig

import { useDynamicConfig } from '@statsig/react-native-bindings-on-device-eval';

function MyComponent() {
  const config = useDynamicConfig('a_config', { userID: 'a-user' }); // <-- Returns the DynamicConfig object
  const bgColor = config.value['bg_color'] as string;

  return <View style={{backgroundColor: bgColor}}></View>;
}

​
useExperiment

import { useExperiment } from '@statsig/react-native-bindings-on-device-eval';

function MyComponent() {
  const experiment = useExperiment('an_experiment', { userID: 'a-user' }); // <-- Returns the Experiment object
  const bgColor = experiment.value['bg_color'] as string;

  return <View style={{backgroundColor: bgColor}}></View>;
}

​
useLayer

import { useLayer } from '@statsig/react-native-bindings-on-device-eval';

function MyComponent() {
  const layer = useLayer('a_layer', { userID: 'a-user' }); // <-- Returns the Layer object
  const bgColor = layer.getValue('bg_color') as string;

  return <View style={{backgroundColor: bgColor}}></View>;
}

​
Code Examples

Working sample apps are available in the repository:

​
Statsig User

You need to provide a StatsigUser object to check/get your configurations. You should pass as much information as possible in order to take advantage of advanced gate and config conditions. Most of the time, the userID field is needed in order to provide a consistent experience for a given user (see logged-out experiments to understand how to correctly run experiments for logged-out users). Besides userID, we also have email, ip, userAgent, country, locale and appVersion as top-level fields on StatsigUser. In addition, you can pass any key-value pairs in an object/dictionary to the custom field and be able to create targeting based on them. Once the user logs in or has an update/changed, make sure to call updateUser with the updated userID and/or any other updated user attributes:
For the React Native On-Device Evaluation SDK, you pass the `StatsigUser` object directly into each evaluation method (`checkGate`, `getConfig`, etc.) rather than during initialization.
Unlike precomputed evaluation SDKs, the on-device evaluation SDK does not have an `updateUser` method since it evaluates gates/configs/experiments in real-time for any user object you pass in.

​
Client Event Emitter

It is possible to subscribe to StatsigClientEvents (Not to be confused with StatsigEvent). These events occur at various stages while using the Statsig client. You can subscribe to specific events by specifying the StatsigClientEvent name, or, all events by using the wildcard token '*'. 
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);
The full list of events and descriptions can be found here.

​
Statsig Options

You can configure certain aspects of the SDKs behavior by passing a StatsigOptions object during initialization.
​
api
string
The API to use for all SDK network requests. You should not need to override this unless you have another API that implements the Statsig API endpoints.
​
logEventUrl
string
The URL used to flush queued events via a POST request. Takes precedence over StatsigOptions.api.
​
logEventBeaconUrl
string
The URL used to flush queued events via window.navigator.sendBeacon (web only). Takes precedence over StatsigOptions.api.
​
downloadConfigSpecsUrl
string
The URL used to fetch your latest Statsig specifications. Takes precedence over StatsigOptions.api.
​
environment
StatsigEnvironment
An object you can use to set environment variables that apply to all of your users in the same session.
​
overrideStableID
string
Overrides the auto-generated stableID that is set for the device.
​
logLevel
LogLevel
default:"LogLevel.Warn"
How much information is allowed to be printed to the console.
​
dataAdapter
SpecsDataAdapter
default:"StatsigSpecsDataAdapter"
Implementing this type allows customization of the initialization. See Using SpecsDataAdapter to learn more.
​
networkTimeoutMs
number
default:"10,000"
The maximum amount of time (in milliseconds) that any network request can take before timing out.
​
loggingBufferMaxSize
number
default:"50"
The maximum number of events to batch before flushing logs to Statsig.
​
loggingIntervalMs
number
default:"10,000"
How often (in milliseconds) to flush logs to Statsig.
​
overrideAdapter
OverrideAdapter
An implementor of OverrideAdapter, used to alter evaluations before its returned to the caller of a check api (checkGate/getExperiment etc).

​
Manual Exposures

Manual logging is error-prone and can often introduce issues like uneven exposures, which compromise experiment results.
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

In order to save users’ data and battery usage, as well as prevent logged events from being dropped, we keep event logs in client cache and flush periodically. Because of this, some events may not have been sent when your app shuts down. To make sure all logged events are properly flushed or saved locally, you should tell Statsig to shutdown when your app is closing: 
await myStatsigClient.shutdown();

​
Data Adapter

The EvaluationsDataAdapter type outlines how the StatsigClient should fetch and cache data during initialize and update operations. By default, the StatsigClient uses StatsigEvaluationsDataAdapter, a Statsig provided implementor of the EvaluationsDataAdapter type. StatsigEvaluationsDataAdapter provides ways to fetch data synchronously from Local Storage and asynchronously from Statsig’s servers. See Using EvaluationsDataAdapter to learn more and see example usage.

​
Additional Resources

⌘I