> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-serverless-cloudflare.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Client SDKs

Statsig client SDKs enable you to run experiments for user experience improvements in applications running on end-user devices. These applications include web and mobile apps, television and gaming apps, and other consumer electronics apps.

As shown in the diagram below, implementing an experiment using a Statsig client SDK consists of three phases:

1. Initialization
2. Checking an Experiment
3. Logging Custom Events

<Frame>
  <img src="https://user-images.githubusercontent.com/1315028/169555378-a1ba4c22-1d13-46c5-956e-ba87abe9b549.png" alt="Client SDKs" />
</Frame>

### 1. Initialization

* The client SDK's `initialize` call takes the **client SDK key** and a [**StatsigUser**](/concepts/user) object.  First, it checks for cached values from a previous initialize in local storage, and then it makes a network request to Statsig servers; this network call fetches precomputed configuration parameters for the specified user from Statsig servers and stores these parameters in local storage on the client device.
  If the request fails, the previous cached values are used.

* Statsig's server latency to service `initialize` calls is generally 10ms (p50); the latency for given client may vary depending on how far the device is from Statsig's servers; the client SDK has a built-in timeout of 3 seconds that you can configure using **StatsigOptions** when you initialize the SDK

* The [**StatsigUser**](/concepts/user) object that you provide in the `initialize` call should include the user identifier, *userID*, that you use to identify the end-user of your application; the client SDK also generates a device identifier called *stableID* to enable experiments where users aren’t signed in and a *userID* is not available; you can choose to override this *stableID* through **StatsigOptions** using the *overrideStableID* parameter when you initialize the SDK

### 2. Checking an Experiment

* After the `initialize` call completes, any subsequent `getExperiment` call synchronously returns the variant that your end-user is assigned to (you define these parameters when you set up an experiment on the Statsig console);  use the returned `config` object to `get` the value of the parameters required to implement the experiment variant

* If your experiment is part of a Layer, the `getLayer` call returns the variant that the your end-user is assigned to;  use the returned `layer` object to `get` the value of the parameters required to implement the experiment variant

* The `checkGate` calls returns *true* if the end-user passes the feature gate rules that you've configured on the Statsig console, and *false* otherwise

* The `getConfig` call returns the dynamic configuration based on the rules that you've configured to target your end-users; use the returned `config` object to `get` the value of the parameters required to serve a dynamically configured app experience

* All of the above (`checkGate`, `getExperiment`, `getLayer`, and `getConfig`) log an exposure at the time the check is made, before returning a value to the caller.

* The client SDK automatically flushes all accumulated exposure checks and events to the Statsig servers every 10 seconds

* You can also force this flush by calling `shutdown` to push these accumulated exposure checks to Statsig servers; the `shutdown` call resets the state of the SDK and you should call it when the application is about to exit

* You can verify that exposure events are being recorded in Statsig servers by checking the live **Exposure Stream** in the Statsig console under the **Diagnostics** tab of your experiment

* The **Users** and **Checks** charts in the **Diagnostics** tab are updated hourly; the **Metrics Lift** panel in experiment **Results** is updated daily around 9am PST.

#### Updating Experiment Configuration

* The experiment configuration received from Statsig servers in response to the `initialize` call persists until you either make another `initialize` call (recommended when the end-user starts a new session) or an `updateUser` call (recommended when an end-user attribute changes). These calls trigger a revaluation of all experiment configuration for the end-user.

<Info title="Best Practices">
  **Using [**StatsigUser**](/concepts/user)**

  Learn how to use [StatsigUser](/concepts/user) while using a client SDK.

  **Setting Default Parameter Values**

  Statsig recommends including a default value when you make the `get` call to fetch a parameter value from the returned `config` object. This will ensure that your application code falls back to the default value for a parameter that's not yet been configured in an experiment, layer, or dynamic config in the Statsig console. For convenience, Statsig by default returns *false* when you check a gate that has not yet been configured.
</Info>

<Info title="Testing exposure checks in development or staging environments">
  You can test your experiment in development or staging environments by setting the environment tier in the `initialize` call. When you do this, you can verify that your exposure checks are working by switching the toggle to *Show non-production logs* in the **Exposure Stream** under the **Diagnostics** tab for your experiment in the Statsig console. By default, the **Exposure Stream** shows exposure checks logged in production environments.

  When you're testing in development or staging environments, you can target specific members in your team to see a specific variant by adding these members to the override list of a rule or variant group using the **Manage Overrides** option.
</Info>

#### A word on cached values

If the initialize request fails, the SDK will fall back to values cached for the user.  The cache key for those values is important - because values related to the session can change for every `initialize` call, if we include the full user object as the cache key, we may never match against cached values.

We define the "user" to cache based on the set of all ids - the userID and all customIDs.  This means that if another field changes in the user object, we will still load the cached values as long as the IDs are the same.

If you have critical fields which define a user uniquely and are not in the `userID` or `customIDs` field, you can override the cache key - check the documentation for your specific sdk.  At the moment, this is only available in javascript based sdks (js, react, react native, expo), and android/ios native sdks.

### 3. Logging Custom Events

* The client SDK's `logEvent` call takes a custom event that you want to record to analyze the impact of the experiment on your end-user experience

* The client SDK automatically flushes all accumulated logged custom events to the Statsig servers every 10 seconds

* Statsig uses these custom events to compute metrics as part of your experiment **Results**; Statsig automatically updates the **Metrics Lift** panel in the experiment **Results** tab daily around 9am PST

<Info title="Avoid custom event logging being blocked by third-party plugins">
  Custom event logging can sometimes be blocked by third-party plugins. As a workaround, you can set up a custom proxy using your domain for log event API calls. For more information, refer to [Custom Proxy for Statsig API](../custom_proxy).
</Info>

To start integrating, jump into the technical docs by language:

* [Javascript](/client/javascript-sdk)
* [React](/client/React)
* [React Native](/client/ReactNative)
* [React Native Expo](/client/Expo)
* [iOS](/client/iosClientSDK)
* [Android](/client/Android)
* [Dotnet](/client/DotNet)
* [Roku](/client/Roku)
* [Unity](/client/Unity)

Got questions? Join the Statsig engineering and product team on the [Statsig Slack channel](https://statsig.com/slack) and ask away!