React Native On-Device Evaluation

Pros

• No network request needed when changing user properties: 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

• The entire project definition is available client-side: your client key exposes the names and configurations of all experiments and feature flags. 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

   Installation

   Statsig uses a multi-package strategy. Install both the Statsig client and the React Native specific bindings.

   npmyarn

   Copy

   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 aren't already in your project.

   npmyarn

   Copy

   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 can't download the project definition for on-device evaluation by default.

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

   How to add the scope

   React Native Specific Setup

   To set up Statsig in a React Native component tree, use the RN-specific StatsigProviderOnDeviceEvalRN. This automatically switches out the storage layer used by the SDK, using AsyncStorage instead of LocalStorage (which is unavailable in RN environments).

   tsx

   Copy

   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

Set up a StatsigUser

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:

• React Native Examples

Logging Custom Events

Logging an Event

After setting up a Feature Gate or Experiment, you may want to track custom events to see how new features or different experiment groups affect those events. Call the Log Event API for the event. You can also provide a value and metadata object to be logged 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();

Statsig User

You need to provide a StatsigUser object to check/get your configurations. Pass as much information as possible to take advantage of advanced gate and config conditions.

Besides userID, Statsig also supports 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 create targeting based on them.

After the user logs in or their attributes change, call updateUser with the updated userID and any other updated user attributes:

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

You can configure SDK 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

The SDK keeps event logs in the client cache and flushes them periodically to save data and battery usage. Because of this, the SDK may not have flushed some events when your app shuts down.

To ensure all logged events are flushed or saved locally, shut down Statsig when your app is closing:

await myStatsigClient.shutdown();

Data Adapter

Additional Resources

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