{% callout type="info" %}
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](/client/onDeviceOverview). On-device evaluation SDKs are for Enterprise & Pro Tier only.
{% /callout %}

These SDKs use a different paradigm than their precomputed counterparts ([JS](/client/javascript-sdk), [Android](/client/Android), [iOS](/client/iosClientSDK)) and 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 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](/access-management/api-keys#client-keys-with-server-permissions).
* 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

{% steps %}
{% step title="Install the SDK" %}
Install the Statsig SDK using npm, yarn, or jsdelivr:

{% codetabs %}
```bash npm
npm install @statsig/js-on-device-eval-client
```

```bash yarn
yarn add @statsig/js-on-device-eval-client
```

```html CDN / <script>
<script src="https://cdn.jsdelivr.net/npm/@statsig/js-on-device-eval-client@1/build/statsig-js-on-device-eval-client.min.js"></script>
```
{% /codetabs %}

Statsig is hosted on the [jsDelivr](https://www.jsdelivr.com/package/npm/@statsig/js-client) 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`
{% /step %}

{% step title="Initialize the SDK" %}
Initialize the SDK with a client SDK key from the ["API Keys" tab on the Statsig console](https://console.statsig.com/api_keys). These keys are safe to embed in a client application.

Along with the key, pass in a [User Object](#statsig-user) with the attributes you'd like to target later in a gate or experiment.

{% callout type="warning" %}
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.
{% /callout %}

{% accordion title="How to add the scope" %}
{% tabs %}
{% tab title="New SDK Keys" %}
When creating a new client key, select **"Allow Download Config Specs"**

![Add DCS Scope to New Key](/images/local-eval/new-keys.png)
{% /tab %}

{% tab title="Existing SDK Keys" %}
To add the scope to an existing key, under **Project Settings** → **API Keys** → **Client API Keys**, select **Actions** → **Edit Scopes**, and select **"Allow Download Config Specs"**, then **Save**.

![Add DCS Scope to Existing Key](/images/local-eval/existing-keys.png)
{% /tab %}
{% /tabs %}
{% /accordion %}

```typescript
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();
```

{% callout type="note" %}
In advanced use cases, you may want to Prefetch or Bootstrap (Provide) values for initialization. Go to [Using EvaluationsDataAdapter](/client/javascript-mono/UsingEvaluationsDataAdapter) to learn how to do this.
{% /callout %}
{% /step %}
{% /steps %}

## Working with the SDK

## Setup a StatsigUser

To interact with the SDK, create a `StatsigUser` object. The full definition of this
object is [here](#statsig-user).

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

### Checking a Feature Flag/Gate

Now that your SDK is initialized, check a [**Feature Gate**](/feature-flags/overview). Feature Gates create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always **CLOSED** or **OFF** (think `return false;`) by default.

```typescript
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:

```typescript
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

Use **Layers/Experiments** to run A/B/n experiments. Statsig offers two APIs, but recommends [layers](/experiments/layers-overview) to enable quicker iterations with parameter reuse.

```typescript
// 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:

```typescript
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.

```typescript
await myStatsigClient.flush();
```

### Code Examples

Working sample apps are available in the repository:

* [JavaScript & TypeScript Examples](https://github.com/statsig-io/js-client-monorepo/tree/main/samples)

## 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.

The `userID` field is usually required to provide a consistent experience for a given user. (Refer to [logged-out experiments](/guides/first-device-level-experiment) to understand how to correctly run experiments for logged-out users.)

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.

{% callout type="note" %}
For the JavaScript On-Device Evaluation SDK, you pass the `StatsigUser` object into each evaluation method (`checkGate`, `getConfig`, etc.) rather than during initialization.
{% /callout %}

{% callout type="note" %}
Unlike precomputed evaluation SDKs, the on-device evaluation SDK doesn't have an `updateUser` method since it evaluates gates/configs/experiments in real-time for any user object you pass in.
{% /callout %}

## Client Event Emitter

You can subscribe to StatsigClientEvents (not to be confused with [StatsigEvent](#logging-an-event)). These events occur at various stages while using the Statsig client.
Subscribe to specific events by specifying the StatsigClientEvent name, or subscribe to all events using the wildcard token `'*'`.

```typescript
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](https://github.com/statsig-io/js-client-monorepo/blob/main/packages/client-core/src/StatsigClientEventEmitter.ts).

## Statsig Options

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

{% parameter name="api" type="string" %}
The API to use for all SDK network requests. You don't need to override this unless you have another API that implements the Statsig API endpoints.
{% /parameter %}

{% parameter name="logEventUrl" type="string" %}
The URL used to flush queued events via a POST request. Takes precedence over `StatsigOptions.api`.
{% /parameter %}

{% parameter name="logEventBeaconUrl" type="string" %}
The URL used to flush queued events via `window.navigator.sendBeacon` (web only). Takes precedence over `StatsigOptions.api`.
{% /parameter %}

{% parameter name="downloadConfigSpecsUrl" type="string" %}
The URL used to fetch your latest Statsig specifications. Takes precedence over `StatsigOptions.api`.
{% /parameter %}

{% parameter name="environment" type="StatsigEnvironment" %}
An object you can use to set environment variables that apply to all of your users in the same session.
{% /parameter %}

{% parameter name="overrideStableID" type="string" %}
Overrides the auto-generated stableID that is set for the device.
{% /parameter %}

{% parameter name="logLevel" type="LogLevel" %}
How much information is allowed to be printed to the console.
{% /parameter %}

{% parameter name="dataAdapter" type="SpecsDataAdapter" %}
Implementing this type allows customization of the initialization. See [Using SpecsDataAdapter](/client/javascript-mono/UsingEvaluationsDataAdapter) to learn more.
{% /parameter %}

{% parameter name="networkTimeoutMs" type="number" %}
The maximum amount of time (in milliseconds) that any network request can take before timing out.
{% /parameter %}

{% parameter name="loggingBufferMaxSize" type="number" %}
The maximum number of events to batch before flushing logs to Statsig.
{% /parameter %}

{% parameter name="loggingIntervalMs" type="number" %}
How often (in milliseconds) to flush logs to Statsig.
{% /parameter %}

{% parameter name="overrideAdapter" type="OverrideAdapter" %}
An implementor of `OverrideAdapter`, used to alter evaluations before they are returned to the caller of a check API (checkGate/getExperiment etc).
{% /parameter %}

## Manual Exposures

{% callout type="warning" %}
Manual logging is error-prone and can often introduce issues like uneven exposures, which compromise experiment results.
{% /callout %}

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

### Gates

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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.

```typescript
await myStatsigClient.shutdown();
```

## Data Adapter

The `EvaluationsDataAdapter` type outlines how the `StatsigClient` fetches and caches 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.
Go to [Using EvaluationsDataAdapter](/client/javascript-mono/UsingEvaluationsDataAdapter) to learn more and see example usage.

## FAQs

{% accordion-group %}
{% accordion title="Does the SDK use the browser local storage or cookies? If so, for what purposes?" %}
The SDK doesn't use any cookies.

It does use local storage for feature targeting and experimentation purposes only. Values for feature gates, dynamic configs, and experiments are cached in local storage as a backup if your website/app can't reach the Statsig server to fetch the latest values. If any events were logged but couldn't be sent to the Statsig server due to issues like network failure, Statsig also saves them in local storage to be sent again when the network restores.
{% /accordion %}

{% accordion title="How do I run experiments for logged out users?" %}
Go to the guide on [device level experiments](/guides/first-device-level-experiment).
{% /accordion %}
{% /accordion-group %}

## Additional Resources

* [On-Device Evaluation SDK Overview](/client/onDeviceOverview)
* [Client Keys with Server Permissions](/access-management/api-keys#client-keys-with-server-permissions)
* [Using EvaluationsDataAdapter](/client/javascript-mono/UsingEvaluationsDataAdapter)
* [Debugging SDK Evaluations](/sdks/debugging)