`.
* Subsequent sessions reuse the stored value. Each client SDK key has its own Stable ID entry.
* Local storage is scoped per domain, so cross-domain usage requires sharing the value manually (see below).
### Reading the Stable ID
```tsx theme={null}
const context = client.getContext();
console.log('Statsig StableID:', context.stableID);
```
```tsx theme={null}
import { useStatsigClient } from '@statsig/react-bindings';
function MyComponent() {
const { client } = useStatsigClient();
const context = client.getContext();
return {context.stableID}
;
}
```
### Overriding the Stable ID
Provide a custom Stable ID through `StatsigUser.customIDs.stableID` if you already manage a durable device identifier.
```tsx theme={null}
import { StatsigClient, StatsigUser } from '@statsig/js-client';
const userWithStableID: StatsigUser = {
customIDs: {
stableID: 'my-custom-stable-id',
},
};
const client = new StatsigClient('client-xyz', userWithStableID);
await client.updateUserAsync(userWithStableID);
```
```tsx theme={null}
import { StatsigProvider, useStatsigClient } from '@statsig/react-bindings';
function App() {
return (
Your App
);
}
function MyComponent() {
const { client } = useStatsigClient();
useEffect(() => {
client.updateUserAsync({
customIDs: { stableID: 'my-custom-stable-id' },
});
}, [client]);
}
```
When you override the Stable ID it is persisted to local storage, so subsequent sessions reuse your custom value.
### Sharing Stable ID Across Subdomains
Add this helper script before initializing the SDK and then copy the stored value onto your user object.
```html theme={null}
```
(Use this script at your discretion and test thoroughly.)
### Aligning Stable ID Between Client and Server
To share Stable ID with a backend Statsig SDK, send the value with requests and persist it server-side when missing. The server can bootstrap the client with the same Stable ID.
```tsx theme={null}
// Server: ensure Stable ID exists, then return initialize response for the client
const values = Statsig.getClientInitializeResponse(user, YOUR_CLIENT_KEY, {
hash: 'djb2',
});
// Client: apply the server-provided values and initialize synchronously
const { values, user: verifiedUser } = await fetch('/init-statsig-client', {
method: 'POST',
body: loadUserData(),
}).then((res) => res.json());
const myClient = new StatsigClient(YOUR_CLIENT_KEY, verifiedUser);
myClient.dataAdapter.setData(values);
myClient.initializeSync();
```
## 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:
```tsx theme={null}
'use client';
import { useEffect } from "react";
import { useStatsigClient } from "@statsig/react-bindings";
export default function Home() {
const { client } = useStatsigClient();
useEffect(() => {
return () => {
void client.shutdown();
};
}, [client]);
return null;
}
```
In an App Router app, you need to use the [`use client` directive](https://nextjs.org/docs/app/building-your-application/rendering/client-components) to ensure your logic runs on the frontend.
```tsx theme={null}
import { useEffect } from "react";
import { useStatsigClient } from "@statsig/react-bindings";
export default function Home() {
const { client } = useStatsigClient();
useEffect(() => {
return () => {
void client.shutdown();
};
}, [client]);
return null;
}
```
## Advanced Setup
### Client Bootstrapping (Recommended)
```ts app/api/statsig-bootstrap/route.ts theme={null}
import { Statsig, StatsigUser } from '@statsig/statsig-node-core';
export async function POST(request: Request): Promise {
const body = await request.json();
const user = new StatsigUser(body?.user ?? {});
// Ensure server SDK is initialized at startup
// await Statsig.initialize(process.env.STATSIG_SERVER_KEY!);
const values = Statsig.getClientInitializeResponse(user, {
hashAlgorithm: 'djb2',
});
return new Response(JSON.stringify(values), { status: 200 });
}
```
```tsx app/layout.tsx theme={null}
import { StatsigBootstrapProvider } from '@statsig/next';
export default function RootLayout({ children }: { children: React.ReactNode }) {
const user = { userID: 'user-123' };
return (
{children}
);
}
```
```ts pages/api/statsig-bootstrap.ts theme={null}
import type { NextApiRequest, NextApiResponse } from 'next';
import { Statsig, StatsigUser } from 'statsig-node'; // legacy Node SDK for pages router
export default async function handler(
req: NextApiRequest,
res: NextApiResponse,
) {
if (req.method !== 'POST') {
res.status(400).send('/statsig-bootstrap only supports POST');
return;
}
// Ensure server SDK is initialized at startup
// await Statsig.initialize(process.env.STATSIG_SERVER_KEY!);
const { user } = JSON.parse(req.body) as { user: StatsigUser };
const values = Statsig.getClientInitializeResponse(user, { hash: 'djb2' });
res.status(200).send(JSON.stringify(values));
}
```
```tsx pages/_app.tsx theme={null}
import type { AppProps } from 'next/app';
import { StatsigProvider } from '@statsig/react-bindings';
import { StatsigClient } from '@statsig/js-client';
import { useEffect, useMemo, useState } from 'react';
export default function App({ Component, pageProps }: AppProps) {
const user = useMemo(() => ({ userID: 'a-user' }), []);
const [client, setClient] = useState(null);
useEffect(() => {
(async () => {
const res = await fetch('/api/statsig-bootstrap', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ user }),
});
const initializeValues = await res.json();
const inst = new StatsigClient(
process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY!,
user,
{ initializeValues },
);
await inst.initializeAsync();
setClient(inst);
})();
}, [user]);
if (!client) {
return null;
}
return (
);
}
```
### Proxying Network Traffic (Optional)
```ts app/proxy/initialize/route.ts theme={null}
// Note: Using generic path names like "proxy" instead of "statsig-proxy"
// to prevent ad blockers from blocking these requests
import { generateBootstrapValues } from './statsig-backend';
export async function POST(request: Request): Promise {
const json = await request.json();
if (!json || typeof json !== 'object') {
return new Response(null, { status: 400 });
}
const data = await generateBootstrapValues();
return new Response(data);
}
```
```ts app/proxy/search.ts theme={null}
// Note: Using generic path names like "search" instead of "log_event" or "events"
// to prevent ad blockers from blocking these requests
type ExtendedRequestInit = RequestInit & { duplex?: 'half' | 'full' };
export async function POST(request: Request): Promise {
const tail = request.url.split('?').pop();
const logEventUrl = `https://events.statsigapi.net/v1/log_event?${tail}`;
const fetchOptions: ExtendedRequestInit = {
method: 'POST',
body: request.body,
headers: request.headers,
duplex: 'half',
};
return fetch(logEventUrl, fetchOptions);
}
```
```ts pages/api/proxy/initialize.ts theme={null}
// Note: Using generic path names like "proxy" instead of "statsig-proxy"
// to prevent ad blockers from blocking these requests
import type { NextApiRequest, NextApiResponse } from 'next';
import { StatsigUser } from 'statsig-node';
import { getStatsigValues } from '@/pages/statsig-backend';
export default async function handler(
req: NextApiRequest,
res: NextApiResponse,
) {
if (req.method !== 'POST') {
res.status(400).send('/initialize only supports POST');
return;
}
const { user } = JSON.parse(req.body) as { user: StatsigUser };
const values = await getStatsigValues(user);
res.status(200).send(values);
}
```
```ts pages/api/proxy/search.ts theme={null}
// Note: Using generic path names like "search" instead of "log_event" or "events"
// to prevent ad blockers from blocking these requests
import type { NextApiRequest, NextApiResponse } from 'next';
type ExtendedRequestInit = RequestInit & { duplex?: 'half' | 'full' };
export default async function handler(
req: NextApiRequest,
res: NextApiResponse,
): Promise {
if (req.method !== 'POST') {
res.status(400).send('/search only supports POST');
return;
}
let logEventUrl = `https://events.statsigapi.net/v1/log_event`;
const queryParams = [] as string[];
for (const [key, value] of Object.entries(req.query)) {
queryParams.push(`${key}=${value}`);
}
if (queryParams.length > 0) {
logEventUrl += '?' + queryParams.join('&');
}
const fetchOptions: ExtendedRequestInit = {
method: 'POST',
body: req.body as BodyInit,
headers: req.headers as HeadersInit,
duplex: 'half',
};
try {
const response = await fetch(logEventUrl, fetchOptions);
if (!response.ok) {
res.status(500).send('Failed to log event');
return;
}
const body = await response.text();
res.status(response.status).send(body);
} catch (err) {
res.status(500).send('Failed to log event: ' + err);
}
}
```
```ts theme={null}
// Assign URLs when creating the client
const inst = new StatsigClient(clientSdkKey, user, {
networkConfig: {
logEventUrl: '/api/proxy/search',
initializeUrl: '/api/proxy/initialize',
logEventCompressionMode: 'Forced',
},
disableCompression: true,
disableStatsigEncoding: true,
});
```
## Statsig Site Generation (SSG)
Vercel's Static Site Generation renders HTML at build time. Because static HTML can't be responsive to per-user values, experimenting on SSG content requires one of these patterns:
* Use Vercel Edge Middleware with Statsig's Edge Config Adapter for zero-latency redirects.
* Isolate Statsig usage to hydrated client components only.
```tsx theme={null}
// Create a single client and share it across multiple StatsigProviders
const myStatsigClient = new StatsigClient(YOUR_SDK_KEY, user, options);
await myStatsigClient.initializeAsync();
```
## Statsig Options
Controls logging behavior.
* `browser-only` (default): log events from browser environments.
* `disabled`: never send events.
* `always`: log in every environment, including non-browser contexts.
Use `loggingEnabled: 'disabled'` instead.
Skip generating a device-level Stable ID.
Recompute every evaluation instead of using the memoized result.
Override the generated session ID.
Persist Stable ID in cookies for cross-domain tracking.
Prevent any local storage writes (disables caching).
Override network endpoints per request type.
Base URL for all requests. The SDK appends endpoint paths like `/initialize` and `/rgstr`; append `/v1` when your proxy expects it.
Endpoint for initialization requests only. Takes precedence over `api` for `/initialize`.
Fallback endpoints for initialization requests only. This does not create a generic fallback for `api`.
Endpoint for event uploads.
Fallback endpoints for event uploads only. This does not create a generic fallback for `api`.
Request timeout in milliseconds.
Disable all outbound requests; combine with `loggingEnabled: 'disabled'` to silence log warnings.
Provide custom transport (e.g., Axios).
Set environment-wide defaults (for example `{ tier: 'staging' }`).
Console verbosity.
Max events per log batch.
Interval between automatic flushes.
Modify evaluations before returning them.
Attach the current page URL to logged events.
Send requests without Statsig-specific encoding.
Control compression for batched events.
Use `logEventCompressionMode` instead.
Provide a custom data adapter to control caching/fetching.
Override cache key generation for stored evaluations.
## Additional Resources
* [JavaScript Client SDK](/client/javascript-sdk)
* [React Client SDK](/client/React)
* [Initialization Concepts](/client/concepts/initialize)
# React Client SDK
Source: https://docs.statsig.com/client/React
Use the Statsig React SDK with hooks and providers to evaluate feature flags, run experiments, and add optional session replay and autocapture plugins.
Source code: statsig-io/js-client-monorepo
## Set Up the SDK
If you need a starter project, follow the official React quickstart . Looking for Next.js instead? See the Next.js SDK docs.
### AI-powered Setup
Setup Statsig in 90 seconds by copying this AI prompt into your IDE:
```text expandable theme={null}
You are a frontend engineer integrating the Statsig SDK into a React app. Follow these instructions carefully:
1. Install the required Statsig packages:
npm install @statsig/react-bindings @statsig/session-replay @statsig/web-analytics
2. In the main component file (`App.jsx` or `App.tsx`):
- Import `StatsigProvider` and `useClientAsyncInit` from `@statsig/react-bindings`
- Import `StatsigAutoCapturePlugin` from `@statsig/web-analytics` and `StatsigSessionReplayPlugin` from `@statsig/session-replay`
- Initialize the SDK using your client key: 'YOUR-CLIENT-API-KEY'
- Use `userID` from an existing variable if it's already declared in the file; otherwise, default to `'a-user'`
- Wrap the existing app content inside ``, using `Loading...
` as the `loadingComponent`
3. DO NOT remove any existing JSX content from the component. Just wrap it.
4. Here is what the final file structure should look like:
import { StatsigProvider, useClientAsyncInit } from '@statsig/react-bindings';
import { StatsigAutoCapturePlugin } from '@statsig/web-analytics';
import { StatsigSessionReplayPlugin } from '@statsig/session-replay';
import YourApp from './YourApp';
function App() {
const id = typeof userID !== 'undefined' ? userID : 'a-user';
const { client } = useClientAsyncInit(
'YOUR-CLIENT-API-KEY',
{ userID: id },
{ plugins: [new StatsigAutoCapturePlugin(), new StatsigSessionReplayPlugin()] }
);
return (
Loading...}>
);
}
5. Ask the user to provide their CLIENT-API-KEY and insert it where prompted above.
```
### Install Packages
```bash theme={null}
npm install @statsig/react-bindings
```
```bash theme={null}
yarn add @statsig/react-bindings
```
Add `@statsig/session-replay` and `@statsig/web-analytics` if you plan to enable Session Replay or Auto Capture.
Next, 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 on in a gate or experiment.
### Wrap Your App With `StatsigProvider`
Provide your client SDK key and initial user when you render the provider.
```tsx theme={null}
import { StatsigProvider } from '@statsig/react-bindings';
function App() {
return (
Hello world
);
}
```
### Typical Project Structure
Most projects render a root component inside the provider.
```tsx theme={null}
// App.tsx
import RootPage from './RootPage';
import { StatsigProvider } from '@statsig/react-bindings';
export default function App() {
return (
);
}
```
```tsx theme={null}
// RootPage.tsx
export default function RootPage() {
return Hello World
;
}
```
Need to balance startup speed with freshness? Review Initialization Strategies for bootstrap and async options.
## Use the SDK
Use `useStatsigClient` inside components to retrieve the client when you need to evaluate something.
```tsx theme={null}
import { useStatsigClient } from '@statsig/react-bindings';
const { client } = useStatsigClient();
```
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's check a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
```tsx theme={null}
import {
useFeatureGate,
useGateValue,
useStatsigClient,
} from '@statsig/react-bindings';
const { checkGate } = useStatsigClient();
const gateValue = useGateValue('my_gate');
const gate = useFeatureGate('my_gate');
return (
{checkGate('my_gate') &&
Passing
}
{gateValue &&
Passing
}
{gate.value &&
Passing ({gate.details.reason})
}
Reason: {config.details.reason}
Value: {config.get('a_value', 'fallback_value')}
Another Value: {getDynamicConfig('my_dynamic_config').get('a_bool', false)}
);
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```tsx theme={null}
import { useExperiment, useStatsigClient } from '@statsig/react-bindings';
const experiment = useExperiment('my_experiment');
const { getExperiment } = useStatsigClient();
return (
Group: {getExperiment('my_experiment').groupName}
Value: {experiment.get('a_value', 'fallback_value')}
);
```
```tsx theme={null}
import { useLayer, useStatsigClient } from '@statsig/react-bindings';
const layer = useLayer('my_layer');
const { getLayer } = useStatsigClient();
return (
Group: {getLayer('my_layer').groupName}
Value: {layer.get('a_value', 'fallback_value')}
);
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:
```tsx theme={null}
import { useStatsigClient } from '@statsig/react-bindings';
const { logEvent } = useStatsigClient();
return logEvent('my_event')}>Click Me ;
```
### Flushing Logged Events
`flush()` sends queued events immediately. Use `shutdown()` when your app is exiting.
```tsx theme={null}
import { useStatsigClient } from '@statsig/react-bindings';
const { client } = useStatsigClient();
return (
{
await client.flush();
}}
>
Flush Events
);
```
## Parameter Stores
Parameter Stores hold a set of parameters for your mobile app. These parameters can be remapped on-the-fly from a static value to a Statsig entity (Feature Gates, Experiments, and Layers), so you can decouple your code from the configuration in Statsig. Read more about Param Stores [here](/client/concepts/parameter-stores).
## Manage Users
### Updating User Properties
Switch identities when a user logs in or when you collect richer attributes.
```tsx theme={null}
import { useGateValue, useStatsigUser } from '@statsig/react-bindings';
export default function AccountBanner() {
const gateValue = useGateValue('check_user');
const { updateUserAsync } = useStatsigUser();
return (
Gate is {gateValue ? 'passing' : 'failing'}.
updateUserAsync({ userID: '2' })}>Login
);
}
```
## Loading State
On a fresh page load with no cached values in `localStorage` (for example, an incognito window or a first visit), `isClientLoading` from `useStatsigClient` stays `true` until the SDK finishes fetching values from the network.
The recommended pattern is to initialize with `useClientAsyncInit` and pass the client to `StatsigProvider`, so your app waits for the initial fetch before rendering. Passing a `loadingComponent` directly to `StatsigProvider` is an equivalent shorthand.
```tsx theme={null}
import { StatsigProvider, useClientAsyncInit } from '@statsig/react-bindings';
export function App() {
const { client, isLoading } = useClientAsyncInit(
'client-KEY',
{ userID: 'a-user' },
);
if (isLoading) {
return Loading...
;
}
return (
);
}
```
```tsx theme={null}
import { StatsigProvider } from '@statsig/react-bindings';
export function App() {
return (
Loading...}
>
);
}
```
## React Hooks
Hooks that read gates, configs, experiments, or layers will log exposures on render. Use `useStatsigClient` to defer checks until you actually change the UI.
### Feature Gate Hooks
* Recommended: `useStatsigClient().checkGate` logs when invoked.
* `useGateValue` returns the boolean value and logs immediately.
* `useFeatureGate` returns the full gate object with details.
```tsx theme={null}
import {
useFeatureGate,
useGateValue,
useStatsigClient,
} from '@statsig/react-bindings';
const { checkGate } = useStatsigClient();
const gateValue = useGateValue('my_gate');
const gate = useFeatureGate('my_gate');
return (
{checkGate('my_gate') &&
Passing
}
{gateValue &&
Passing
}
{gate.value &&
Passing ({gate.details.reason})
}
Reason: {config.details.reason}
Value: {config.get('a_value', 'fallback_value')}
Another Value: {getDynamicConfig('my_dynamic_config').get('a_bool', false)}
);
```
### Experiment Hooks
* Recommended: `useStatsigClient().getExperiment` to control exposures.
* `useExperiment` logs on render.
```tsx theme={null}
import { useExperiment, useStatsigClient } from '@statsig/react-bindings';
const experiment = useExperiment('my_experiment');
const { getExperiment } = useStatsigClient();
return (
Group: {getExperiment('my_experiment').groupName}
Value: {experiment.get('a_value', 'fallback_value')}
);
```
### Layer Hooks
Layers only log exposures when you call `.get()`.
```tsx theme={null}
import { useLayer, useStatsigClient } from '@statsig/react-bindings';
const layer = useLayer('my_layer');
const { getLayer } = useStatsigClient();
return (
Group: {getLayer('my_layer').groupName}
Value: {layer.get('a_value', 'fallback_value')}
);
```
### Parameter Store Hooks
```tsx theme={null}
import { useParameterStore } from '@statsig/react-bindings';
function MyComponent() {
const store = useParameterStore('my_parameter_store');
const title = store.get('page_title', 'Default Title');
const maxItems = store.get('max_items', 10);
const isEnabled = store.get('feature_enabled', false);
const storeNoExposure = useParameterStore('my_parameter_store', {
disableExposureLog: true,
});
return {title}
;
}
```
### Log Events From Hooks
```tsx theme={null}
import { useStatsigClient } from '@statsig/react-bindings';
const { logEvent } = useStatsigClient();
return logEvent('my_event')}>Click Me ;
```
### StatsigUser Hook
```tsx theme={null}
import { useStatsigUser } from '@statsig/react-bindings';
const { user, updateUserSync } = useStatsigUser();
return (
Current User: {user.userID}
updateUserSync({ userID: 'some-other-user' })}>
Update User
);
```
### Direct Access to the Client
```tsx theme={null}
import { useStatsigClient } from '@statsig/react-bindings';
const { client } = useStatsigClient();
console.log('stableID', client.getContext().stableID);
```
### Client Initialization Hooks
* `useClientAsyncInit` — fetches the latest values before rendering.
* `useClientBootstrapInit` — bootstrap from server-provided values.
You can also initialize your own client instance manually. See Initialization Strategies for alternatives.
## Statsig Options
Controls logging behavior.
* `browser-only` (default): log events from browser environments.
* `disabled`: never send events.
* `always`: log in every environment, including non-browser contexts.
Use `loggingEnabled: 'disabled'` instead.
Skip generating a device-level Stable ID.
Recompute every evaluation instead of using the memoized result.
Override the generated session ID.
Persist Stable ID in cookies for cross-domain tracking.
Prevent any local storage writes (disables caching).
Override network endpoints per request type.
Base URL for all requests. The SDK appends endpoint paths like `/initialize` and `/rgstr`; append `/v1` when your proxy expects it.
Endpoint for initialization requests only. Takes precedence over `api` for `/initialize`.
Fallback endpoints for initialization requests only. This does not create a generic fallback for `api`.
Endpoint for event uploads.
Fallback endpoints for event uploads only. This does not create a generic fallback for `api`.
Request timeout in milliseconds.
Disable all outbound requests; combine with `loggingEnabled: 'disabled'` to silence log warnings.
Provide custom transport (e.g., Axios).
Set environment-wide defaults (for example `{ tier: 'staging' }`).
Console verbosity.
Max events per log batch.
Interval between automatic flushes.
Modify evaluations before returning them.
Attach the current page URL to logged events.
Send requests without Statsig-specific encoding.
Control compression for batched events.
Use `logEventCompressionMode` instead.
Provide a custom data adapter to control caching/fetching.
Override cache key generation for stored evaluations.
## Testing
Mock Statsig hooks in Jest to isolate component logic.
```tsx theme={null}
import { StatsigProvider, useFeatureGate, useExperiment } from '@statsig/react-bindings';
function Content() {
const gate = useFeatureGate('a_gate');
const experiment = useExperiment('an_experiment');
return (
a_gate: {gate.value ? 'Pass' : 'Fail'}
an_experiment: {experiment.get('my_param', 'fallback')}
);
}
function App() {
return (
);
}
```
```tsx theme={null}
import { render, screen } from '@testing-library/react';
import * as ReactBindings from '@statsig/react-bindings';
jest.mock('@statsig/react-bindings', () => ({
...jest.requireActual('@statsig/react-bindings'),
useFeatureGate: () => ({ value: true }),
useExperiment: () => ({ get: () => 'my_value' }),
}));
test('renders gate pass', async () => {
render(Loading...}>
Hello World
);
}
```
## Web Analytics / Auto Capture
By including the [`@statsig/web-analytics`](https://www.npmjs.com/package/@statsig/web-analytics) package in your project, you can automatically capture common web events like clicks and page views.
For more information on filtering events, enabling console log capture, and other configuration options available in web analytics, see the [Web Analytics Configuration](/webanalytics/overview#event-filtering-and-console-configuration) documentation.
```tsx theme={null}
import { StatsigProvider, useClientAsyncInit } from '@statsig/react-bindings';
import { StatsigAutoCapturePlugin } from '@statsig/web-analytics';
function App() {
const { client } = useClientAsyncInit(
'client-KEY',
{ userID: 'a-user' },
{ plugins: [new StatsigAutoCapturePlugin()] },
);
return (
Loading...}>
Hello World
);
}
```
## Using Persistent Evaluations
Keep experiment variants stable across rerenders or user transitions by plugging in persistent storage. The React integration mirrors the [JavaScript workflow](/client/javascript-sdk#using-persistent-evaluations) and you can adapt the [Next.js sample](https://github.com/statsig-io/js-client-monorepo/tree/main/samples/next-js/src/app/persisted-user-storage-example) to your setup.
Read more in [Client Persistent Assignment](/client/concepts/persistent_assignment).
## Additional Resources
* [Initialization Concepts](/client/concepts/initialize)
* [JavaScript Client SDK](/client/javascript-sdk)
* [Persistent Assignment](/client/concepts/persistent_assignment)
# React Native Client SDK
Source: https://docs.statsig.com/client/ReactNative
Install the Statsig React Native SDK to evaluate feature gates, run experiments, and log analytics events on iOS and Android React Native applications.
Source code: statsig-io/js-client-monorepo
## Setup the SDK
## Installation
Statsig uses a multi-package strategy, so you will need to install both the Statsig client and the React Native specific bindings.
```shell NPM theme={null}
npm install @statsig/react-native-bindings
```
```shell Yarn theme={null}
yarn add @statsig/react-native-bindings
```
### Peer Dependencies
The `@statsig/react-native-bindings` package has peer dependencies which may also need to be installed if they are not already in your project.
```shell NPM theme={null}
npm install react-native-device-info @react-native-async-storage/async-storage
```
```shell Yarn theme={null}
yarn add react-native-device-info @react-native-async-storage/async-storage
```
Next, 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 on in a gate or experiment.
## React Native + React Specific Setup
The setup for a ReactNative environment is very similar to a plain [React environment](/client/React).
The only difference is that you need to use the ReactNative specific `StatsigProviderRN`.
This automatically switches out the storage layer used by the SDK, utilizing [AsyncStorage](https://github.com/react-native-async-storage) instead of LocalStorage (which isn't available in RN environments).
```tsx theme={null}
import {
StatsigProviderRN,
useFeatureGate,
} from "@statsig/react-native-bindings";
function Content() {
const gate = useFeatureGate("a_gate");
// Reason: Network or NetworkNotModified
return (
Value: {gate.value ? "Pass" : "Fail"}
Reason: {gate.details.reason}
);
}
function App() {
return (
Loading...}
>
);
}
```
## Use the SDK
You can get an instance of the StatsigClient to check gates, experiments, dynamic configs, layers, and log events.
```jsx theme={null}
import { useStatsigClient } from "@statsig/react-native-bindings";
const { client } = useStatsigClient();
```
See the methods you can call on the client below.
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's check a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
You can evaluate a gate by getting the client with the `useStatsigClient` hook, and then calling `checkGate`
```tsx theme={null}
const { client } = useStatsigClient();
return (
Gate is {client.checkGate('check_user') ? 'passing' : 'failing'}.
);
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, **Dynamic Configs** can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
You can get a DynamicConfig value by getting the client with the `useStatsigClient` hook, and then calling `getConfig`
```tsx theme={null}
const { client } = useStatsigClient();
const config = client.getConfig('app_properties');
return (
{config.get('title', 'Default Title')}
);
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
You can access the experiment variant and parameters for the user by getting the client with the `useStatsigClient` hook, and then calling `getExperiment`.
```tsx theme={null}
const { client } = useStatsigClient();
const experiment = client.getExperiment('headline_test');
return (
Headline Parameter: {experiment.get('headline', 'Default')}.
);
```
You can access layers and layer parameters for the user by getting the client with the `useStatsigClient` hook, and then calling `getLayer`.
```tsx theme={null}
const { client } = useStatsigClient();
const layer = client.getLayer('homepage_layer');
return (
Headline Parameter: {layer.get('hero_text', 'Welcome')}.
);
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:
You can get the client with the `useStatsigClient` hook, and then call `logEvent`
```tsx theme={null}
const { client } = useStatsigClient();
return client.logEvent("button_click")}>Click Me
```
### Flushing Logged Events
`flush()` sends queued events immediately. Use `shutdown()` when your app is exiting.
```tsx theme={null}
import { Button } from 'react-native';
import { useStatsigClient } from '@statsig/react-native-bindings';
const { client } = useStatsigClient();
return (
{
await client.flush();
}}
/>
);
```
## Loading State
Dependent on your setup, you may want to wait for the latest values before checking a gate or experiment.
If you are using the `StatsigProviderRN`, you can pass in a `loadingComponent` prop to display a loading state while the SDK is initializing.
If you are using the `useClientAsyncInitRN` hook, you can check the `isLoading` prop to determine if the SDK is still loading.
```tsx theme={null}
export function App() {
const loadingComponent = Loading...
;
return (
);
}
```
```tsx theme={null}
export function App() {
const { client, isLoading } = useClientAsyncInitRN(...);
if (isLoading) {
return Loading...
;
}
return (
);
}
```
## 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:
```tsx theme={null}
import { useEffect } from 'react';
import { useStatsigClient } from '@statsig/react-native-bindings';
const { client } = useStatsigClient();
useEffect(() => {
return () => {
void client.shutdown();
};
}, [client]);
```
## Advanced
### StatsigClient Outside the Component Tree
In some scenarios, you may need to use the `StatsigClient` when you are not in the React component tree. Things like background tasks or handling notifications. For these, you can use the RN-specific `StatsigClientRN`.
```tsx theme={null}
import { StatsigClientRN } from '@statsig/react-native-bindings';
const myClient = new StatsigClientRN(
YOUR_CLIENT_KEY,
{ userID: "a-user" }
);
await myClient.initializeAsync();
if (myClient.checkGate("my_gate")) {
// do something cool
}
```
If you would like to access the StatsigClient instance that was created by the StatsigProvider outside of the component tree, you can use the `StatsigClientRN.instance()` method. This will return the first StatsigClient instance that was created. If you have multiple instances, you can pass in the SDK key to get a specific instance.
```tsx theme={null}
// Inside the component tree
function App() {
return
...
}
// Outside the component tree
const client = StatsigClientRN.instance(); // get the first created instance
const client = StatsigClientRN.instance(YOUR_CLIENT_KEY); // get a specific instance by SDK key
```
### Synchronous Storage with MMKV
Due to the lack of LocalStorage in ReactNative environments, by default the SDK will prefetch all Statsig cache entries during initialization.
If you are utilizing MMKV in your project, and would prefer to use that instead of the default (AsyncStorage). You can provide you own `StorageProvider` via `StatsigOptions`.
Something like:
```tsx theme={null}
import { MMKV } from "react-native-mmkv";
import { StorageProvider } from "@statsig/client-core";
import { StatsigProviderRN } from '@statsig/react-native-bindings';
function App() {
const [storageProvider] = useState(() => {
const mmkv = new MMKV();
return {
isReady: () => true,
isReadyResolver: () => null,
getProviderName: () => "MMKV",
getAllKeys: () => mmkv.getAllKeys(),
getItem: (key: string) => mmkv.getString(key) ?? null,
setItem: (key: string, value: string) => mmkv.set(key, value),
removeItem: (key: string) => mmkv.delete(key),
};
});
return (
...
);
}
```
# React Native On-Device Evaluation
Source: https://docs.statsig.com/client/ReactNativeOnDeviceEvaluation
Use the Statsig React Native on-device evaluation SDK to evaluate feature gates and experiments locally with low latency for mobile React Native apps.
**Tip:** Get started quickly with one of our [sample apps](https://github.com/statsig-io/js-client-monorepo/tree/main/samples)!
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](/client/onDevice). On-device evaluation SDKs are for Enterprise & Pro Tier only.
These SDKs use a different paradigm than their precomputed counterparts: [JS](/client/javascript-sdk), [Android](/client/Android), [iOS](/client/iosClientSDK), 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](/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)
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](/client/jsOnDeviceEvaluationSDK) is also relevant for React Native implementations.
## Set Up 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.
```shell npm theme={null}
npm install @statsig/react-native-bindings-on-device-eval
```
```shell yarn theme={null}
yarn add @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.
```shell npm theme={null}
npm install @react-native-async-storage/async-storage
```
```shell yarn theme={null}
yarn add @react-native-async-storage/async-storage
```
Next, 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 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.
When creating a new client key, select **"Allow Download Config Specs"**
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**.
## 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](https://github.com/react-native-async-storage) instead of LocalStorage (which isn't available in RN environments).
```tsx theme={null}
import {
StatsigProviderOnDeviceEvalRN,
useFeatureGate,
} from '@statsig/react-native-bindings-on-device-eval';
function Content() {
const gate = useFeatureGate('a_gate');
return Reason: {gate.details.reason}
; // Reason: Network or NetworkNotModified
}
function App() {
return (
...}
>
);
}
```
## 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](#statsig-user).
```typescript theme={null}
const myUser = {
userID: "a-user",
email: "user@statsig.com"
};
```
## React Hooks
### useGateValue or useFeatureGate
```typescript theme={null}
import { useGateValue } from '@statsig/react-native-bindings-on-device-eval';
const gateValue = useGateValue('a_gate', { userID: "a-user" }); // <-- Returns the boolean value
if (gateValue) {
//
}
```
```typescript theme={null}
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
```typescript theme={null}
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
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.
The URL used to flush queued events via a POST request. Takes precedence over `StatsigOptions.api`.
The URL used to flush queued events via `window.navigator.sendBeacon` (web only). Takes precedence over `StatsigOptions.api`.
The URL used to fetch your latest Statsig specifications. Takes precedence over `StatsigOptions.api`.
An object you can use to set environment variables that apply to all of your users in the same session.
Overrides the auto-generated stableID that is set for the device.
How much information is allowed to be printed to the console.
Implementing this type allows customization of the initialization. See [Using SpecsDataAdapter](/client/js-on-device-eval-client/using-evaluations-data-adapter) to learn more.
The maximum amount of time (in milliseconds) that any network request can take before timing out.
The maximum number of events to batch before flushing logs to Statsig.
How often (in milliseconds) to flush logs to Statsig.
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
```typescript theme={null}
// 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 theme={null}
// 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 theme={null}
// 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 theme={null}
// 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:
```typescript theme={null}
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](/client/javascript/using-evaluations-data-adapter) to learn more and see example usage.
## Additional Resources
* [On-Device Evaluation SDK Overview](/client/onDevice)
* [JavaScript On-Device Evaluation SDK](/client/jsOnDeviceEvaluationSDK)
* [Client Keys with Server Permissions](/access-management/api-keys#client-keys-with-server-permissions)
* [Using EvaluationsDataAdapter](/client/javascript/using-evaluations-data-adapter)
* [Debugging SDK Evaluations](/sdk/debugging)
# Roku Client SDK
Source: https://docs.statsig.com/client/Roku
Install the Statsig Roku SDK to evaluate feature gates, run experiments, and log analytics events from BrightScript and SceneGraph Roku applications.
Source code: statsig-io/roku-sdk
## Setup the SDK
You can start by downloading a copy of [the GitHub repository](https://github.com/statsig-io/roku-sdk). Roku does not have a package manager where we could release an SDK, so instead, you will copy over the implementation from this repository to integrate Statsig in your Roku app.
You will need the following files:
```
Statsig
-- components
-- statsigsdk
-- StatsigTask.brs
-- StatsigTask.xml
-- source
-- DynamicConfig.brs
-- Statsig.brs
-- StatsigClient.brs
-- StatsigUser.brs
```
The library consists of two main parts:
* **source/Statsig** - an object used by SceneGraph components that connects a StatsigClient with the background StatsigTask.
* **components/StatsigTask** - a SceneGraph Task to do work in the background for integrating with Statsig like batching events and fetching values from Statsig servers.
The "components" folder contains SceneGraph components and the "source" folder contains BrightScript files. All of these files must be included in their respective folders of the application. Note that if you change the file paths, you will need to update the file references in `StatsigTask.xml`. You will also need to include those references in your main XML file.
Next, 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 on in a gate or experiment.
To Initialize the SDK, you first need to integrate the SDK files into your application.
Include `StatsigClient.brs`, `StatsigUser.brs`, `DynamicConfig.brs`, and `Statsig.brs`:
```xml theme={null}
```
Next, you can initialize the library in your init() function, and add a listener for when gates/experiments have been fetched:
```xml theme={null}
", user)
```
For more information on all of the user fields you can use, see the [StatsigUser docs](/concepts/user).
Before the SDK has loaded the updated values, all APIs will return default values (false for gates, empty configs and experiments).
To implement a callback handler for Statsig being ready, and tell the SDK to load the updated values in the `onStatsigReady` function observed above:
```brightscript theme={null}
function onStatsigReady() as void
m.statsig.load()
// Check gates, log events, check experiments, etc
gate = m.statsig.checkGate("gate_id")
config = m.statsig.getConfig("config_id")
experiment = m.statsig.getExperiment("experiment_id")
m.statsig.logEvent("event_name", "event_value", {metadata: "event_metadata"})
end function
```
If you need to update the user, `m.statsig.updateUser(newUser)` will trigger the same `onStatsigReady` callback once the new gate/config/experiment values have been fetched from Statsig servers.
# Unity SDK
Source: https://docs.statsig.com/client/Unity
Install the Statsig Unity SDK to evaluate feature gates, run experiments, and log analytics events from Unity games on mobile, console, and desktop platforms.
Source code: statsig-io/unity-sdk
## Setup the SDK
The project is on [GitHub](https://github.com/statsig-io/unity-sdk). You can add the package to your Unity project via "Package Manager" -> "add package from Git URL" -> enter [https://github.com/statsig-io/unity-sdk.git](https://github.com/statsig-io/unity-sdk.git) (be sure to include the `.git` part in the URL)
Next, 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 on in a gate or experiment.
It is important to **make sure API calls to `Statsig` are made from the main thread** to ensure everything functions correctly. Operations that take longer like network requests are made asynchronously so they will not block the main thread.
```csharp theme={null}
using StatsigUnity;
await Statsig.Initialize(
"client-sdk-key",
new StatsigUser { UserID = "some_user_id", Email = "user@email.com" },
new StatsigOptions // optional parameters to customize your Statsig client, see "Statsig Options" section below to see details on available options
{
EnvironmentTier = EnvironmentTier.Development,
InitializeTimeoutMs = 5000,
}
);
```
## Use the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's check a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
```csharp theme={null}
if (Statsig.CheckGate("show_new_loading_screen"))
{
// Gate is on, show new loading screen
}
else
{
// Gate is off, show old loading screen
}
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, **Dynamic Configs** can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```csharp theme={null}
var config = Statsig.GetConfig("awesome_product_details");
// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
string itemName = config.Get("product_name", "Awesome Product v1");
double price = config.Get("price", 10.0);
bool shouldDiscount = config.Get("discount", false);
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```csharp theme={null}
// Values via getLayer
var layer = Statsig.GetLayer("user_promo_experiments");
var promoTitle = layer.Get("title", "Welcome to Statsig!");
var discount = layer.Get("discount", 0.1);
// or, via getExperiment
var titleExperiment = Statsig.GetExperiment("new_user_promo_title");
var priceExperiment = Statsig.GetExperiment("new_user_promo_price");
var promoTitle = titleExperiment.Get("title", "Welcome to Statsig!");
var discount = priceExperiment.Get("discount", 0.1);
...
double price = msrp * (1 - discount);
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:
```csharp theme={null}
Statsig.LogEvent(
"purchase",
"new_player_pack",
new Dictionary() {
{ "price", "9.99" }
}
);
```
## 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](/guides/first-device-level-experiment) 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:
```csharp theme={null}
// if you want to update the existing user, or change to a different user, call UpdateUser.
// The API makes a network request to fetch values for the new user.
await Statsig.UpdateUser(
new StatsigUser { UserID = "new_user_id", Email = "new_user@email.com" },
);
```
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Statsig Options
`Initialize()` takes an optional parameter `options` in addition to `clientKey` and `user` that you can provide to customize the Statsig client.
Set the environment tier for the user. Values: `Production | Development | Staging`.
Users with `null` or `Production` tier are included in Pulse metrics by default.
Maximum milliseconds `Statsig.Initialize()` will wait before proceeding with cached/default values.
Interval for periodically flushing logging events to the Statsig backend.
Maximum number of events the logger batches before flushing.
## 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:
```csharp theme={null}
// This function is async, and you can choose to await for it so that we make sure all the
// events that are yet to be flushed get flushed
await Statsig.Shutdown();
```
## FAQs
#### How do I run experiments for logged out users?
See the guide on [device level experiments](/guides/first-device-level-experiment)
# Android On Device Evaluation SDK
Source: https://docs.statsig.com/client/androidOnDeviceEvaluationSDK
Use the Statsig Android on-device evaluation SDK to evaluate feature gates and experiments locally for fast, low-latency rules evaluation on devices.
Source code: statsig-io/android-local-eval
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/onDevice). On-device evaluation SDKs are for Enterprise & Pro Tier only.
These SDKs use a different paradigm than their precomputed counterparts: [JS](/client/javascript-sdk), [Android](/client/Android), [iOS](/client/iosClientSDK), 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](/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
You can install the SDK using JitPack. See the latest version and installation steps at [https://jitpack.io/#statsig-io/android-local-eval](https://jitpack.io/#statsig-io/android-local-eval).
Next, 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 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.
When creating a new client key, select **"Allow Download Config Specs"**
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**.
```java Java theme={null}
import com.statsig.androidlocalevalsdk.*;
// ...
android.app.Application app = // ref to your Application instance
StatsigOptions opts = new StatsigOptions();
opts.setEnvironmentParameter("tier", "staging");
StatsigClient client = Statsig.INSTANCE.getClient();
client.initializeAsync(
app,
"client-YOUR_CLIENT_SDK_KEY",
new IStatsigCallback() {
@Override
public void onStatsigInitialize(@NotNull InitializationDetails initDetails) {
// Statsig Ready
}
@Override
public void onStatsigInitialize() {
// deprecated
}
},
opts
);
// or, create your own instance of StatsigClient
StatsigClient client = new StatsigClient();
client.initializeAsync(...);
```
```kotlin Kotlin theme={null}
import com.statsig.androidlocalevalsdk.*
// ...
val opts = StatsigOptions()
opts.setEnvironmentParameter("tier", "staging")
Statsig.client.initializeAsync(
application, // ref to your Application instance
"client-YOUR_CLIENT_SDK_KEY",
object : IStatsigCallback {
override fun onStatsigInitialize(initDetails: InitializationDetails) {
// Statsig Ready
}
override fun onStatsigInitialize() {
// deprecated
}
},
opts
)
// or, create your own instance of StatsigClient
val client = StatsigClient()
client.initializeAsync(...)
```
### Synchronous Initialization
```kotlin theme={null}
import com.statsig.androidlocalevalsdk.*
// (optional) Configure the SDK if needed
val opts = StatsigOptions()
opts.environment.tier = "staging"
val specs = "..." // JSON string of your configurations
let details = Statsig.client.initializeSync(application, "client-YOUR_CLIENT_SDK_KEY", specs, opts)
```
It is possible to configure the SDK to use cached values if they are newer than the local file.
This can be useful if you ship your app with a local file, but would like it to only be used for the first session.
In the following example, the SDK will only use initialSpecs if there is no cache or if the cache is older than initialSpecs.
```kotlin theme={null}
val options = StatsigOptions()
options.useNewerCacheValuesOverProvidedValues = true
Statsig.client.initializeSync(
application,
"client-YOUR_CLIENT_SDK_KEY",
specs,
options
)
```
You can get a copy of your current specs data by visiting: `https://api.statsigcdn.com/v1/download_config_specs/client-{YOUR_SDK_KEY}.json`
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's check a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
```java Java theme={null}
StatsigUser user = new StatsigUser("a-user");
StatsigClient client = Statsig.INSTANCE.getClient();
if (client.checkGate(user, "new_homepage_design")) {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
```
```kotlin Kotlin theme={null}
val user = StatsigUser("user_id")
if (Statsig.client.checkGate(user, "new_homepage_design")) {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, **Dynamic Configs** can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```java Java theme={null}
StatsigUser user = new StatsigUser("a-user");
StatsigClient client = Statsig.INSTANCE.getClient();
DynamicConfig config = client.getConfig(user, "awesome_product_details");
// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
String itemName = config.getString("product_name", "Awesome Product v1");
Double price = config.getDouble("price", 10.0);
Boolean shouldDiscount = config.getBoolean("discount", false);
```
```kotlin Kotlin theme={null}
val user = StatsigUser("user_id")
val config = Statsig.client.getConfig(user, "awesome_product_details")
// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
val itemName = config.getString("product_name", "Awesome Product v1")
val price = config.getDouble("price", 10.0)
val shouldDiscount = config.getBoolean("discount", false)
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```java Java theme={null}
StatsigUser user = new StatsigUser("a-user");
StatsigClient client = Statsig.INSTANCE.getClient();
// Values via getLayer
Layer layer = client.getLayer(user, "user_promo_experiments")
String promoTitle = layer.getString("title", "Welcome to Statsig!");
Double discount = layer.getDouble("discount", 0.1);
// or, via getExperiment
DynamicConfig titleExperiment = client.getExperiment(user, "new_user_promo_title");
DynamicConfig priceExperiment = client.getExperiment(user, "new_user_promo_price");
String promoTitle = titleExperiment.getString("title", "Welcome to Statsig!");
Double discount = priceExperiment.getDouble("discount", 0.1);
...
Double price = msrp * (1 - discount);
```
```kotlin Kotlin theme={null}
val user = StatsigUser("user_id")
// Values via getLayer
val layer = Statsig.client.getLayer(user, "user_promo_experiments")
val promoTitle = layer.getString("title", "Welcome to Statsig!")
val discount = layer.getDouble("discount", 0.1)
// or, via getExperiment
val titleExperiment = Statsig.client.getExperiment(user, "new_user_promo_title")
val priceExperiment = Statsig.client.getExperiment(user, "new_user_promo_price")
val promoTitle = titleExperiment.getString("title", "Welcome to Statsig!")
val discount = priceExperiment.getDouble("discount", 0.1)
...
val price = msrp * (1 - discount);
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:
```java Java theme={null}
StatsigUser user = new StatsigUser("user_id");
StatsigClient client = Statsig.INSTANCE.getClient();
client.logEvent(user, "purchase", 2.99, Map.of("item_name", "remove_ads"));
```
```kotlin Kotlin theme={null}
val user = StatsigUser("user_id")
Statsig.client.logEvent(user, "purchase", 2.99, mapOf("item_name" to "remove_ads"))
```
### Code Examples
Working sample apps are available in the repository:
* [Java & Kotlin Examples](https://github.com/statsig-io/android-local-eval/tree/main/samples)
## 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](/guides/first-device-level-experiment) 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:
The endpoint to use for downloading config spec network requests. You should not need to override this (unless you have another API that implements the Statsig API endpoints).
The endpoint to use for log events. You should not need to override this (unless you have another API that implements the Statsig API endpoints).
Milliseconds to wait for the initial network request before calling the completion block. The Statsig client will return either cached values (if any) or default values if checkGate/getConfig/getExperiment is called before the initial network request completes. Set to `0` to wait indefinitely for the latest values.
Overrides the `stableID` in the SDK that is set for the user.
Whether or not the SDK should block on loading saved values from disk.
Provide the `download_config_specs` response values directly to the Android SDK to synchronously initialize the client. You can get a copy of your current specs data by visiting: `https://api.statsigcdn.com/v1/download_config_specs/client-{YOUR_SDK_KEY}.json`
Prevent the SDK from sending useful debug information to Statsig.
#### Methods
* **setTier | setEnvironmentParameter | getEnvironment**
* Used to signal the environment tier the user is currently in.
* `setTier` can be PRODUCTION, STAGING or DEVELOPMENT. e.g. passing in a value of `Tier.STAGING` will allow your users to pass any condition that pass for the staging environment tier, and fail any condition that only passes for other environment tiers.
* `setEnvironmentParameter` can be used for custom tiers, eg `options.setEnvironmentParameter("tier", "test")`
## 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:
```java Java theme={null}
Statsig.shutdown();
```
```kotlin Kotlin theme={null}
Statsig.shutdown()
```
## Post Init Syncing
### From Network
By default, the SDK will only sync during initialization. If you would like to re-sync after initialization, you can call the `Statsig.client.updateAsync` method.
This will trigger a network call to fetch the latest changes from the server.
```kotlin theme={null}
val details = Statsig.client.updateAsync()
```
### Scheduled Polling
If you would like the SDK to regularly poll for updates, you can start the polling task with `Statsig.client.scheduleBackgroundUpdates()`.
This will hit the network and pull down the latest changes.
```kotlin theme={null}
val pollingTask = Statsig.cloent.scheduleBackgroundUpdates() // Defaults to 1 hour interval
// or, specify a custom interval
val intervalSeconds = 300
val pollingTask = Statsig.client.scheduleBackgroundUpdates(intervalSeconds)
// and, if you need to cancel it later
pollingTask?.cancel()
```
## Using Persistent Evaluations
If you want to ensure that a user's variant stays consistent while an experiment is running, regardless of changes to allocation or targeting, you can implement the `UserPersistentStorageInterface` and set it in `StatsigOptions` when you initialize the SDK.
#### Synchronous Persistent Evaluations
The `UserPersistentStorageInterface` exposes two methods for synchronous persistent storage, which will be called by default when evaluating an experiment.
```
interface UserPersistentStorageInterface {
suspend fun load(key: String): PersistedValues
fun save(key: String, experimentName: String, data: String)
fun delete(key: String, experiment: String)
...
}
```
The `key` string is a combination of ID and ID Type: e.g. "123:userID" or "abc:stableID" which the SDK will construct and call `get` and `set` on by default
You can use this interface to persist evaluations synchronously to local storage. If you need an async interface, read on.
#### Asynchronous Persistent Evaluations
The `UserPersistentStorageInterface` exposes two methods for asynchronous persistent evaluations. Because the `getExperiment` call is synchronous, you must load the value first, and pass it in as `userPersistedValues`
```kotlin theme={null}
interface UserPersistentStorageInterface {
fun loadAsync(key: String, callback: IPersistentStorageCallback)
fun save(key: String, experimentName: String, data: String)
fun delete(key: String, experiment: String)
...
}
interface IPersistentStorageCallback {
fun onLoaded(values: PersistedValues)
}
```
For your convenience, we've created a top level method to load the value for a given user and ID Type:
```kotlin theme={null}
// Asynchronous load values
val userPersistedValues = Statsig.client.loadUserPersistedValuesAsync(
user: StatsigUser,
idType: string, // userID, stableID, customIDxyz, etc
callback: IPersistentStorageCallback
);
// Synchronous load values
val userPersistedvalues = Statsig.client.loadUserPersistedValues(
user: StatsigUser,
idType: string, // userID, stableID, customIDxyz, etc
)
```
Putting it all together, assuming you have implemented the `UserPersistentStorageInterface` and set it on `StatsigOptions`, your call site will look like this:
```kotlin theme={null}
// Asynchronous
val callback = object: IPersistentStorageCallback {
@override
fun onLoaded(values: PersistedValues) {
Statsig.getExperiment(user, "sample_experiment", GetExperimentOptions(userPersistedValues = values))
}
}
val userValues = Statsig.client.loadUserPersistedValuesAsync(user, "userID", callback)
// Synchronous
val user = StatsigUser(userID = "user123")
val userValues = Statsig.client.loadUserPersistedValues(user, 'userID');
const experiment = statsig.getExperiment({userID: "123"}, 'the_allocated_experiment', { userPersistedValues: userValues });
```
If you are using java, you can only override loadAsync function and ignore load function as empty.
## Local Overrides
It is possible to override the values returned by the Statsig SDK. This can be useful in unit testing or for enabling features for local development.
To get setup with local overrides, you can pass an instance of `LocalOverrideAdapter` to the SDK via the `StatsigOptions` object.
It is possible to write your own override adapter. You can implement the [`IOverrideAdapter`](https://github.com/statsig-io/android-local-eval/blob/main/src/main/java/com/statsig/androidlocalevalsdk/IOverrideAdapter.kt) interface and pass that in instead.
```kotlin Kotlin theme={null}
val user = StatsigUser("user-a")
val overrides = LocalOverrideAdapter()
// Override a gate
overrides.setGate(user, "local_override_gate", true)
// Override a dynamic config (Similar for Layer and Experiment)
val config = DynamicConfig("local_override_dynamic_config", mapOf("key" to "val"))
overrides.setConfig(user, config)
val opts = StatsigOptions()
opts.overrideAdapter = overrides
Statsig.client.initializeAsync(
app,
YOUR_SDK_KEY,
callback,
opts // <- Pass in StatsigOptions
)
```
```java Java theme={null}
StatsigUser user = new StatsigUser("a-user");
LocalOverrideAdapter overrides = new LocalOverrideAdapter();
// Override a gate
overrides.setGate(user, "local_override_gate", true);
// Override a dynamic config (Similar for Layer and Experiment)
HashMap configValue = new HashMap() {};
DynamicConfig config = new DynamicConfig(
"local_override_dynamic_config",
configValue,
"local_override",
null,
new ArrayList>(),
null
);
overrides.setConfig(user, config);
StatsigOptions opts = new StatsigOptions();
opts.setOverrideAdapter(overrides);
StatsigClient client = Statsig.INSTANCE.getClient();
client.initializeAsync(
app,
YOUR_SDK_KEY,
callback,
opts // <- Pass in StatsigOptions
);
```
## FAQs
See the guide on [device level experiments](/guides/first-device-level-experiment).
## Additional Resources
* [On-Device Evaluation SDK Overview](/client/onDevice)
* [Client Keys with Server Permissions](/access-management/api-keys#client-keys-with-server-permissions)
* [Debugging SDK Evaluations](/sdk/debugging)
# Initializing SDKs
Source: https://docs.statsig.com/client/concepts/initialize
Initialize Statsig client SDKs correctly across web, mobile, and React Native applications to ensure feature gates and experiments evaluate as expected.
The first step in using a Statsig SDK is calling `initialize()`, which retrieves the values you need to evaluate experiments & send events. Before initialization, Statsig SDKs won't have latest values in-memory, and therefore may return stale values or none at all.
Unlike Server SDK initialization, which happens at Server startup, Client SDK initialization happens when a screen is rendered - meaning initialization can have more impact on user experience. Statsig offers several client initialization methods to tune performance to your needs.
## General Initialization Flow
`initialize` will take an SDK key and `StatsigUser` object. The SDK will then:
1. Check local storage for cached values. The SDK caches the previous evaluations locally so they are available on the next session if there isn't a successful network call
2. Create a `STATSIG_STABLE_ID` - an ID that stays consistent per-device, which can often be helpful for logged-out experiments.
3. Set the SDK as initialized so checks won't throw errors - they will either return cached values or defaults.
4. Issue a network request to Statsig to get the latest values for all gates/experiments/configs/layers/autotunes for the given user. If the project definition does not change from the most recent cached values, this request may succeed without returning new data.
5. Resolve the asynchronous `initialize` call. If the request to the server failed, the SDK will have the cached values or return defaults for this session.
Depending on when you check a gate or experiment after initializing, it's possible that you may not have retrieved fresh values yet. Awaiting initialization solves this, with some performance downsides (discussed below).
## Client Initialization Strategies
Below are the various strategies summarized at a high level, ordered from most common to least common:
* [**Asynchronous Initialization (Awaited)**](#1-asynchronous-initialization-awaited): Wait for the initialization network call to finish before rendering content.
* [**Bootstrap Initialization**](#2-bootstrap-initialization): Generate the assignment values on your own server, and pass them down with other request, resulting in zero-latency rendering. Best of both worlds for latency and availability of fresh assignments, but requires additional engineering effort.
* [**Asynchronous Initialization (Not Awaited)**](#3-asynchronous-initialization-not-awaited): Do not await the return of the initialization network call. This ensures immediate rendering, but in a state that reflects stale assignments or no assignments available.
* [**Synchronous Initialization**](#4-synchronous-initialization): Renders immediately, but with stale or no assignments available. First-visit users will never be assigned to gates and experiments.
| Method | Speed-to-render? | Render consistency? | Latest content? | Engineering Complexity? |
| ----------------------- | ----------------------------------------------------------- | ------------------------------------- | --------------------------------------------------- | ------------------------------ |
| **Explanation** | When I visit the webpage, how fast does the content appear? | Does the content ever change/flicker? | Does the user ever see an out-of-date config value? | How easy is this to implement? |
| Await InitializeAsync() | ❌ Slow | ✅ Good | ✅ Yes | ✅ Easy |
| InitializeAsync() | ✅ Fast | ❌ Poor | ✅ Yes | ✅ Easy |
| InitializeSync() | ✅ Fast | ✅ Good | ❌ No | ✅ Easy |
| BootstrapInit | ✅ Fast | ✅ Good | ✅ Yes | ❌ Extra Effort |
### 1. Asynchronous Initialization - Awaited
> Ensures latest assignments but requires a loading state
When calling `StatsigClient.initializeAsync`, the client loads values from the cache and fetches the latest values from the network. This approach waits for the latest values before rendering, which means it is not immediate but ensures the values are up-to-date.
```tsx React Example theme={null}
const { client, isLoading } = useClientAsyncInit(
YOUR_CLIENT_KEY,
{ userID: "u_123" }
);
if (isLoading) {
return Loading...
;
}
// Continue with initialized client
```
```js JavaScript Example theme={null}
const client = new StatsigClient(YOUR_CLIENT_KEY, { userID: "u_123" });
await client.initializeAsync();
// Client is now initialized with latest values
```
### 2. Bootstrap Initialization
> Ensures both latest assignments with no rendering latency
Bootstrapping allows you to initialize the client with a JSON string. This approach ensures that values are immediately available without the client making any network requests. Note that you will be responsible for keeping these values up to date.
With this approach, your server will be responsible for serving the configuration payload to your client app on page load (for web implementations) or during app launch (for mobile implementations).
```tsx React Bootstrap theme={null}
// Server-generated initialization values
const initValues = getStatsigValuesFromServer(user);
const client = useClientBootstrapInit(
YOUR_CLIENT_KEY,
{ userID: "u_123" },
initValues
);
// Client renders immediately with server values — no network request
```
```js JavaScript Bootstrap theme={null}
const bootstrapValues = getInitializationValuesFromServer();
const client = new StatsigClient(YOUR_CLIENT_KEY, { userID: "u_123" });
client.dataAdapter.setData(bootstrapValues);
client.initializeSync();
```
### 3. Asynchronous Initialization - Not Awaited
If you want to fetch the latest values without awaiting the asynchronous call, you can call `initializeAsync` and catch the promise.
This approach provides immediate rendering with cached values initially, which will update to the latest values mid-session.
Be aware that the values may switch when checked a second time after the latest values have been loaded.
### 4. Synchronous Initialization
> Ensures immediate rendering but uses cached assignments (when available)
When calling `StatsigClient.initializeSync`, the client uses cached values if they are available. The client fetches new values in the background and updates the cache. This approach provides immediate rendering, but the values might be stale or absent during the first session.
These strategies help you balance the need for the latest gate / experiment assignment information with the need for immediate application rendering based on your specific requirements.
## General Initialization Flow
Server SDKs require only a secret key to initialize. As most servers are expected to deal with many users - server SDKs download all rules and configurations you have in your project and evaluate them in realtime for each user that is encountered. The process for Server SDK initialization looks something like this:
1. Your server checks if you have locally cached values (which you can set up with a [DataAdapter](/server/concepts/data_store/))
2. If your server found values on the last call, it'll be ready for checks with the reason "DataAdapter". Whether it found local data or not, it'll next go to the network to find updated values.
3. The Server retrieves updated rules from the server, and is now ready for checks even if it didn't find values in step 1.
4. Going forward, the server will retrieve new values every 10 seconds from the server, updating the locally cached values each time.
DataAdapters provide a layer of resilience, and ensure your server is ready to serve requests as soon as it starts up rather than waiting for a network roundtrip, which can be especially valuable if you have short-lived or serverless instances. While only recommended for advanced setups, Statsig also offers a [Forward Proxy](/server/concepts/forward_proxy/) that can add an extra layer of resilience to your server setup.
```js Node.js Initialization theme={null}
import { Statsig, StatsigUser } from '@statsig/statsig-node-core';
const statsig = new Statsig("YOUR_SERVER_KEY");
await statsig.initialize();
// Server SDK is now ready to evaluate gates/experiments for any user
const user = new StatsigUser({ userID: "123" });
const gate = statsig.checkGate(user, "my_gate");
```
```python Python Initialization theme={null}
from statsig_python_core import Statsig, StatsigUser
statsig = Statsig("YOUR_SERVER_KEY")
statsig.initialize().wait()
# Server SDK is now ready
user = StatsigUser("123")
gate = statsig.check_gate(user, "my_gate")
```
# Local Eval Adapter
Source: https://docs.statsig.com/client/concepts/local-eval-adapter
Use the local evaluation data adapter in Statsig client SDKs to bootstrap evaluations from a custom data source, file, or server-rendered payload.
## Local Eval Adapter
A common limitation of experimentation systems is the **dependence on an upfront network requests to fetch experiment configurations**. While concepts like [Bootstrapping](/client/concepts/initialize#2-bootstrap-initialization) and [Synchronous Initialization](/client/concepts/initialize#4-synchronous-initialization) can provide alternatives, both have caveats that are sometimes prohibitive: Bootstrapping still requires an upfront request (though it can be made synchronous with other requests), and Synchronous Initialization Strategies can result in out-of-date configs (by one session).
The Local Eval Adapter solves this by enabling you to ship your experiment configurations inline with your application, meaning you can run experiments before initialization completes. The adapter expects a ruleset explaining your experiments, similar to Statsig's Server SDKs - see the [Example Ruleset below](#example-ruleset-config-spec).
## Limitations
Shipping with a ruleset presents security concerns, but given that the experiment set can be scoped to only an experiment or two occurring before any network requests, those concerns are often minimal. However, we expect users to take caution shipping a ruleset in their production code, vetting the contents are correct and safe.
## Usage & Functionality
The Local Eval Adapter, with proper attention to security, and maintenance of the ruleset in your application, **addresses the downsides of other experiment-at-launch strategies**.
The local evaluation adapter is for Enterprise and Pro Tier companies only. If you are trying to follow these instructions but do not meet that criteria, some of the setup steps may not work.
The Adapter manifests as a StatsigOptions object seeded with a ruleset payload:
```swift theme={null}
Statsig.initialize(
sdkKey: "client-sdkkey",
user: user,
options: StatsigOptions(
overrideAdapter: OnDeviceEvalAdapter(stringPayload: onDeviceEvalAdapterRulesetPayload)
)
) { err in
// Initialization completed. `err` is `nil` if it was successful
}
```
```kotlin theme={null}
val adapter = OnDeviceEvalAdapter("...") // dcs payload as string
val user = StatsigUser("a-user")
Statsig.initializeAsync(application, "client-sdk", user, object : IStatsigCallback {
override fun onStatsigInitialize() {
println(adapter.getGate(Statsig.getFeatureGate("a_gate"), user)?.details?.reason) // [OnDevice] Bootstrap:Recognized
println(Statsig.getFeatureGate("a_gate").details.reason) // Network:Recognized
}
})
```
```js theme={null}
const adapter = new OnDeviceEvalAdapter();
adapter.setData('...'); // dcs payload as string
const client = new StatsigClient(
'client-...',
{ userID: 'a-user' },
{
overrideAdapter: adapter,
},
);
// purposely not awaiting this, will use local specs until network is resolved
const isReady = client.initializeAsync();
const localEvalGate = client.getFeatureGate('a_gate');
console.log(localEvalGate.details.reason); // [OnDevice] Bootstrap:Recognized
await isReady;
const networkEvalGate = client.getFeatureGate('a_gate');
console.log(networkEvalGate.details.reason); // Network:Recognized
```
### Example Ruleset "Config Spec"
The ruleset is a JSON object that contains the following fields:
```json theme={null}
{
"feature_gates": [],
"dynamic_configs": [],
"layer_configs": [],
"time": 1735718400000
}
```
Your ruleset can be retrieved by API, and we recommend using target apps to scope the ruleset to only the experiments and feature gates you need on startup. If you need help, reach out to us in your Slack Channel or our [community Slack](https://statsig.com/slack).
# Parameter Stores
Source: https://docs.statsig.com/client/concepts/parameter-stores
Use Statsig Parameter Stores to map dynamic config or experiment parameters to runtime values in client SDKs with type-safe access patterns.
Parameter Stores provide a new way to organize and manage parameters in your web or mobile app via the Statsig console. Now available for JS, React, React Native, Android, iOS, and Dart SDKs on the client side and java, node, python, and rust on the server side. Let us know in [Slack](https://statsig.com/slack) if you'd like support in a certain language soon.
## What is a Parameter Store?
Rather than thinking in terms of Statsig entities like Feature Gates, Experiments, Layers, or Dynamic Configs, Parameter Stores let you focus on **parameters**—the values in your app that need to be configurable remotely.
Parameter Stores **decouple your code from configuration, indefinitely**. This abstraction allows you to run experiments, adjust gating, or change values on the fly— **without hardcoding any experiment/gate names**. Instead you define *parameters* that can be remapped remotely to any value or any Statsig entity.
## An Example: Parameterizing the Statsig Website
While usually release cycles are more painful on platforms like mobile, take the example of the Statsig Website - perhaps our marketing team asks for frequent updates, so we'd prefer to parameterize the text, images, buttons, colors and more:
);
```
## How to Use Parameter Stores
Here’s a suggested workflow:
1. **Create a Parameter Store**:
Set up a Parameter Store for your team or project. Parameter Stores are designed to hold related parameters in one object.
2. **Identify Configuration Variables**:
Consider which variables you want to decouple from your app and control via Statsig rather than hardcoding them in your app. These could include:
* A boolean parameter to control access to a new feature. Even if you're used to using Feature Gates for boolean feature management, start with a boolean parameter instead.
* A string parameter for text resources that you may want to swap or experiment with.
* A number parameter for inputs such as the number of onboarding steps, a list length to truncate, and more.
3. **Start with Static Values**:
Begin with a static value for each parameter (what you would have hardcoded in the app). Use this static value initially.
4. **Remap When Ready**:
Once your app is shipped and the feature is ready, remap the parameter to a Feature Gate, Experiment, Dynamic Config, or Layer. This allows you to test and target different variants.
5. **Update in Real-Time**:
After experimenting, you can update the static value or gate the feature for specific app versions. This can be done in real time across mobile apps that are already released.
## Why Use Parameter Stores?
If you’ve encountered this problem before, you’ll immediately recognize the power of Parameter Stores. For developers just starting with a Statsig SDK in their mobile apps, it’s beneficial to use Parameter Stores from the outset.
Parameter Stores are inspired by solutions like Facebook's Mobile Config, Uber's approach to experimentation, and Firebase Remote Config. These are used by leading mobile companies to:
* Move faster
* Maintain backward compatibility
* Experiment more freely
While the extra setup in the Statsig console may seem less convenient than creating a gate, it saves time later. Once your app version is shipped, Parameter Stores ensure that no Statsig entity values are hardcoded, giving you flexibility to update parameters without the need for a new release. This is particularly valuable for mobile apps, where app store release cycles create delays—unlike backends or websites, which can be updated quickly.
## Supported SDK Versions
Parameter Stores are available in the following SDKs:
* **Android SDK** v4.33.0+
* **iOS SDK** v1.45.0+
* **@statsig/js-client**, **@statsig/react-bindings**, **@statsig/react-native-bindings**, **@statsig/expo-bindings** v1.4.0+
* **Dart SDK** v1.2.1+
* **Statsig Server Core SDKs** are gradually adding support, available in:
* **com.statsig:javacore** 0.1.0+
* **statsig-rust** 0.1.0+
* **@statsig/statsig-node-core** 0.1.0+
* **statsig-python-core** 0.5.0+
* **statsig-dotnet-core** 0.6.1+
Parameter Stores will *Not* be available in non server-core server SDKs, nor available when Bootstrapping a client SDK from one of those SDKs. Need support in a language soon? Let us know in [Slack](https://statsig.com/slack).
***
# Client Persistent Assignment
Source: https://docs.statsig.com/client/concepts/persistent_assignment
Configure persistent assignment in Statsig client SDKs so users stay in the same experiment group across sessions and devices for consistent experiences.
Persistent assignment allows you to ensure that a user's variant stays consistent while an experiment is running, regardless of changes to allocation or targeting.
## Persistent Storage
Persistent storage takes an "adapter" approach, allowing you to plug in a storage solution of your choice to store assignments, which can then be referenced later to ensure a user stays in the same bucket. You can implement an adapter that uses Local Storage, or one that uses remote storage, to enable persistence across multiple devices.
The user persistent storage interface consists of just a `load`/`loadAsync`, `save`, `delete` API for read/write operations.
Persistent Storage is currently supported on:
* The modern [`Javascript,`](/client/javascript-sdk) [`React`](/client/React), and [`React Native`](/client/ReactNative) SDKs, including on-device evaluation
* [`Android, on-device evaluation`](/client/androidOnDeviceEvaluationSDK) only
* [`iOS, on-device evaluation`](/client/swiftOnDeviceEvaluationSDK) only
* See [below](#support-in-ios-and-android-sdks) for more information on Android and iOS Support
### Persistent Storage Logic
* Providing a storage adapter on Statsig initialization will give the SDK access to read & write on your custom storage
* Providing user persisted values to `get_experiment` will inform the SDK to
* **save** the evaluation of the current user **on first evaluation**
* **load** the previously saved evaluation of a persisted user **on subsequent evaluations**
* **delete** the previously saved evaluation of a persisted user if the experiment is no longer active
* Not providing user persisted values to `get_experiment` will **delete** a previously saved evaluation
### Example usage
```typescript theme={null}
import { StatsigClient } from '@statsig/js-client';
import { UserPersistentOverrideAdapter } from '@statsig/js-user-persisted-storage';
// Custom storage implementation using localStorage
class LocalStorageUserPersistedStorage {
load(key) {
return JSON.parse(localStorage.getItem(key) ?? '{}');
}
save(key, experiment, data) {
const values = JSON.parse(localStorage.getItem(key) ?? '{}');
values[experiment] = JSON.parse(data);
localStorage.setItem(key, JSON.stringify(values));
}
delete(key, experiment) {
const data = JSON.parse(localStorage.getItem(key) ?? '{}');
delete data[experiment];
localStorage.setItem(key, JSON.stringify(data));
}
}
const storage = new LocalStorageUserPersistedStorage();
const adapter = new UserPersistentOverrideAdapter(storage);
const client = new StatsigClient('client-key', { overrideAdapter: adapter });
await client.initializeAsync({ userID: "123" });
const user = { userID: "123" };
const userPersistedValues = adapter.loadUserPersistedValues(user, 'userID');
const experiment = client.getExperiment('active_experiment', { userPersistedValues });
console.log(experiment.getGroupName()); // 'Control'
// Switch to different user - will maintain same experiment group due to persistence
const newUser = { userID: "456" };
const newExperiment = client.getExperiment('active_experiment', { userPersistedValues });
console.log(newExperiment.getGroupName()); // Still 'Control'
```
The Syntax for react matches vanilla Javascript - for a full implementation example, you can refer to our [Persistent Storage Example](https://github.com/statsig-io/js-client-monorepo/tree/main/samples/next-js/src/app/persisted-user-storage-example) in Next.js.
#### Synchronous Persistent Evaluations
The `UserPersistentStorageInterface` exposes two methods for synchronous persistent storage, which will be called by default when evaluating an experiment.
```
interface UserPersistentStorageInterface {
suspend fun load(key: String): PersistedValues
fun save(key: String, experimentName: String, data: String)
fun delete(key: String, experiment: String)
...
}
```
The `key` string is a combination of ID and ID Type: e.g. "123:userID" or "abc:stableID" which the SDK will construct and call `get` and `set` on by default
You can use this interface to persist evaluations synchronously to local storage. If you need an async interface, read on.
#### Asynchronous Persistent Evaluations
The `UserPersistentStorageInterface` exposes two methods for asynchronous persistent evaluations. Because the `getExperiment` call is synchronous, you must load the value first, and pass it in as `userPersistedValues`
```kotlin theme={null}
interface UserPersistentStorageInterface {
fun loadAsync(key: String, callback: IPersistentStorageCallback)
fun save(key: String, experimentName: String, data: String)
fun delete(key: String, experiment: String)
...
}
interface IPersistentStorageCallback {
fun onLoaded(values: PersistedValues)
}
```
For your convenience, we've created a top level method to load the value for a given user and ID Type:
```kotlin theme={null}
// Asynchronous load values
val userPersistedValues = Statsig.client.loadUserPersistedValuesAsync(
user: StatsigUser,
idType: string, // userID, stableID, customIDxyz, etc
callback: IPersistentStorageCallback
);
// Synchronous load values
val userPersistedvalues = Statsig.client.loadUserPersistedValues(
user: StatsigUser,
idType: string, // userID, stableID, customIDxyz, etc
)
```
Putting it all together, assuming you have implemented the `UserPersistentStorageInterface` and set it on `StatsigOptions`, your call site will look like this:
```kotlin theme={null}
// Asynchronous
val callback = object: IPersistentStorageCallback {
@override
fun onLoaded(values: PersistedValues) {
Statsig.getExperiment(user, "sample_experiment", GetExperimentOptions(userPersistedValues = values))
}
}
val userValues = Statsig.client.loadUserPersistedValuesAsync(user, "userID", callback)
// Synchronous
val user = StatsigUser(userID = "user123")
val userValues = Statsig.client.loadUserPersistedValues(user, 'userID');
const experiment = statsig.getExperiment({userID: "123"}, 'the_allocated_experiment', { userPersistedValues: userValues });
```
If you are using java, you can only override loadAsync function and ignore load function as empty.
```typescript theme={null}
const storage = new CustomStorageAdapter(); // Need to implement
const adapter = new UserPersistentOverrideAdapter(storage);
const client = new StatsigOnDeviceEvalClient(
'client-key',
{ overrideAdapter: adapter }
);
await client.initializeAsync();
const userInControl = { userID: "123" }
const userInUnknown = { userID: "unknown" }
const userPersistedValues = adapter.loadUserPersistedValues(user, 'userID');
let experiment = client.getExperiment('active_experiment', user, { userPersistedValues });
console.log(experiment.getGroupName()) // 'Control'
experiment = client.getExperiment('active_experiment', userInUnknown, { userPersistedValues });
console.log(experiment.getGroupName()) // 'Control'
```
For a full implementation example, you can refer to our [Persistent Storage On-Device Eval Example](https://github.com/statsig-io/js-client-monorepo/tree/main/samples/next-js/src/app/persisted-user-storage-example-on-device) in Next.js.
```typescript theme={null}
await statsig.initialize(
'client-key',
{ userPersistentStorage: new CustomStorageAdapter() } // Need to implement
);
const userInControl = { userID: "123" }
const userInUnknown = { userID: "unknown" }
const userPersistedValues = await statsig.loadUserPersistedValuesAsync(userInControl, 'userID');
let experiment = statsig.getExperiment(userInControl, 'active_experiment', { userPersistedValues });
console.log(experiment.getGroupName()) // 'Control'
experiment = statsig.getExperiment(userInUnknown, 'active_experiment', { userPersistedValues });
console.log(experiment.getGroupName()) // 'Control'
```
## Support in iOS and Android SDKs
Android and iOS SDKs offer a simplified version of Persistent Storage called `keepDeviceValues` that relies on on-device storage. While this is less flexible it's simple to leverage - with a simple boolean flag. When enabled, the SDK (under the hood in the getExperiment/getLayer call) will check for previous stored value, and use those instead, even if allocation or targeting has changed. When the experiment ends - the SDK will stop persisting values.
#### Swift:
```swift theme={null}
// With an Experiment:
let titleExperiment = Statsig.getExperiment("new_user_promo_title", true) // <-- "true" flag sets keep device values
// Use the experiment like normal:
let promoTitle = titleExperiment.getValue(forKey: "title", defaultValue: "Welcome to Statsig!")
// Or a Layer:
let layer = Statsig.getLayer("user_promo_experiments", true) // <-- "true" flag sets keep device values
// Use the layer like normal:
let promoTitle = layer.getValue(forKey: "title", defaultValue: "Welcome to Statsig!")
```
#### Objective C:
```objc theme={null}
// With an Experiment:
DynamicConfig *expConfig = [Statsig getExperimentForName:@"new_user_promo_title" true]; // <-- "true" flag sets keep device values
// Use the experiment like normal:
NSString *promoTitle = [expConfig getStringForKey:@"title" defaultValue:@"Welcome to Statsig! Use discount code WELCOME10OFF for 10% off your first purchase!"];
double discount = [expConfig getDoubleForKey:@"discount" defaultValue:0.1];
double price = msrp * (1 - discount);
```
#### Java:
```Java theme={null}
// With an Experiment:
DynamicConfig titleExperiment = Statsig.getExperiment("new_user_promo_title", true); // <-- "true" flag sets keep device values
// Use the experiment like normal:
String promoTitle = titleExperiment.getString("title", "Welcome to Statsig!");
// Or a Layer:
Layer layer = Statsig.getLayer("user_promo_experiments", true) // <-- "true" flag sets keep device values
// Use the layer like normal:
String promoTitle = layer.getString("title", "Welcome to Statsig!");
```
#### Kotlin:
```kotlin theme={null}
// With an Experiment:
val titleExperiment = Statsig.getExperiment("new_user_promo_title", true) // <-- "true" flag sets keep device values
// Use the experiment like normal:
val promoTitle = titleExperiment.getString("title", "Welcome to Statsig!")
// Or a Layer:
val layer = Statsig.getLayer("user_promo_experiments", true) // <-- "true" flag sets keep device values
// Use the layer like normal:
val promoTitle = layer.getString("title", "Welcome to Statsig!")
```
# HTML Snippet
Source: https://docs.statsig.com/client/html-snippet
Add Statsig to any website with a single HTML script tag to evaluate feature flags, run A/B tests, and capture analytics events without a build step.
## Set Up the SDK
You can install the Statsig SDK by putting a script tag in the head of your HTML file:
```js theme={null}
```
Note that you need to replace `YOUR_CLIENT_API_KEY` with your actual client API key from the [Project Settings > API Keys](https://console.statsig.com/api_keys).
The HTML snippet we provide wraps an instance of the statsig javascript sdk. Simply providing your client API key in the url is enough to auto initialize the SDK, as the installation step recommends.
However, you should likely move to a manual initialization if you need any of the following:
* custom user properties
* custom initialization options
* check gates, configs, experiments, or log events
To manually initialize an instance of the sdk, remove the key parameter from the script tag, and do the following:
```js theme={null}
const { StatsigClient, runStatsigAutoCapture, runStatsigSessionReplay } = window.Statsig;
const client = new StatsigClient(
'',
{ userID: 'a-user' }
);
runStatsigSessionReplay(client);
runStatsigAutoCapture(client);
await client.initializeAsync();
// check gates, configs, experiments, or log events
```
The `StatsigClient` instance you create is also available via `window.Statsig`, so you can reference it globally.
At this point, you have access to all of the methods available in the [Javascript SDK](/client/javascript-sdk) via your instance of the `StatsigClient`. Refer to that documentation for initialization details and core methods.
#### I want to customize the initialization logic, can I do that?
Yes, you can remove the client API key from the url and see the [Javascript SDK Getting Started Guide](/client/javascript-sdk#getting-started) for more information.
The HTML snippet is just our javascript SDK - providing an api key in the url will auto initialize an instance for you, but if you don't want that, you can use it just like the javascript SDK.
You will need to create your own instance differently than if you were installing the SDK via npm:
```js theme={null}
const { StatsigClient, runStatsigAutoCapture, runStatsigSessionReplay } = window.Statsig;
const client = new StatsigClient(
'',
{ userID: 'a-user' }
);
runStatsigSessionReplay(client);
runStatsigAutoCapture(client);
await client.initializeAsync();
// check gates, configs, experiments, or log events
```
# iOS/tvOS/macOS Client SDK
Source: https://docs.statsig.com/client/iosClientSDK
Use the Statsig iOS SDK in Swift and Objective-C apps to evaluate feature flags, run experiments, and log analytics events on iOS, tvOS, and macOS.
## Setup the SDK
To use the SDK in your project, you must add Statsig as a dependency.
In your Xcode, select File > Swift Packages > Add Package Dependency
and enter the URL [https://github.com/statsig-io/statsig-kit.git](https://github.com/statsig-io/statsig-kit.git).
You can also include it directly in your project's Package.swift. Find out the latest release version on our [GitHub page](https://github.com/statsig-io/statsig-kit/releases).
```swift theme={null}
//...
dependencies: [
// see the latest version on https://github.com/statsig-io/statsig-kit/releases
.package(url: "https://github.com/statsig-io/statsig-kit.git", .upToNextMinor("X.Y.Z")),
],
//...
targets: [
.target(
name: "YOUR_TARGET",
dependencies: ["Statsig"]
)
],
//...
```
If you are using CocoaPods, our pod name is 'Statsig', and you can include the following line to your Podfile:
```ruby theme={null}
use_frameworks!
target 'TargetName' do
//...
pod 'Statsig', '~> X.Y.Z'
end
```
Find the latest versions by searching [cocoapods.org](https://cocoapods.org/) or on [Github](https://github.com/statsig-io/statsig-kit/releases).
Next, 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 on in a gate or experiment.
```swift Swift theme={null}
Statsig.initialize(
sdkKey: "my_client_sdk_key",
user: StatsigUser(userID: "my_user_id"),
options: StatsigOptions(environment: StatsigEnvironment(tier: .Staging)))
{ error in
// Statsig has finished fetching the latest feature gate and experiment values for your user.
// If you need the most recent values, you can get them now.
// You can also check error.message and error.code for any debugging information.
}
```
```objective-c Objective C theme={null}
StatsigUser *user = [[StatsigUser alloc] initWithUserID:@"my_user_id"];
[Statsig initializeWithSDKKey:@"my_client_sdk_key" user:user completion:^(StatsigClientError * error) {
// Statsig has finished fetching the latest feature gate and experiment values for your user.
// If you need the most recent values, you can get them now.
// You can also check error.message and error.code for any debugging information.
}];
```
The completion block is called after the network request to fetch the latest feature gate and experiment values for your user.
If you try to get any value before the completion block is called, you could get either the cached value from the previous session,
or the default value. If you need the latest value, please wait for the completion block to be called first.
## Use the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's check a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
```swift Swift theme={null}
if Statsig.checkGate("new_homepage_design") {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
```
```objective-c Objective C theme={null}
if ([Statsig checkGateForName:@"new_homepage_design"]) {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, **Dynamic Configs** can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```swift Swift theme={null}
let config = Statsig.getConfig("awesome_product_details")
// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
let itemName = config.getValue(forKey: "product_name", defaultValue: "Awesome Product v1")
let price = config.getValue(forKey: "price", defaultValue: 10.0)
let shouldDiscount = config.getValue(forKey: "discount", defaultValue: false)
```
```objective-c Objective C theme={null}
DynamicConfig *config = [Statsig getConfigForName:@"awesome_product_details"];
// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
NSString *itemName = [config.getStringForKey:@"product_name" defaultValue:@"Awesome Product v1"];
double price = [config getDoubleForKey:@"price" defaultValue:10.0];
BOOL shouldDiscount = [config getBoolForKey:@"discount" defaultValue:false];
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```swift Swift theme={null}
// Values via getLayer
let layer = Statsig.getLayer("user_promo_experiments")
let promoTitle = layer.getValue(forKey: "title", defaultValue: "Welcome to Statsig!")
let discount = layer.getValue(forKey: "discount", defaultValue: 0.1)
// or, via getExperiment
let titleExperiment = Statsig.getExperiment("new_user_promo_title")
let priceExperiment = Statsig.getExperiment("new_user_promo_price")
let promoTitle = titleExperiment.getValue(forKey: "title", defaultValue: "Welcome to Statsig")
let discount = priceExperiment.getValue(forKey: "discount", defaultValue: 0.1)
...
let price = msrp * (1 - discount);
```
```objective-c Objective C theme={null}
DynamicConfig *expConfig = [Statsig getExperimentForName:@"new_user_promo"];
NSString *promoTitle = [expConfig.getStringForKey:@"title" defaultValue:@"Welcome to Statsig! Use discount code WELCOME10OFF for 10% off your first purchase!"];
double discount = [expConfig getDoubleForKey:@"discount" defaultValue:0.1];
double price = msrp * (1 - discount);
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:
```swift Swift theme={null}
Statsig.logEvent(withName: "purchase", value: 2.99, metadata: ["item_name": "remove_ads"])
```
```objective-c Objective C theme={null}
[Statsig logEvent:@"purchase" doubleValue:2.99 metadata:@{ @"item_name" : @"remove_ads" }];
```
## Parameter Stores
Parameter Stores hold a set of parameters for your mobile app. These parameters can be remapped on-the-fly from a static value to a Statsig entity (Feature Gates, Experiments, and Layers), so you can decouple your code from the configuration in Statsig. Read more about Param Stores [here](/client/concepts/parameter-stores).
## 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](/guides/first-device-level-experiment) 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 `updateUserWithResult`
with the updated `userID` and/or any other updated user attributes:
```swift Swift theme={null}
let user = StatsigUser(
userID: "a-user-id",
email: "user@example.com",
ip: "192.168.1.1",
userAgent: "Mozilla/5.0",
country: "US",
locale: "en_US",
appVersion: "1.0.0",
custom: [
"plan": "premium",
"age": 25
],
customIDs: [
"stableID": "stable-id-123"
],
privateAttributes: [
"email": "private@example.com"
]
)
```
```objective-c Objective C theme={null}
StatsigUser *user = [[StatsigUser alloc] initWithUserID:@"a-user-id"];
user.email = @"user@example.com";
user.ip = @"192.168.1.1";
user.userAgent = @"Mozilla/5.0";
user.country = @"US";
user.locale = @"en_US";
user.appVersion = @"1.0.0";
user.custom = @{ @"plan": @"premium", @"age": @25 };
user.customIDs = @{ @"stableID": @"stable-id-123" };
user.privateAttributes = @{ @"email": @"private@example.com" };
```
## Statsig Options
Used to decide how long the Statsig client waits for the initial network request to respond before calling the completion block. The Statsig client will return either cached values (if any) or default values if checkGate/getConfig/getExperiment is called before the initial network request completes.
If you always want to wait for the latest values fetched from Statsig server, you should set this to 0 so we do not timeout the network request.
By default, any custom event your application logs with `Statsig.logEvent()` includes the current root View Controller. This is so we can generate user journey funnels for your users. You can set this parameter to true to disable this behavior.
A handler for log messages from the SDK. If not provided, logs will be printed to the console.
The handler receives the message string that would otherwise be printed to the console.
Useful for redirecting logs to your own logging system, suppressing unnecessary console output, or debugging issues with the SDK.
StatsigEnvironment is a class for you to set environment variables that apply to all of your users in the same session and will be used for targeting purposes.
e.g. passing in a value of `StatsigEnvironment(tier: .Staging)` will allow your users to pass any condition that pass for the staging environment tier, and fail any condition that only passes for other environment tiers.
EvaluationCallback provides a callback when an evaluation is made against one of your configurations (gate, dynamic config, experiment, layer and parameter stores). This is useful when you want to trigger specific actions or log evaluations based on the results received from Statsig.
To use the EvaluationCallback, you need to provide a callback function during the SDK initialization via the StatsigOptions. The callback is invoked every time an evaluation occurs for feature gates, dynamic configs, experiments, layers, or parameter stores.
The EvaluationCallbackData enum defines the different types of data that can be returned in the evaluationCallback when the Statsig iOS SDK evaluates feature gates, dynamic configs, experiments, layers, or parameter stores.
Here is the structure of the enum:
```swift theme={null}
public enum EvaluationCallbackData {
case gate (FeatureGate)
case config (DynamicConfig)
case experiment (DynamicConfig)
case layer (Layer)
case parameterStore (ParameterStore)
}
```
Here's an example of how to set up an evaluation callback:
```swift theme={null}
func callback(data: StatsigOptions.EvaluationCallbackData) {
switch data {
case .gate(let gate):
// Handle gate evaluation
case .config(let config):
// Handle dynamic config evaluation
case .experiment(let experiment):
// Handle experiment evaluation
case .layer(let layer):
// Handle layer evaluation
case .parameterStore(let paramStore):
// Handle parameter store evaluation
}
}
let opts = StatsigOptions(evaluationCallback: callback)
Statsig.initialize(sdkKey: "client-key", options: opts)
```
Allows users to implement their own caching strategy by passing an object that conforms to the `StorageProvider` protocol.
Default cache key: `com.statsig.cache`
```swift theme={null}
@objc public protocol StorageProvider {
@objc func read(_ key: String) -> Data?
@objc func write(_ value: Data, _ key: String)
@objc func remove(_ key: String)
}
```
Overrides the auto generated StableID that is set for the device.
Use file caching instead of UserDefaults. Useful if you are running into size limits with UserDefaults (ie tvOS).
Controls whether the SDK sends events over the network. Useful when user consent is needed before sending events. The iOS SDK stores up to 1MB of unsent request payloads
Provide a Dictionary representing the "initialize response" required to synchronously initialize the SDK.
This value can be obtained from a Statsig server SDK and used to [Bootstrap](/client/concepts/initialize/#2-bootstrap-initialization) the SDK when initializing.
Prevent the SDK from sending useful debug information to Statsig.
When disabled, the SDK will not hash gate/config/experiment names, instead they will be readable as plain text.
This requires special authorization from Statsig. Reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
The SDK automatically shuts down when an app is put into the background.
If you need to use the SDK while your app is in the background, set this to false.
Override the URL used to initialize the SDK. Learn more at [https://docs.statsig.com/custom\_proxy](https://docs.statsig.com/custom_proxy)
```swift theme={null}
StatsigOptions(initializationURL: URL(string: "https://example.com/setup"))
```
Override the URL used to log events. Learn more at [https://docs.statsig.com/custom\_proxy](https://docs.statsig.com/custom_proxy)
```swift theme={null}
StatsigOptions(eventLoggingURL: URL(string: "https://example.com/info"))
```
## StableID
Each client SDK has the notion of stableID, a devive-level identifier that is generated the first time the SDK is initialized and is stored locally for all future sessions. Unless storage is wiped (or app deleted), the stableID will not change.
This allows us to run device level experiments and experiments when other user identifiable information is unavailable (Logged out users).
```swift Swift theme={null}
let options = StatsigOptions(overrideStableID: "my_stable_id")
Statsig.initialize(sdkKey: "client-xyz", options: options)
```
```objective-c Objective C theme={null}
StatsigOptions *options = [[StatsigOptions alloc] init];
options.overrideStableID = @"my_stable_id";
[Statsig initializeWithSDKKey:@"client-xyz" user:nil options:options completion:nil];
```
## 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:
```swift Swift theme={null}
// Swift - Check without logging exposure
let result = Statsig.checkGateWithExposureLoggingDisabled("a_gate_name")
// ...
// Later, when ready to log the exposure
Statsig.manuallyLogGateExposure("a_gate_name")
```
```objc Objective-C theme={null}
// Objective C - Check without logging exposure
bool result = [Statsig checkGateWithExposureLoggingDisabled:@"a_gate_name"];
// ...
// Later, when ready to log the exposure
[Statsig manuallyLogGateExposure:@"a_gate_name"];
```
```swift Swift theme={null}
// Swift - Get config without logging exposure
let config = Statsig.getConfigWithExposureLoggingDisabled("a_config_name")
// ...
// Later, when ready to log the exposure
Statsig.manuallyLogConfigExposure("a_config_name")
```
```objc Objective-C theme={null}
// Objective C - Get config without logging exposure
DynamicConfig *config = [Statsig getConfigWithExposureLoggingDisabled:@"a_config_name"];
// ...
// Later, when ready to log the exposure
[Statsig manuallyLogConfigExposure:@"a_config_name"];
```
```swift Swift theme={null}
// Swift - Get experiment without logging exposure
let experiment = Statsig.getExperimentWithExposureLoggingDisabled("an_experiment_name")
// ...
// Later, when ready to log the exposure
Statsig.manuallyLogExperimentExposure("an_experiment_name")
```
```objc Objective-C theme={null}
// Objective C - Get experiment without logging exposure
DynamicConfig *experiment = [Statsig getExperimentWithExposureLoggingDisabled:@"an_experiment_name"];
// ...
// Later, when ready to log the exposure
[Statsig manuallyLogExperimentExposure:@"an_experiment_name"];
```
```swift Swift theme={null}
// Swift - Get layer without logging exposure
let layer = Statsig.getLayerWithExposureLoggingDisabled("a_layer_name")
let result = layer.getValue(forKey: "a_parameter_name", defaultValue: "fallback")
// ...
// Later, when ready to log the exposure
Statsig.manuallyLogLayerParameterExposure("a_layer_name", "a_parameter_name")
```
```objc Objective-C theme={null}
// Objective C - Get layer without logging exposure
Layer *layer = [Statsig getLayerWithExposureLoggingDisabled:@"a_layer_name"];
NSString *result = [layer getStringForKey:@"a_parameter_name" defaultValue:@"fallback"];
// ...
// Later, when ready to log the exposure
[Statsig manuallyLogLayerParameterExposure:@"a_layer_name" parameterName:@"a_parameter_name"];
```
## Local Overrides
If you want to locally override gates/configs/experiments/layers for testing, Statsig offers convenient methods for a quick local override. Unless you call the remove method, these will be persisted session-to-session on the client's device. Note that these overrides only apply locally - they don't impact definitions in the console or elsewhere.
## 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:
```swift Swift theme={null}
Statsig.shutdown()
```
```objective-c Objective C theme={null}
[Statsig shutdown];
```
## Using multiple instances of the SDK
Up to this point, we've used the SDK's singleton. We also support creating multiples instances of the SDK - the `Statsig` singleton wraps a single instance of the SDK (typically called a `StatsigClient`) that you can instantiate.
You must use a different SDK key for each sdk instance you create for this to work. Various functionality of the Statsig client is keyed on the SDK key being used. Using the same key will lead to collisions.
All top level static methods from the singleton carry over as instance methods. To create an instance of the Statsig sdk:
```swift Swift theme={null}
let client = StatsigClient(
sdkKey: "client-xyz",
user: StatsigUser(userID: "user-1"),
options: StatsigOptions(environment: StatsigEnvironment(tier: .Production))
) { error in
// ready
}
let gateOn = client.checkGate("some_gate")
```
```objective-c Objective C theme={null}
StatsigOptions *options = [[StatsigOptions alloc] initWithEnvironment:[[StatsigEnvironment alloc] initWithTier:StatsigEnvironmentTierProduction]];
StatsigUser *user = [[StatsigUser alloc] initWithUserID:@"user-1"];
StatsigClient *client = [[StatsigClient alloc] initWithSdkKey:@"client-xyz" user:user options:options completion:^(StatsigClientError * error) {
// ready
}];
BOOL gateOn = [client checkGate:@"some_gate"];
```
Use a unique SDK key per instance to avoid collisions.
## Initialize Response
The SDK provides a method to access the raw values that are used internally for gate, config, and layer value. This can be useful for debugging or for advanced use cases where you need to access the underlying data. For example, you can use these values to bootstrap another SDK, like the javascript SDK when you open an in-app browser.
The `getInitializeResponseJson` method returns an `ExternalInitializeResponse` object that contains:
1. A JSON string representation of the initialize response values
2. Evaluation details that provide metadata about how the values were obtained (network, cache, etc.)
```swift Swift theme={null}
let response = Statsig.getInitializeResponseJson()
if let values = response.values {
print(values)
}
let details = response.evaluationDetails
```
```objective-c Objective C theme={null}
ExternalInitializeResponse *response = [Statsig getInitializeResponseJson];
NSString *values = response.values;
if (values) {
NSLog(@"%@", values);
}
EvaluationDetails *details = response.evaluationDetails;
```
## Listening for changes
In v1.14.0+, you can listen for SDK changes using `StatsigListening`.
```swift Swift theme={null}
class MyViewController: UIViewController, StatsigListening {
override func viewDidLoad() {
super.viewDidLoad()
if Statsig.isInitialized() {
render()
} else {
Statsig.addListener(self)
renderLoading()
}
}
private func render() {
let showNewUI = Statsig.checkGate("new_ui_enabled")
if showNewUI {
// Render the new UI
} else {
// Render the old UI
}
}
private func renderLoading() { /* loading UI */ }
private func renderError(error: StatsigClientError) { /* error UI */ }
// StatsigListening
func onInitializedWithResult(_ error: StatsigClientError?) {
if let error = error {
renderError(error)
return
}
render()
}
func onUserUpdatedWithResult(_ error: StatsigClientError?) { /* optional rerender */ }
}
```
# JavaScript Client SDK (Web)
Source: https://docs.statsig.com/client/javascript-sdk
Use the Statsig JavaScript client SDK in browser and React applications to evaluate feature gates, run experiments, and capture analytics events.
Source code: statsig-io/js-client-monorepo
## Set Up the SDK
To install the Statsig Web SDK, add the package via your preferred package manager. Include optional packages if you plan to enable Session Replay or Auto Capture.
```bash theme={null}
npm install @statsig/js-client @statsig/session-replay @statsig/web-analytics
```
```bash theme={null}
yarn add @statsig/js-client @statsig/session-replay @statsig/web-analytics
```
If you don't need Session Replay or Auto Capture, omit the `@statsig/session-replay` and `@statsig/web-analytics` packages.
After installation, configure the SDK in your app entry point before rendering your UI.
Next, 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 on in a gate or experiment.
```tsx theme={null}
import { StatsigClient } from '@statsig/js-client';
const client = new StatsigClient(
'client-xyz',
{ userID: 'a-user' },
{
environment: { tier: 'development' },
},
);
await client.initializeAsync();
```
Use `initializeAsync` when you need to await the latest values. For a non-blocking approach, you can call `initializeAsync()` without awaiting and rely on cached values until the promise resolves.
## Use the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's check a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
```tsx theme={null}
if (client.checkGate('new_homepage_design')) {
// Gate is on, show new experience
} else {
// Gate is off, render the default experience
}
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, **Dynamic Configs** can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```tsx theme={null}
const config = client.getDynamicConfig('awesome_product_details');
const itemName = config.get('product_name', 'Some Fallback');
const price = config.value.price ?? 10.0;
if (config.value.is_discount_enabled === true) {
// apply discount logic
}
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```tsx theme={null}
// Reading values via getLayer
const layer = client.getLayer('user_promo_experiments');
const promoTitle = layer.get('title', 'Welcome to Statsig!');
const discount = layer.get('discount', 0.1);
```
```tsx theme={null}
// Reading values via getExperiment
const titleExperiment = client.getExperiment('new_user_promo_title');
const priceExperiment = client.getExperiment('new_user_promo_price');
const experimentTitle = titleExperiment.value.title ?? 'Welcome to Statsig!';
const experimentDiscount = priceExperiment.value.discount ?? 0.1;
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:
```tsx theme={null}
client.logEvent('my_simple_event');
client.logEvent({
eventName: 'add_to_cart',
value: 'SKU_12345',
metadata: {
price: '9.99',
item_name: 'diet_coke_48_pack',
},
});
```
### Flushing Logged Events
`flush()` sends queued events immediately. Use `shutdown()` when your app is exiting.
```tsx theme={null}
await client.flush();
```
### Typed Getters
`Layer`, `Experiment`, and `DynamicConfig` objects support a typed `get` method. Using a fallback that matches the expected type helps avoid returning unintended values.
```tsx theme={null}
// config value: { "my_value": 1 }
const dynamicConfig = client.getDynamicConfig('a_config');
const fallbackString = dynamicConfig.get('my_value', 'fallback'); // returns 'fallback'
const fallbackNumber = dynamicConfig.get('my_value', 0); // returns 1
const rawValue = dynamicConfig.get('my_value'); // returns 1
```
Passing a fallback of the wrong type returns that fallback. When type safety is not needed, omit the fallback to receive the raw value.
### Evaluation Details
Each gate, config, experiment, and layer exposes `details` describing how the value was resolved.
* `reason` explains the source (e.g., `Network:Recognized`, `Cache:Unrecognized`).
* `lcut` is the last time any configuration changed in your project.
* `receivedAt` marks when this response was received, useful for judging cache staleness.
```tsx theme={null}
const gate = client.getFeatureGate('a_gate');
console.log(gate.details);
// { reason: 'Cache:Recognized', lcut: 1713837126636, receivedAt: 1713838137598 }
const config = client.getDynamicConfig('a_config');
console.log(config.details);
// { reason: 'Cache:Unrecognized', lcut: 1713837126636, receivedAt: 1713838137598 }
```
See [`/sdk/debugging`](/sdk/debugging) for the full list of `reason` values.
### Sample Projects
Explore end-to-end examples in the [`js-client-monorepo` samples folder](https://github.com/statsig-io/js-client-monorepo/tree/main/samples) for React, Next.js, precomputed clients, and more.
## Parameter Stores
Parameter Stores hold a set of parameters for your mobile app. These parameters can be remapped on-the-fly from a static value to a Statsig entity (Feature Gates, Experiments, and Layers), so you can decouple your code from the configuration in Statsig. Read more about Param Stores [here](/client/concepts/parameter-stores).
```tsx theme={null}
const homepageStore = client.getParameterStore('homepage');
const title = homepageStore.get('title', 'Welcome');
const showUpsell = homepageStore.get('upsell_upgrade_now', false);
```
## 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](/guides/first-device-level-experiment) 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:
### Updating Users
Call `updateUserAsync` when the signed-in user changes to fetch fresh values for that identity.
```tsx theme={null}
const user = { userID: 'a-user' };
await client.updateUserAsync(user);
```
For advanced flows—such as bootstrapping or prefetching users—see [Using EvaluationsDataAdapter](/client/javascript/using-evaluations-data-adapter).
### Prefetching Users
Use `prefetchData` to prepare values for another user so you can switch synchronously later.
```tsx theme={null}
const nextUser = { userID: 'my-other-user' };
await client.dataAdapter.prefetchData(nextUser);
// Optionally handle failures without blocking the UI
client.dataAdapter.prefetchData(nextUser).catch((err) => {
console.warn('Failed to prefetch', err);
});
client.updateUserSync(nextUser);
const gate = client.getFeatureGate('a_gate');
console.log(gate.value, gate.details.reason); // true, 'Prefetch:Recognized'
```
## Statsig Options
Controls logging behavior.
* `browser-only` (default): log events from browser environments.
* `disabled`: never send events.
* `always`: log in every environment, including non-browser contexts.
Use `loggingEnabled: 'disabled'` instead.
Skip generating a device-level Stable ID.
Recompute every evaluation instead of using the memoized result.
Override the generated session ID.
Persist Stable ID in cookies for cross-domain tracking.
Prevent any local storage writes (disables caching).
Override network endpoints per request type.
Base URL for all requests. The SDK appends endpoint paths like `/initialize` and `/rgstr`; append `/v1` when your proxy expects it.
Endpoint for initialization requests only. Takes precedence over `api` for `/initialize`.
Fallback endpoints for initialization requests only. This does not create a generic fallback for `api`.
Endpoint for event uploads.
Fallback endpoints for event uploads only. This does not create a generic fallback for `api`.
Request timeout in milliseconds.
Disable all outbound requests; combine with `loggingEnabled: 'disabled'` to silence log warnings.
Provide custom transport (e.g., Axios).
Set environment-wide defaults (for example `{ tier: 'staging' }`).
Console verbosity.
Max events per log batch.
Interval between automatic flushes.
Modify evaluations before returning them.
Attach the current page URL to logged events.
Send requests without Statsig-specific encoding.
Control compression for batched events.
Use `logEventCompressionMode` instead.
Provide a custom data adapter to control caching/fetching.
Override cache key generation for stored evaluations.
## 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:
```tsx theme={null}
const result = client.checkGate('a_gate_name', { disableExposureLog: true });
// ...
client.checkGate('a_gate_name'); // later, when ready to log the exposure
```
```tsx theme={null}
const config = client.getConfig('a_dynamic_config_name', { disableExposureLog: true });
client.getConfig('a_dynamic_config_name');
```
```tsx theme={null}
const experiment = client.getExperiment('an_experiment_name', { disableExposureLog: true });
client.getExperiment('an_experiment_name');
```
```tsx theme={null}
const layer = client.getLayer('a_layer_name', { disableExposureLog: true });
const value = layer.get('param_name', 'fallback');
// When ready to log
const exposure = client.getLayer('a_layer_name');
exposure.get('param_name', 'fallback');
```
## Session Replay
Install `@statsig/session-replay` and register the plugin to record user sessions.
```tsx theme={null}
import { StatsigProvider } from '@statsig/react-bindings';
import { StatsigSessionReplayPlugin } from '@statsig/session-replay';
Loading...}
options={{ plugins: [new StatsigSessionReplayPlugin()] }}
>
;
```
## Web Analytics / Auto Capture
By including the [`@statsig/web-analytics`](https://www.npmjs.com/package/@statsig/web-analytics) package in your project, you can automatically capture common web events like clicks and page views.
For more information on filtering events, enabling console log capture, and other configuration options available in web analytics, see the [Web Analytics Configuration](/webanalytics/overview#event-filtering-and-console-configuration) documentation.
```tsx theme={null}
import { StatsigProvider } from '@statsig/react-bindings';
import { StatsigAutoCapturePlugin } from '@statsig/web-analytics';
Loading...}
options={{ plugins: [new StatsigAutoCapturePlugin()] }}
>
;
```
## Content Security Policy
Add Statsig endpoints to your CSP `connect-src` directive when running the web SDK.
```js theme={null}
const cspConfig = {
directives: {
'connect-src': [
'api.statsig.com',
'featuregates.org',
'statsigapi.net',
'events.statsigapi.net',
'api.statsigcdn.com',
'featureassets.org',
'assetsconfigcdn.org',
'prodregistryv2.org',
'cloudflare-dns.com',
'beyondwickedmapping.org',
],
},
};
```
Statsig occasionally updates its network domains. Verify the latest list in [Statsig Domains](/infrastructure/statsig_domains).
## 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:
```tsx theme={null}
await client.shutdown();
```
## StableID
Each client SDK has the notion of stableID, a devive-level identifier that is generated the first time the SDK is initialized and is stored locally for all future sessions. Unless storage is wiped (or app deleted), the stableID will not change.
This allows us to run device level experiments and experiments when other user identifiable information is unavailable (Logged out users).
## Stable ID
Stable ID provides a consistent device identifier. It lets you run [logged-out experiments](/guides/first-device-level-experiment) and target gates at the device level.
### How Stable ID Works
* On first initialization the SDK generates a Stable ID and stores it in `localStorage` under `statsig.stable_id.`.
* Subsequent sessions reuse the stored value. Each client SDK key has its own Stable ID entry.
* Local storage is scoped per domain, so cross-domain usage requires sharing the value manually (see below).
### Reading the Stable ID
```tsx theme={null}
const context = client.getContext();
console.log('Statsig StableID:', context.stableID);
```
```tsx theme={null}
import { useStatsigClient } from '@statsig/react-bindings';
function MyComponent() {
const { client } = useStatsigClient();
const context = client.getContext();
return {context.stableID}
;
}
```
### Overriding the Stable ID
Provide a custom Stable ID through `StatsigUser.customIDs.stableID` if you already manage a durable device identifier.
```tsx theme={null}
import { StatsigClient, StatsigUser } from '@statsig/js-client';
const userWithStableID: StatsigUser = {
customIDs: {
stableID: 'my-custom-stable-id',
},
};
const client = new StatsigClient('client-xyz', userWithStableID);
await client.updateUserAsync(userWithStableID);
```
```tsx theme={null}
import { StatsigProvider, useStatsigClient } from '@statsig/react-bindings';
function App() {
return (
Your App
);
}
function MyComponent() {
const { client } = useStatsigClient();
useEffect(() => {
client.updateUserAsync({
customIDs: { stableID: 'my-custom-stable-id' },
});
}, [client]);
}
```
When you override the Stable ID it is persisted to local storage, so subsequent sessions reuse your custom value.
### Sharing Stable ID Across Subdomains
Add this helper script before initializing the SDK and then copy the stored value onto your user object.
```html theme={null}
```
(Use this script at your discretion and test thoroughly.)
### Aligning Stable ID Between Client and Server
To share Stable ID with a backend Statsig SDK, send the value with requests and persist it server-side when missing. The server can bootstrap the client with the same Stable ID.
```tsx theme={null}
// Server: ensure Stable ID exists, then return initialize response for the client
const values = Statsig.getClientInitializeResponse(user, YOUR_CLIENT_KEY, {
hash: 'djb2',
});
// Client: apply the server-provided values and initialize synchronously
const { values, user: verifiedUser } = await fetch('/init-statsig-client', {
method: 'POST',
body: loadUserData(),
}).then((res) => res.json());
const myClient = new StatsigClient(YOUR_CLIENT_KEY, verifiedUser);
myClient.dataAdapter.setData(values);
myClient.initializeSync();
```
## Using multiple instances of the SDK
Up to this point, we've used the SDK's singleton. We also support creating multiples instances of the SDK - the `Statsig` singleton wraps a single instance of the SDK (typically called a `StatsigClient`) that you can instantiate.
You must use a different SDK key for each sdk instance you create for this to work. Various functionality of the Statsig client is keyed on the SDK key being used. Using the same key will lead to collisions.
All top level static methods from the singleton carry over as instance methods. To create an instance of the Statsig sdk:
```tsx theme={null}
import { StatsigClient } from '@statsig/js-client';
const mainClient = new StatsigClient('client-xyz', { userID: 'a-user' });
const secondaryClient = new StatsigClient('client-abc', { userID: 'another-user' });
await Promise.all([
mainClient.initializeAsync(),
secondaryClient.initializeAsync(),
]);
if (mainClient.checkGate('a_gate')) {
// ...
}
if (secondaryClient.checkGate('some_other_gate')) {
// ...
}
```
## Override Adapter
Use the `LocalOverrideAdapter` to define local overrides for gates, configs, experiments, or layers.
```tsx theme={null}
import { LocalOverrideAdapter } from '@statsig/js-local-overrides';
import { StatsigClient, LogLevel } from '@statsig/js-client';
const overrideAdapter = new LocalOverrideAdapter();
overrideAdapter.overrideGate('gate_a', false);
overrideAdapter.overrideGate('gate_b', true);
const client = new StatsigClient('client-xyz', { userID: 'a-user' }, {
logLevel: LogLevel.Debug,
overrideAdapter,
});
```
### Persisting Overrides
Pass your client SDK key to the adapter to persist overrides between sessions when using multi-instance setups.
```tsx theme={null}
const overrideAdapter = new LocalOverrideAdapter('client-xyz');
```
## Using Persistent Evaluations
Persist experiment assignments so users keep the same variant even if targeting rules change.
```tsx theme={null}
import { StatsigClient } from '@statsig/js-client';
import { UserPersistentOverrideAdapter } from '@statsig/js-user-persisted-storage';
class LocalStorageUserPersistedStorage {
load(key: string) {
return JSON.parse(localStorage.getItem(key) ?? '{}');
}
save(key: string, experiment: string, data: string) {
const values = JSON.parse(localStorage.getItem(key) ?? '{}');
values[experiment] = JSON.parse(data);
localStorage.setItem(key, JSON.stringify(values));
}
delete(key: string, experiment: string) {
const data = JSON.parse(localStorage.getItem(key) ?? '{}');
delete data[experiment];
localStorage.setItem(key, JSON.stringify(data));
}
}
const storage = new LocalStorageUserPersistedStorage();
const adapter = new UserPersistentOverrideAdapter(storage);
const client = new StatsigClient('client-xyz', { overrideAdapter: adapter });
await client.initializeAsync({ userID: '123' });
const userPersistedValues = adapter.loadUserPersistedValues({ userID: '123' }, 'userID');
const experiment = client.getExperiment('active_experiment', { userPersistedValues });
```
See [Client Persistent Assignment](/client/concepts/persistent_assignment) for additional patterns and storage options.
## Common Targeting Use Cases
Capture cookies or URL parameters and pass them through `StatsigUser.custom` for targeting rules.
```tsx theme={null}
const user = {
custom: {
isLoggedIn: cookieLib.get('isLoggedIn'),
utm: new URL(window.location.href).searchParams.get('utm'),
},
};
const client = new StatsigClient('client-xyz', user, options);
```
Custom cache keys can produce stale or incorrect evaluations if multiple users map to the same key. Await `updateUserAsync` when you need guaranteed fresh values per user.
### Client Event Emitter
Subscribe to Statsig client lifecycle events to respond to initialization, logging, or evaluation changes.
```tsx theme={null}
import type {
AnyStatsigClientEvent,
StatsigClientEvent,
} from '@statsig/client-core';
const onAnyEvent = (event: AnyStatsigClientEvent) => {
console.log('Statsig event', event);
};
const onLogsFlushed = (event: StatsigClientEvent<'logs_flushed'>) => {
console.log('Logs', event.events);
};
client.on('logs_flushed', onLogsFlushed);
client.on('*', onAnyEvent);
client.off('logs_flushed', onLogsFlushed);
client.off('*', onAnyEvent);
```
| Event | Payload | Description |
| --------------------------- | -------------------- | ----------------------------------------------------- |
| `values_updated` | `{ status, values }` | Fired when initialize/update refreshes cached values. |
| `session_expired` | `{}` | Fired when the current session expires. |
| `error` | `{ error, tag }` | Unexpected client errors. |
| `pre_logs_flushed` | `{ events }` | Before a batch of events is sent. |
| `logs_flushed` | `{ events }` | After events are sent. |
| `pre_shutdown` | `{}` | Before the SDK shuts down. |
| `initialization_failure` | `{}` | Initialization failed. |
| `gate_evaluation` | `{ gate }` | When a gate is evaluated. |
| `dynamic_config_evaluation` | `{ dynamicConfig }` | When a config is evaluated. |
| `experiment_evaluation` | `{ experiment }` | When an experiment is evaluated. |
| `layer_evaluation` | `{ layer }` | When a layer is evaluated. |
| `log_event_called` | `{ event }` | When `logEvent` is called. |
## Quality & Troubleshooting
## Testing
Mock Statsig APIs in Jest to isolate business logic.
```tsx theme={null}
import { StatsigClient } from '@statsig/js-client';
export async function transform(input: string): Promise {
const client = new StatsigClient('client-xyz', { userID: 'a-user' }, {
networkConfig: {
preventAllNetworkTraffic:
typeof process !== 'undefined' && process.env['NODE_ENV'] === 'test',
},
});
await client.initializeAsync();
if (client.checkGate('a_gate')) {
input = 'transformed';
}
const experiment = client.getExperiment('an_experiment');
input += '-' + experiment.get('my_param', 'fallback');
await client.shutdown();
return input;
}
```
```tsx theme={null}
import { StatsigClient } from '@statsig/js-client';
jest.mock('@statsig/js-client');
test('string transformations', async () => {
jest
.spyOn(StatsigClient.prototype, 'checkGate')
.mockImplementation(() => true);
jest
.spyOn(StatsigClient.prototype, 'getExperiment')
.mockImplementation(() => ({ get: () => 'my-value' } as any));
const result = await transform('original');
expect(result).toBe('transformed-my-value');
});
```
## Debugging
When results look unexpected, use these tools to inspect what the SDK is doing.
### Enable Verbose Logging
```ts theme={null}
import { LogLevel, StatsigClient } from '@statsig/js-client';
const client = new StatsigClient('client-xyz', { userID: 'a-user' }, {
logLevel: LogLevel.Debug,
});
```
### Inspect the `__STATSIG__` Global
Open your browser console and run `__STATSIG__` to inspect the current client instance. Useful properties include `_logger._queue` for pending events.
With multiple instances, pass the SDK key: `Statsig.instance('client-YOUR_KEY')`.
#### How do I handle consent or GDPR flows?
Start with logging disabled and storage blocked, then enable them after consent.
```tsx theme={null}
const client = new StatsigClient('client-xyz', {}, {
loggingEnabled: 'disabled',
disableStorage: true,
});
await client.initializeAsync();
client.updateRuntimeOptions({
loggingEnabled: 'browser-only',
disableStorage: false,
});
```
The SDK buffers up to 500 events in memory and flushes them once logging is re-enabled.
## Additional Resources
* [Client Persistent Assignment](/client/concepts/persistent_assignment)
* [Using EvaluationsDataAdapter](/client/javascript/using-evaluations-data-adapter)
* [Debugging SDK Evaluations](/sdks/debugging)
# JavaScript On-Device Evaluation Client SDK
Source: https://docs.statsig.com/client/jsOnDeviceEvaluationSDK
Use the Statsig JavaScript on-device evaluation SDK in browser and Node.js apps to evaluate feature gates and experiments locally with low latency.
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](/client/onDevice). On-device evaluation SDKs are for Enterprise & Pro Tier only.
These SDKs use a different paradigm than their precomputed counterparts: [JS](/client/javascript-sdk), [Android](/client/Android), [iOS](/client/iosClientSDK), 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](/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
You can install the Statsig SDK via npm, yarn or jsdelivr:
```bash npm theme={null}
npm install @statsig/js-on-device-eval-client
```
```bash yarn theme={null}
yarn add @statsig/js-on-device-eval-client
```
```html CDN /
```
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`
Next, 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 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.
When creating a new client key, select **"Allow Download Config Specs"**
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**.
```typescript theme={null}
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. See [Using EvaluationsDataAdapter](/client/javascript/using-evaluations-data-adapter) to learn how this can be achieved.
## 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](#statsig-user).
```typescript theme={null}
const myUser = {
userID: "a-user",
email: "user@statsig.com"
};
```
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's check a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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 theme={null}
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 can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, **Dynamic Configs** can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```typescript theme={null}
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
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```typescript theme={null}
// 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
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:
```typescript theme={null}
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 theme={null}
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
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](/guides/first-device-level-experiment) 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:
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.
The URL used to flush queued events via a POST request. Takes precedence over `StatsigOptions.api`.
The URL used to flush queued events via `window.navigator.sendBeacon` (web only). Takes precedence over `StatsigOptions.api`.
The URL used to fetch your latest Statsig specifications. Takes precedence over `StatsigOptions.api`.
An object you can use to set environment variables that apply to all of your users in the same session.
Overrides the auto-generated stableID that is set for the device.
How much information is allowed to be printed to the console.
Implementing this type allows customization of the initialization. See [Using SpecsDataAdapter](/client/js-on-device-eval-client/using-evaluations-data-adapter) to learn more.
The maximum amount of time (in milliseconds) that any network request can take before timing out.
The maximum number of events to batch before flushing logs to Statsig.
How often (in milliseconds) to flush logs to Statsig.
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
```typescript theme={null}
// 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 theme={null}
// 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 theme={null}
// 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 theme={null}
// 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:
```typescript theme={null}
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](/client/javascript/using-evaluations-data-adapter) to learn more and see example usage.
## FAQs
#### Does the SDK use the browser local storage or cookies? If so, for what purposes?
The SDK does not use any cookies.
It does use the local storage for feature targeting and experimentation purposes only. Values for feature gates, dynamic configs and experiments are cached in the local storage, which are used as a backup in the event that your website/app cannot reach the Statsig server to fetch the latest values. If any events were logged but could not be sent to Statsig server due to issues like network failure, we also save them in the local storage to be sent again when network restores.
The SDK does not use any cookies.
It does use the local storage for feature targeting and experimentation purposes only. Values for feature gates, dynamic configs and experiments are cached in the local storage, which are used as a backup in the event that your website/app cannot reach the Statsig server to fetch the latest values. If any events were logged but could not be sent to Statsig server due to issues like network failure, we also save them in the local storage to be sent again when network restores.
See the guide on [device level experiments](/guides/first-device-level-experiment).
## Additional Resources
* [On-Device Evaluation SDK Overview](/client/onDevice)
* [Client Keys with Server Permissions](/access-management/api-keys#client-keys-with-server-permissions)
* [Using EvaluationsDataAdapter](/client/javascript/using-evaluations-data-adapter)
* [Debugging SDK Evaluations](/sdk/debugging)
# Migrating to @statsig/js-client
Source: https://docs.statsig.com/client/migration-guides/MigrationFromOldJsClient
Step-by-step guide to migrate from the legacy statsig-js SDK to the new @statsig/js-client SDK, including API changes, imports, and configuration updates.
### Deprecated
Migrate soon! Official support for statsig-js ended Jan 31, 2025.
The architecture and majority of the APIs in the updated SDK have been retained; however,
modifications have been made to address common pitfalls, resolve existing issues, and streamline the SDK logic, resulting in some breaking changes.
## Breaking Changes
* The SDK now offers both a synchronous and asynchronous [initialization](/client/javascript-sdk/migrating-from-statsig-js#initialization) and [updateUser](/client/javascript-sdk/migrating-from-statsig-js#updating-the-user) methods.
* The "getConfig" method has [changed to "getDynamicConfig"](/client/javascript-sdk/migrating-from-statsig-js#getconfig-is-now-getdynamicconfig)
* When Bootstrapping, you'll now have to [pass the hash parameter as 'djb2'](/client/javascript-sdk/migrating-from-statsig-js#bootstrapping)
* The top-level static instance has moved to a static method, [StatsigClient.instance()](/client/javascript-sdk/migrating-from-statsig-js#static-instance)
* Overrides have moved into their own package: [js-local-overrides](/client/javascript-sdk/migrating-from-statsig-js#overrides)
* Parameters for GDPR compliance have [changed and been centralized](/client/javascript-sdk/migrating-from-statsig-js#gdpr)
* The method to retrieve a stableID [has changed](/client/javascript-sdk/migrating-from-statsig-js#stableid-and-getstableid)
* The structure of [cached values has changed](/client/javascript-sdk/migrating-from-statsig-js#cached-values), with implications on first-run experience
* Several StatsigOptions [have changed](/client/javascript-sdk/migrating-from-statsig-js#legacy-statsigoptions)
* Manual exposure logging methods (`getExperimentWithExposureLoggingDisabled`, `checkGateWithExposureLoggingDisabled`)have been deprecated. The checkGate and getExperiment methods now support a second argument to suppress exposure logging [as shown here](/client/javascript-sdk/#manual-exposures).
### Initialization
Previously, the SDK employed a single method for initialization. However, we have recognized that waiting for a method call during app startup can be impractical. Consequently, we have introduced two distinct initialization approaches: one synchronous and one asynchronous.
Synchronous initialization will leverage cache (if available), returning immediately. Data for subsequent sessions will then be fetched in the background.
Asynchronous initialization, on the other hand, is awaitable and ensures that the most current data is fetched and used.
```typescript statsig-js (Legacy) theme={null}
import Statsig from "statsig-js";
// initialize returns a promise which always resolves
await Statsig.initialize(
"client-sdk-key",
{ userID: "some_user_id" },
{ environment: { tier: "staging" } } // optional, pass options here if needed
);
```
```typescript New - Async theme={null}
import { StatsigClient } from '@statsig/js-client';
const client = new StatsigClient(
'client-sdk-key',
{ userID: 'some_user_id' },
{ environment: { tier: 'staging' } }
);
// Async - waits for latest values
await client.initializeAsync();
```
```typescript New - Sync theme={null}
import { StatsigClient } from '@statsig/js-client';
const client = new StatsigClient(
'client-sdk-key',
{ userID: 'some_user_id' },
{ environment: { tier: 'staging' } }
);
// Sync - uses cache, fetches in background
client.initializeSync();
```
View a full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-initialize.tsx) or read more about StatsigClient initialization [here](/client/javascript-sdk#initialize-the-sdk).
### getConfig is now getDynamicConfig
Make sure you update your `getConfig` call sites to call the new method, `getDynamicConfig`. In addition, `DynamicConfig` and `Layer` are no longer classes, but javascript objects. There are still convenience `get` methods, which should remain unchanged.
```js theme={null}
// old
statsig.getConfig('config_name');
// new
statsigClient.getDynamicConfig('config_name');
```
### Bootstrapping
If you are using a server SDK to bootstrap your js/react app, you will need to make some updates to how your server SDK generates values. One of the optimizations we made with this new js-client SDK was to remove the `sha256` library for hashing gate/experiment names. Instead, we use a `djb2` hash. By default, all server SDKs generate `sha256` hashes of gate/experiment names in the `getClientInitializeResponse` method. You will need to set the hash algorithm parameter to that method call to `"djb2"` instead in order to bootstrap this new client SDK. One of the benefits to this hashing algorithm is it will make the entire payload smaller as well, so it's a net win on package size, speed, and payload size for the SDK. This does not change any of the bucketing logic, only the obfuscation method used for the payload.
For example, if you are bootstrapping from a nodejs app, you will need to do:
```js theme={null}
statsig.getClientInitializeResponse(
user,
'[client-key]',
{
hash: 'djb2',
},
);
```
### Updating the User
Similar to initialization, the `updateUser` method now supports both synchronous and asynchronous approaches. Each method functions in the same manner as the initialization process.
```typescript statsig-js (Legacy) theme={null}
import Statsig from "statsig-js";
const user = { userID: "a-user" };
await Statsig.updateUser(user);
```
```typescript New - Async theme={null}
import { StatsigClient } from '@statsig/js-client';
const client = new StatsigClient('client-sdk-key', { userID: 'initial-user' });
await client.initializeAsync();
// Update to new user - async
const newUser = { userID: 'a-user' };
await client.updateUserAsync(newUser);
```
```typescript New - Sync theme={null}
import { StatsigClient } from '@statsig/js-client';
const client = new StatsigClient('client-sdk-key', { userID: 'initial-user' });
client.initializeSync();
// Update to new user - sync
const newUser = { userID: 'a-user' };
client.updateUserSync(newUser);
```
View a full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-update-user.tsx)
## Static Instance
In the previous SDK version, there was a top-level static interface for using Statsig. To enhance support for multiple instances, we have replaced this with a static method that retrieves an instance.
```typescript statsig-js (Legacy) theme={null}
import Statsig from "statsig-js";
await Statsig.initialize(YOUR_CLIENT_KEY, { userID: 'a-user' });
// then later, at some other location in your code base
if (Statsig.checkGate('a_gate')) {
// do something...
}
```
```typescript New theme={null}
import { StatsigClient } from '@statsig/js-client';
// Initialize once in your app
const client = new StatsigClient(YOUR_CLIENT_KEY, { userID: 'a-user' });
await client.initializeAsync();
// then later, at some other location in your code base
const instance = StatsigClient.instance(YOUR_CLIENT_KEY);
if (instance.checkGate('a_gate')) {
// do something...
}
```
View a full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-static-instance.tsx) or read more about StatsigClient multi-instance support [here](/client/javascript-sdk#multiple-client-instances).
## Overrides
Previously, the client had top level methods for managing overrides for gates/configs/experiments/layers, etc. Now, this has been removed from the main SDK and is in its own package. You can implement your own overrides, or use `@statsig/js-local-overrides` and plug it in as the local override adapter in `StatsigOptions`
```
import { StatsigClient } from '@statsig/js-client';
import { LocalOverrideAdapter } from '@statsig/js-local-overrides';
const overrideAdapter = new LocalOverrideAdapter();
overrideAdapter.overrideGate('gate_a', false);
overrideAdapter.overrideGate('gate_b', true);
const client = new StatsigClient(
DEMO_CLIENT_KEY,
{ userID: 'a-user' },
{
overrideAdapter,
},
);
```
Full example here:
[https://github.com/statsig-io/js-client-monorepo/blob/0e7201635f71e77633de04c4c19c1006030a3a81/samples/next-js/src/app/override-adapter-example/OverrideAdapterExample.tsx#L14](https://github.com/statsig-io/js-client-monorepo/blob/0e7201635f71e77633de04c4c19c1006030a3a81/samples/next-js/src/app/override-adapter-example/OverrideAdapterExample.tsx#L14)
## GDPR
In certain use cases (consent management), it is necessary to suspend cache and network usage until the user grants specific permissions. Previously, the method for achieving this was somewhat fragmented. In the new SDK, these functionalities have been consolidated for improved coherence and ease of implementation.
```typescript statsig-js (Legacy) theme={null}
// start the SDK without storage or logging
Statsig.initialize(
'client-key',
{ userID: 'a_user' },
{ disableAllLogging: true, disableLocalStorage: true },
);
// then, once permission was granted
Statsig.shutdown();
Statsig.initialize(
'client-key',
{ userID: 'a_user' },
{ disableAllLogging: false, disableLocalStorage: false },
);
// or, by manually flipping the related flags
Statsig.reenableAllLogging();
StatsigLocalStorage.disabled = false;
```
```typescript New theme={null}
import { StatsigClient } from '@statsig/js-client';
// start the SDK without storage or logging
const client = new StatsigClient(
'client-key',
{ userID: 'a_user' },
{
disableLogging: true,
disableStorage: true,
networkConfig: { preventAllNetworkTraffic: true },
}
);
await client.initializeAsync();
// then, once permission was granted
client.updateRuntimeOptions({
disableLogging: false,
disableStorage: false,
networkConfig: { preventAllNetworkTraffic: false },
});
```
View a full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-gdpr.tsx)
## stableID and getStableID
`statsig.getStableID()` no longer exists. You can get the stableID like this: `myStatsigClient.getContext().stableID`
The key for the stableID in local storage has changed. It is now a function of the SDK key used to initialize the sdk, which enables multiple instances of the SDK to coexist on a single page and not overlap with cached data. If you wish to keep the existing stableID, you should access it in local storage from the old key `STATSIG_LOCAL_STORAGE_STABLE_ID`, and set it in `customIDs` to override the stableID.
## Cached Values
The structure of cached values has changed significantly, and there is no supported way to migrate from the old cached values to the new format. If you wish to pre-populate cached values, we recommend running the new SDK without issuing checks against it for some time before swapping to use it for all checks.
## Legacy StatsigOptions
The options to parameterize initialization of the SDK have changed. In some cases, the underlying features were removed or moved and can be enabled/disabled in a different way. In other scenarios, there is a new API for managing them. The following is a mapping of old options to their equivalents in the new sdk.
#### disableErrorLogging
> This feature does not exist in the new Javascript SDK, so there is no option to disable it.
#### disableAutoMetricsLogging
> Moved to optional package [`@statsig/web-analytics`](https://www.npmjs.com/package/@statsig/web-analytics)
#### disableAllLogging
> This is now referred to as `StatsigOptions.disableLogging`
#### disableCurrentPageLogging
> This is now referred to as `StatsigOptions.includeCurrentPageUrlWithEvents`
#### disableLocalStorage
> This is now referred to as `StatsigOptions.disableStorage`
#### localMode
> This is now referred to as `StatsigOptions.networkConfig.preventAllNetworkTraffic`
#### loggingIntervalMillis
> This is now referred to as `StatsigOptions.loggingIntervalMs`
#### loggingBufferMaxSize
> Unchanged
#### environment
> Unchanged
#### disableNetworkKeepalive
> This is has been completely removed. Network requests can be controlled with `StatsigOptions.networkConfig.networkOverrideFunc`
#### api
> This is now referred to as `StatsigOptions.networkConfig.api`
#### overrideStableID
> stableID is now just part of `StatsigUser.customIDs`. This brings it inline with Statsig server
> SDKs and helps avoid mis-configuration between client and server
#### initTimeoutMs
> Timeouts now live as part of the `async` call.
>
> eg:
> `myStatsigClient.initializeAsync(1000); // 1 sec timeout`
#### initializeValues
> Replaced by the usage of [StatsigEvaluationsDataAdapter](/client/javascript-sdk/using-evaluations-data-adapter)
#### eventLoggingApi
> Replaced by `StatsigOptions.networkConfig.logEventUrl`
#### prefetchUsers
> Replaced by the usage of [StatsigEvaluationsDataAdapter](/client/javascript-sdk/using-evaluations-data-adapter)
#### initCompletionCallback
> Replaced by the usage of [StatsigClientEventEmitter](/client/javascript-sdk#client-event-emitter)
```js theme={null}
statsigClient.on('values_updated', function(evt) {
if(evt.status && evt.status === 'Ready') { /* client has initialized */ }
});
```
#### updateUserCompletionCallback
> Replaced by the usage of [StatsigClientEventEmitter](/client/javascript-sdk#client-event-emitter)
#### fetchMode
> Replaced by the usage of [StatsigEvaluationsDataAdapter](/client/javascript-sdk/using-evaluations-data-adapter)
#### disableDiagnosticsLogging
> There currently is no diagnostics logging in the new SDK
#### initRequestRetries
> This is has been completely removed. Network requests can be controlled with `StatsigOptions.networkConfig.networkOverrideFunc`
#### ignoreWindowUndefined
> No longer applicable
#### disableHashing
> This is now referred to as StatsigOptions.networkConfig.initializeHashAlgorithm
#### logLevel
> This has not been changed, but the enum values are no longer `UPPERCASED`.
#### logger
> Not yet supported
#### evaluationCallback
> Replaced by the usage of [StatsigClientEventEmitter](/client/javascript-sdk#client-event-emitter)
# Migrating to @statsig/react-bindings
Source: https://docs.statsig.com/client/migration-guides/MigrationFromOldReact
Migrate from the legacy statsig-react package to the new @statsig/react-bindings library, with import, provider, and hook changes for the modern SDK.
### DEPRECATED
Migrate soon! Official support for statsig-react ended Jan 31, 2025.
Also refer to our [migration from js-client guide](/client/javascript-sdk/migrating-from-statsig-js), which lists other impacts on statsig-react installations.
Breaking Changes:
* Our [initialization pattern](/client/javascript-sdk/migrating-from-statsig-react#initialize) has changed, along with [waitForInitialization and initializeComponent](/client/javascript-sdk/migrating-from-statsig-react#waitforinitialization-and-initializingcomponent)
* Bootstrapping has changed, now requiring a new hashing parameter: [Bootstrapping the StatsigClient](/client/javascript-sdk/migrating-from-statsig-react#bootstrapping-the-statsigclient)
### Initialize
In the old `statsig-react` package, all values needed to be given to the StatsigProvider, which internally would setup the Statsig client instance. This approach lead to issues in managing state between the Statsig client and the StatsigProvider, making it fragile and likely to break if you ever tried using the Statsig client directly.
The new approach is to run everything through the Statsig client instance, and just pass that to the StatsigProvider.
```jsx statsig-react (Legacy) theme={null}
import { StatsigProvider } from "statsig-react";
function App() {
return (
{/* Rest of App ... */}
);
}
```
```tsx New theme={null}
import { StatsigProvider } from '@statsig/react-bindings';
import { StatsigClient } from '@statsig/js-client';
// Create the client
const client = new StatsigClient(
'',
{ userID: 'a-user' },
{
environment: { tier: 'staging' },
}
);
function App() {
return (
Loading...}>
{/* Rest of App ... */}
);
}
```
View the full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/react-precomp/sample-react-precomp-initialize.tsx)
### waitForInitialization and initializingComponent
In the older versions of the `StatsigProvider`, it was possible to set the `waitForInitialization` to block children from rendering until after the latest
values were fetched from Statsig and if a `initializeComponent` was set, this was displayed while the latest values were fetched.
It was also possible to set `waitForInitialization` to `false`, meaning the StatsigProvider would render immediately, before values were ready. This was not recommended as it meant values could change between checks, resulting in unexpected layout changes.
**Where did waitForInitialization go?**
In the newer `StatsigProvider` this is no longer an option as we want to prevent developers from unintentionally allowing values to change mid-session.
It is still possible to get the same behavior as setting `waitForInitialization` to false, but we recommend against it.
Read the [Initialization Strategies](/client/javascript-sdk/init-strategies) guide to learn how to replicate the `waitForInitialization=false` behavior, as well as the recommended approaches to synchronous initialization.
### Bootstrapping the StatsigClient
If you are using a Statsig Server SDK to bootstrap the Statsig Client used by your React app, you may need to make some updates to how your server SDK generates values.
One of the optimizations we made with the `@statsig/js-client` SDK was to remove the `sha256` library for hashing gate/experiment names.
Instead, we use a `djb2` hash. This does not change any of the bucketing logic, only the obfuscation method used for the payload.
By default, all server SDKs generate `sha256` hashes of gate/experiment names in the `getClientInitializeResponse` method.
You will need to set the hash algorithm parameter to that method call to `"djb2"` instead in order to bootstrap this new client SDK.
One of the benefits to this hashing algorithm is it will make the entire payload smaller as well, so it's a net win on package size, speed, and payload size for the SDK.
For example, if you are bootstrapping from the Statsig Node SDK, you will need to do:
```js theme={null}
statsig.getClientInitializeResponse(
user,
'[client-key]',
{
hash: 'djb2', // <- New Hashing Algorithm
},
);
```
### Updating the User
```jsx statsig-react (Legacy) theme={null}
import { useContext, useState } from "react";
import { StatsigUser, StatsigProvider, StatsigContext } from "statsig-react";
function UpdateUserButton() {
const { updateUser } = useContext(StatsigContext);
return updateUser({ userID: "b-user" })}>Update
}
function App() {
const [user, setUser] = useState({ userID: "a-user" });
return (
);
}
```
```tsx New theme={null}
import { StatsigProvider, useClientAsyncInit } from '@statsig/react-bindings';
import { StatsigClient } from '@statsig/js-client';
const client = new StatsigClient('', { userID: 'a-user' });
function UpdateUserButton() {
const { client } = useClientAsyncInit(client);
const handleUpdate = async () => {
await client.updateUserAsync({ userID: 'b-user' });
};
return Update ;
}
function App() {
return (
);
}
```
View the full example on [GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/react-precomp/sample-react-precomp-update-user.tsx)
# On Device Client SDKs
Source: https://docs.statsig.com/client/onDeviceOverview
Overview of Statsig on-device evaluation client SDKs that evaluate feature gates and experiments locally for low-latency rules evaluation on devices.
## On Device SDK Overview
Statsig's client-side On-Device Eval SDKs provide an alternate client-side architecture where the definition of each experiment or gate is kept in-memory on the device, allowing for faster evaluation with a frequently changing user object (which would require re-initialization on regular client SDKs), at the expense of the privacy of the config definitions.
Generally, we encourage customers to use our traditional client SDKs, unless they have specific requirements making that impossible. If you do choose to use the on-device eval SDKs, we encourage you to speak with our team first and understand the privacy risks.
## Alternatives
An alternative approach to On-Device Eval SDKs is our [Local Eval Adapter](/client/concepts/local-eval-adapter) which allows you to evaluate locally for only a subset of your experiments/gates that might need to be available at startup, rather than exposing all configs in your project.
# Swift On Device Evaluation SDK
Source: https://docs.statsig.com/client/swiftOnDeviceEvaluationSDK
Use the Statsig Swift on-device evaluation SDK in iOS, macOS, tvOS, and watchOS apps to evaluate feature gates and experiments locally with low latency.
Source code: statsig-io/swift-on-device-evaluations-sdk
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/onDevice). On-device evaluation SDKs are for Enterprise & Pro Tier only.
These SDKs use a different paradigm than their precomputed counterparts: [JS](/client/javascript-sdk), [Android](/client/Android), [iOS](/client/iosClientSDK), 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](/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
To use the SDK in your project, you must add Statsig as a dependency.
```swift Swift Package Manager theme={null}
// In your Xcode, select File > Swift Packages > Add Package Dependency
// and enter the URL https://github.com/statsig-io/swift-on-device-evaluations-sdk.git.
//
// You can also include it directly in your project's Package.swift.
// Find out the latest release version on our GitHub page:
// https://github.com/statsig-io/swift-on-device-evaluations-sdk/releases
dependencies: [
// see the latest version on https://github.com/statsig-io/swift-on-device-evaluations-sdk/releases
.package(url: "https://github.com/statsig-io/swift-on-device-evaluations-sdk.git", .upToNextMinor("X.Y.Z")),
],
//...
targets: [
.target(
name: "YOUR_TARGET",
dependencies: ["StatsigOnDeviceEvaluations"]
)
],
```
```ruby CocoaPods theme={null}
# If you are using CocoaPods, our pod name is 'StatsigOnDeviceEvaluations',
# and you can include the following line to your Podfile:
use_frameworks!
target 'TargetName' do
//...
pod 'StatsigOnDeviceEvaluations', '~> X.Y.Z'
end
# Find the latest versions by searching cocoapods.org or on Github:
# https://github.com/statsig-io/swift-on-device-evaluations-sdk/releases
```
Next, 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 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.
When creating a new client key, select **"Allow Download Config Specs"**
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**.
```swift Async (Swift) theme={null}
import StatsigOnDeviceEvaluations
// (optional) Configure the SDK if needed
let opts = StatsigOptions()
opts.environment.tier = "staging"
Statsig.shared.initialize("client-sdk-key", options: opts) { err in
if let err = err {
print("Error \(err)")
}
}
// or, create your own instance
let myStatsigInstance = Statsig()
myStatsigInstance.initialize("client-sdk-key", options: opts) { err in
if let err = err {
print("Error \(err)")
}
}
```
```objective-c Objective C theme={null}
StatsigOptions *options = [StatsigOptions new];
StatsigEnvironment *env = [StatsigEnvironment new];
env.tier = @"staging";
options.environment = env;
[[Statsig sharedInstance]
initializeWithSDKKey:@"client-sdk-key"
options:options
completion:^(NSError * _Nullable error) {
if (error != nil) {
NSLog(@"Error %@", error);
}
}];
```
```swift Synchronous (Swift) theme={null}
import StatsigOnDeviceEvaluations
// (optional) Configure the SDK if needed
let opts = StatsigOptions()
opts.environment.tier = "staging"
let specs: NSString = "..." // JSON string of your configurations
let error = client.initializeSync("client-sdk-key", initialSpecs: specs)
if let err = error {
print("Error \(err)")
}
```
It is possible to configure the SDK to use cached values if they are newer than the local file.
This can be useful if you ship your app with a local file, but would like it to only be used for the first session.
In the following example, the SDK will only use initialSpecs if there is no cache or if the cache is older than initialSpecs.
```swift theme={null}
let options = StatsigOptions()
options.useNewerCacheValuesOverProvidedValues = true
client.initializeSync(
"client-sdk-key",
initialSpecs: specs,
options: options
)
```
You can get a copy of your current specs data by visiting: `https://api.statsigcdn.com/v1/download_config_specs/client-{YOUR_SDK_KEY}.json`
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's check a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
```swift Swift theme={null}
// Simple Pass/Fail check
let isPassing: Bool = Statsig.shared.checkGate("my_gate", user)
// or, the verbose FeatureGate check
let gate = Statsig.shared.getFeatureGate("my_gate", user)
print(gate.evaluationDetails.reason) // "Network" | "Cache" | "Unrecognized"
let isPassing: Bool = gate.value
```
```objective-c Objective C theme={null}
BOOL isPassing = [[Statsig sharedInstance] checkGate:@"my_gate" forUser:user];
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, **Dynamic Configs** can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```swift theme={null}
let config = Statsig.shared.getDynamicConfig("my_dynamic_config", user)
let name: String? = config.value["product_name"] as? String
let price: Double? = config.value["price"] as? Double
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```swift theme={null}
// Getting values via getLayer
let layer = Statsig.shared.getLayer("my_layer", user)
let name: String? = layer.getValue(param: "product_name", fallback: "Unknown") as? String
// or, using getExperiment
let experiment = Statsig.shared.getExperiment("my_experiment", user)
let name: String? = experiment.value["product_name"] as? String
let price: Double? = experiment.value["price"] as? Double
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:
```swift theme={null}
let event = StatsigEvent(
eventName: "add_to_cart",
value: "SKU_1234",
metadata: [
"price": "9.99",
"item_name": "CoolProduct"
]
)
Statsig.shared.logEvent(event, user)
```
### Code Examples
Working sample apps are available in the repository:
* [Swift & Objective C Examples](https://github.com/statsig-io/swift-on-device-evaluations-sdk/tree/main/Sample/App/Examples/OnDeviceEvaluations)
Included are both Swift and Objective C uses.
## 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](/guides/first-device-level-experiment) 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:
```swift Swift theme={null}
let user = StatsigUser(
userID: "a-user",
customIDs: ["EmployeeID": "an-employee"],
email: "user@statsig.io",
ip: "58.84.239.246",
userAgent: "Mozilla/5.0 (iPad; CPU OS 13_4_1....",
country: "NZ",
locale: "en_NZ",
appVersion: "3.2.1",
custom: ["Level": "9001"],
privateAttributes: ["SensitiveInfo": "shhh"]
)
```
```objective-c Objective C theme={null}
StatsigUser *user = [StatsigUser userWithUserID:@"a-user"];
user.customIDs = @{ @"EmployeeID": @"an-employee" };
user.email = @"user@statsig.io";
user.ip = @"58.84.239.246";
user.userAgent = @"Mozilla/5.0 (iPad; CPU OS 13_4_1....";
user.country = @"NZ";
user.locale = @"en_NZ";
user.appVersion = @"3.2.1";
[user.custom setString:@"9001" forKey:@"Level"];
[user.privateAttributes setString:@"shhh" forKey:@"SensitiveInfo"];
```
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
### Setting a Global User
To avoid needing to pass the user object to every single evaluation call, you can set a global user.
This user will be used for all evaluations unless otherwise specified.
```swift theme={null}
Statsig.shared.setGlobalUser(myGlobalUser)
Statsig.shared.checkGate("my_gate") // <- Will use myGlobalUser
Statsig.shared.checkGate("my_gate", StatsigUser(userID: "user-123")) // <- Will NOT use myGlobalUser
```
The maximum number of events to batch before flushing logs to the server.
How frequently to flush queued logs.
The API where all events are sent.
The API used to fetch the latest configurations.
An object you can use to set environment variables that apply to all of your users in the same session and will be used for targeting purposes.
## 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:
```swift Swift theme={null}
Statsig.shared.shutdown { err in
if let err = err {
print("An error occurred during Statsig shutdown: \(err)")
} else {
print("Statsig shutdown successfully")
}
}
```
```objective-c Objective C theme={null}
[[Statsig sharedInstance] shutdownWithCompletion:^(NSError * _Nullable error) {
if (error != nil) {
NSLog(@"An error occurred during Statsig shutdown: %@", error);
} else {
NSLog(@"Statsig shutdown successfully");
}
}];
```
## Post Init Syncing
### From Network
By default, the SDK will only sync during initialization. If you would like to re-sync after initialization, you can call the `Statsig.update` method.
This will trigger a network call to fetch the latest changes from the server.
```swift theme={null}
Statsig.shared.update { err in
if let err = err {
print("Statsig update error: \(err)")
}
}
```
### From a Local File
If you maintain your own copy of the "specs" json, you can pass it in to the update with `Statsig.updateSync()`. This will skip the network call and use the provided specs instead.
```swift theme={null}
let result = Statsig.shared.updateSync(updatedSpecs: myJsonData)
```
### Scheduled Polling
If you would like the SDK to regularly poll for updates, you can start the polling task with `Statsig.scheduleBackgroundUpdates()`.
This will call `Statsig.update` internally, hitting the network and pulling down the latest changes.
```swift theme={null}
let pollingTask = Statsig.shared.scheduleBackgroundUpdates() // Defaults to 1 hour interval
// or, specify a custom interval
let pollingTask = Statsig.shared.scheduleBackgroundUpdates(intervalSeconds: 300)
// and, if you need to cancel it later
pollingTask?.cancel()
```
## Local Overrides
It is possible to override the values returned by the Statsig SDK. This can be useful in unit testing or for enabling features for local development.
To get setup with local overrides, you can pass an instance of `LocalOverrideAdapter` to the SDK via the `StatsigOptions` object.
It is possible to write your own override adapter. You can implement the [`OverrideAdapter`](https://github.com/statsig-io/swift-on-device-evaluations-sdk/blob/main/Sources/StatsigOnDeviceEvaluations/OverrideAdapter.swift) protocol and pass that in instead.
```swift Swift theme={null}
let user = StatsigUser(userID: "a-user")
let overrides = LocalOverrideAdapter()
// Override a gate
overrides.setGate(user, FeatureGate.create("local_override_gate", true))
// Override a dynamic config (Similar for Layer and Experiment)
overrides.setDynamicConfig(user, DynamicConfig.create("local_override_dynamic_config", ["foo": "bar"]))
let opts = StatsigOptions()
opts.overrideAdapter = overrides
Statsig.shared.initialize(YOUR_SDK_KEY, options: opts) { _ in
let gate = Statsig.shared.getFeatureGate("local_override_gate", user)
print("Result: \(gate.value) (\(gate.evaluationDetails.reason))")
}
```
```objective-c Objective C theme={null}
StatsigUser *user = [StatsigUser userWithUserID:@"a-user"];
LocalOverrideAdapter *overrides = [LocalOverrideAdapter new];
// Override a gate
[overrides
setGateForUser:user
gate:[FeatureGate createWithName:@"local_override_gate" andValue:true]];
// Override a dynamic config (Similar for Layer and Experiment)
[_overrides
setDynamicConfigForUser:user
config:[DynamicConfig
createWithName:@"local_override_dynamic_config"
andValue:@{@"foo": @"bar"}]];
StatsigOptions *options = [StatsigOptions new];
options.overrideAdapter = overrides;
[[Statsig sharedInstance]
initializeWithSDKKey:YOUR_SDK_KEY
options:options
completion:^(NSError * _Nullable error) {
FeatureGate *gate = [[Statsig sharedInstance] getFeatureGate:@"local_override_gate" forUser:user options:nil];
NSLog(@"Result: %d (%@)", gate.value, gate.evaluationDetails.reason);
}];
```
## FAQs
See the guide on [device level experiments](/guides/first-device-level-experiment).
## Additional Resources
* [On-Device Evaluation SDK Overview](/client/onDevice)
* [Client Keys with Server Permissions](/access-management/api-keys#client-keys-with-server-permissions)
* [Debugging SDK Evaluations](/sdk/debugging)
# AI Governance, Security & Privacy
Source: https://docs.statsig.com/compliance/ai_governance_security_privacy
Reference for Statsig's AI governance, security, and privacy practices, including data handling, retention, and customer obligations for AI features.
Trust, security, and privacy are central to Statsig's operations. Your data remains confidential, secure, and owned by you across the Statsig platform.
## Governance
The AI features on the Statsig platform use your data to provide additional insights, analysis, and solutions for your review. Examples of our AI features include Knowledge Graph, hypothesis advisor, and suggested metrics. By design, your data is kept separate in our production environment from other customer data. Statsig does not mix or process data from different customers together. This means we do not expose your data to other customers.
Your data is not used to build or develop any AI models unless you provide explicit written consent. You own the data you provide and control which of your internal sources are connected to the Statsig platform. You also control who has access to the Statsig platform within your organization. Information on single sign-on on the Statsig platform can be found [here](/access-management/sso/overview).
## Security
Whether you are sending aggregated metrics, custom attributes, or hashed identifiers or connecting parts of your code base, Statsig understands the importance of security. Because security starts at design, Statsig's software development lifecycle ensures we design and build security into our offerings at inception. We embrace zero trust and defense in-depth approaches to guide our overall security program. We have also implemented layered security controls across our endpoints, infrastructure, networks, and applications.
Statsig uses strong, industry-standard security practices and cryptography to protect your data. This includes using AES-256 encryption at rest and TLS 1.2 or higher in transit. We use automated alerts and manual investigation processes to address any suspicious activity. Our systems also undergo regular risk assessments and audits, including by independent third parties to ensure adherence to high security standards. In addition, Statsig maintains a SOC 2 Type II certification. For more information on Statsig's security practices, you can visit [Security at Statsig](https://www.statsig.com/trust/security).
## Privacy
Statsig's data protection practices are designed to support your compliance with GDPR, CCPA, and other applicable privacy laws across our platform. For cross border data transfers, Statsig complies with the EU-US Data Privacy Framework, the UK Extension to the EU-US Data Privacy Framework, and the Swiss-US Data Privacy Framework. Statsig also provides a [Data Processing Addendum](https://www.statsig.com/legal/online-dpa) to support its customers' data handling requirements. These privacy protections also extend to all AI features.
AI features on the Statsig platform utilize third-party large language models (LLMs). Data processed through these LLMs is not retained, accessed, or used by the underlying third-party model providers. By design, your data is also never shared with other customers. Further, Statsig's subprocessors are only permitted to use the data as directed by Statsig and in accordance with our contractual commitments. A list of Statsig's subprocessors is available [here](https://www.statsig.com/legal/subprocessors/).
# Data Privacy for Mobile
Source: https://docs.statsig.com/compliance/data_privacy_for_mobile
Data privacy considerations when using Statsig mobile SDKs, including handling of identifiers, opt-out mechanisms, and platform-specific requirements.
## General
### What data does Statsig collect from users of my app?
Statsig collects only the data that you configure to be sent to Statsig. This is typically the occurrence of feature flag evaluations (Feature Gates), experiment exposures, and custom events you log with the SDK.
### Does that data include any personally identifiable information (PII)?
By default, Statsig uses randomly generated IDs as described below. You can also augment data sent to Statsig with additional context and meta data, including user names, email addresses, or custom attributes. This data, alone or in combination with other data, may constitute PII if it identifies, directly or indirectly, an individual.
### Does Statsig use the device ID to identify a user?
No. Statsig on Mobile doesn't use device ID such as Secure.ANDROID\_ID and advertisingIdentifier on iOS. Instead, it uses a StableID which is randomly generated per device, per app, and per installation, and therefore can't be used to identify a single device across application installations. When an application is reinstalled, a new StableID is generated. Since these IDs are solely used to provide approximate statistical information as part of the application monitoring service, it serves that purpose. It's required, for example, for Crash Free Session and User Rates, as well as to indicate the impact of issues based on number of events vs affected users.
### What does Statsig do with the data it collects?
Statsig processes the data you send to it to provide our feature flag management, experimentation, and analytics services to you.
## Apple App Store
### Do I need to disclose the use of Statsig in App Store Connect on the Apple App Store?
Yes, Statsig is a third-party partner whose code (SDKs) you integrate in your app that collects data from users of your app.
### What do I need to disclose to Apple?
You would need to disclose all types of data you are collecting through your app, including data you are sending to Statsig. This could include "Contact Info" or "Identifiers" if you provide those in the StatsigUser object, but don't forget to include any other categories of data that you are collecting or have configured the SDKs to send to Statsig.
### How does Statsig use my data?
The standard data use cases for Statsig would be "Analytics" and "App Functionality", but you would also need to disclose to Apple any other ways in which you or your app use data you are collecting.
### Does Statsig use my data to track users?
Statsig does not use your data to track users. However, if you or your other third-party partners are tracking users, you would still need to disclose this to Apple.
### Does Statsig use the Advertising Identifier (IDFA)?
No. Statsig doesn't require IDFA.
## Google Play
### Does Statsig collect any PII from children?
If your app is targeted to children and you configure Statsig to collect PII, then Statsig would collect the elements that you've designated. You would remain responsible for obtaining any appropriate parental consents with respect to the PII you collect from your users and subsequently send to Statsig. You would also remain responsible for declaring your app's target age group to Google Play.
### Do Statsig SDKs cause my app to contain ads?
No. Statsig does not cause your app to contain any ads.
### What do I need to disclose to Google Play?
You would need to disclose and/or include in your app privacy policy all types of data you are collecting through your app, including data you are sending to Statsig.
## Privacy Controls
### What device and user metadata does Statsig automatically collect?
The Statsig SDKs automatically collect the following metadata for targeting and analytics purposes:
**iOS SDK collects:**
* appIdentifier: Your app's bundle identifier
* appVersion: Your app's version
* deviceModel: The device model (e.g., iPhone14,3)
* deviceOS: The operating system (iOS)
* language: The user's preferred language
* locale: The user's locale identifier
* sdkType: The type of SDK (ios-client)
* sdkVersion: The version of the Statsig SDK
* sessionID: A randomly generated UUID for the current session
* stableID: A persistent device identifier (see below)
* systemVersion: The iOS version
* systemName: The system name (iOS)
**Android SDK collects:**
* appIdentifier: Your app's package name
* appVersion: Your app's version name
* deviceModel: The device model (e.g., Pixel 7)
* deviceOS: The operating system (Android)
* locale: The user's locale
* language: The user's language
* sdkType: The type of SDK (android-client)
* sdkVersion: The version of the Statsig SDK
* sessionID: A randomly generated UUID for the current session
* stableID: A persistent device identifier (see below)
* systemVersion: The Android API level
* systemName: The system name (Android)
### How can I limit the metadata collected by Statsig?
Both iOS and Android SDKs provide the `optOutNonSdkMetadata` option to limit the collection of device-specific information:
**iOS SDK:**
```swift theme={null}
let options = StatsigOptions()
options.optOutNonSdkMetadata = true
Statsig.start(sdkKey: "client-sdk-key", options: options)
```
**Android SDK:**
```kotlin theme={null}
val options = StatsigOptions(optOutNonSdkMetadata = true)
```
When `optOutNonSdkMetadata` is enabled, only the following core SDK metadata is included:
* sdkType: The type of SDK
* sdkVersion: The version of the Statsig SDK
* sessionID: A randomly generated UUID for the current session
* stableID: A persistent device identifier
All device-specific information (appIdentifier, appVersion, deviceModel, deviceOS, locale, language, systemVersion, systemName) is excluded from logs and targeting.
### How does StableID work?
The StableID is a persistent identifier that Statsig uses to provide consistent user experiences and analytics:
**iOS Implementation:**
* The StableID is stored in UserDefaults with the key "com.Statsig.InternalStore.stableIDKey"
* When first generated, it's created as a random UUID
* It persists across app launches but is regenerated when the app is reinstalled
* It can be overridden via the StatsigOptions.overrideStableID parameter
**Android Implementation:**
* The StableID is stored in SharedPreferences
* When first generated, it's created as a random UUID
* It persists across app launches but is regenerated when the app is reinstalled
* It can be overridden via the StatsigOptions.overrideStableID parameter
The StableID is not shared across different apps or websites and cannot be used to track users across different applications or platforms.
### How can I prevent sending sensitive user data to Statsig?
Use the `privateAttributes` field for sensitive data that should be used for targeting but not logged:
**iOS SDK:**
```swift theme={null}
let user = StatsigUser(
userID: "user-123",
email: nil, // Not included at top level to keep private
privateAttributes: ["email": "user@example.com"] // Used for evaluation but not logged
)
```
**Android SDK:**
```kotlin theme={null}
val user = StatsigUser("user-123")
user.privateAttributes = mapOf("email" to "user@example.com")
```
These attributes are sent to Statsig servers during initialization for feature flag and experiment evaluation, but are removed before sending any event logs to Statsig servers. This means the attributes can be used for targeting users with specific features or experiments, but won't appear in your analytics data.
For more comprehensive privacy controls, consider using [Client Bootstrapping](/client/concepts/initialize#bootstrapping-overview) to generate all assignments locally on your server, eliminating the need to send any user attributes from the client device to Statsig.
# User Data Deletion Requests API
Source: https://docs.statsig.com/compliance/user_data_deletion_requests
How to submit and process user data deletion requests in Statsig to comply with GDPR, CCPA, and other privacy regulations across SDK and console data.
User data deletion requests are for Enterprise contracts only. Please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you need to enable Enterprise features as you use Statsig.
We currently only support deleting data for unit type `user_id`.
GDPR and similar laws may require that you delete a user's data when they request it. To support deletion requests on our side, we have built this API for you to call.
### How to use the API
All requests must include the STATSIG-API-KEY field in the header. The value should be a SERVER API Key which can be created in the Project Settings on console.statsig.com/api\_keys.
## Sending Requests
Data deletion requests take the following parameters:
* `unit_type`: The unit type that corresponds to the IDs that you would like to deleted. Currently, we only support `user_id`. Support for other ID types will be added in the future.
* `ids`: A comma separated list containing the IDs you would like to delete data for
* `delimiter` (optional): In the case that your IDs contain commas, you can use a different delimiter to separate the IDs, and pass that delimiter here
* `request_id` (optional): If you store a request ID on your side that you would like us to use, you can pass it in, and it will be used to track the request. If left unset, we will provide an ID for you to use in the response. Note that it must be a unique ID if you are supplying your own, otherwise the request will fail with a 400 code.
```bash theme={null}
curl \
--header "statsig-api-key: " \
--header "Content-Type: application/json" \
--request POST \
--data '{"unit_type": "user_id", "ids": "1,2,3", "request_id": "test_request_1"}' \
"https://api.statsig.com/v1/delete_user_data"
```
Response:
`{"request_id":"test_request_1"}`
## Checking on Deletion Status
Using the request ID, you can check on the status of a deletion.
Input:
* `request_id`: The ID of the request
Output:
* `COMPLETE` if the data has been deleted
* `PENDING` if the data is still pending deletion
* `UNKNOWN` if this is an invalid request ID
```bash theme={null}
curl \
--header "statsig-api-key: " \
--header "Content-Type: application/json" \
--request POST \
--data '{"request_id": "test_request_1"}' \
"https://api.statsig.com/v1/get_delete_user_data_request_status"
```
Response:
`PENDING`
## SLA
Data deletion requests are not handled synchronously. We batch requests and do mass deletions periodically. We guarantee that data will be deleted within 30 days of receiving a request.
## Important Notes
* Once a data deletion request has been submitted, it cannot be deleted
* Once data has been deleted, we no longer store the set of IDs that we deleted data for (since this is considered personally identifiable information in some cases)
* The User Data Deletion Requests API deletes data from the Statsig platform only. To delete data from the Amplitude platform, use Amplitude's [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy).
# Console API Overview
Source: https://docs.statsig.com/console-api/introduction
Introduction to the Statsig Console API for programmatically managing feature gates, experiments, dynamic configs, metrics, and project settings.
The "Console API" is the CRUD API for performing the actions offered on console.statsig.com without needing to go through the web UI.
If you have any feature requests, drop on in to our [slack channel](https://www.statsig.com/slack) and let us know.
## Base URL
`https://statsigapi.net`
## Authorization
All requests must include the **STATSIG-API-KEY** field in the header. The value should be a **Console API Key** which can be created in the Project Settings on [console.statsig.com/api\_keys](https://console.statsig.com/api_keys)
## Rate Limiting
Mutation requests (POST/PATCH/PUT/DELETE) to the Console API are limited to \~ 100 requests / 10 seconds and \~ 900 requests / 15 minutes, per project.
## API Version
The Console API is versioned. Each version is guaranteed to not break existing usage; each new version introduces breaking changes. There is only one version: `20240601`. The [OpenAPI spec](https://api.statsig.com/openapi/20240601.json) for this API version is kept up-to-date.
Pass the version in the **STATSIG-API-VERSION** field in the header. For now, this is optional; in the future, this will be required.
# Control Panel
Source: https://docs.statsig.com/control-panel/overview
Use the Statsig Control Panel to track, search, and manage feature gates, experiments, dynamic configs, and rollouts across your entire project.
Control Panel is a surface to measure and track you and your teams' features that are deployed and measured with Statsig. This surface is similar to the standard gate/experiment tables in Statsig, and enables quickly tabbing between filters on top of the objects used to deploy and measure changes - configs, experiments, and gates - and quickly measure them, make or review ship decisions, and manage development flows like overrides.
## Using Control Panel
* Configure Sections in the left hand column. These specify different filters and display settings - e.g. "My Changes", or "My Team's Changes".
* View results inline. Configs and experiments have a summary of metric movements, which can be hovered to see a table of all observed metric movements. Gates and Dynamic Configs can be opened to see results per-rule.
* Manage configs. You can see or set your override status from control panel, and additionally killswitch features in case there's unexpected behaviors
This feature is in Beta. Please reach out if you or your team would like to try it!
# Athena Ingestion
Source: https://docs.statsig.com/data-warehouse-ingestion/athena
Configure Statsig data warehouse ingestion from Amazon Athena, including authentication, scheduled queries, and mapping to events and properties.
## Overview
To set up connection with Athena, Statsig needs the following
* Region
* Granting Athena Access Permissions to a Statsig-owned Service Account
In place of granting Athena Access Permissions to a Statsig-owned Service Account, you can also provide the following:
* IAM User Access Key
* IAM Secret Access Key
The above IAM User will need to be given permissions to query from Athena. Here's a sample policy with required permissions to access Athena:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:CreatePreparedStatement",
"athena:DeletePreparedStatement",
"athena:GetPreparedStatement",
"athena:GetQueryResultsStream",
"s3:GetObject",
"s3:ListBucket",
"s3:GetBucketLocation",
"glue:GetTable",
"glue:GetDatabase"
],
"Resource": [
"arn:aws:athena:*::workgroup/*",
"arn:aws:glue:::*"
]
}
]
}
```
# BigQuery
Source: https://docs.statsig.com/data-warehouse-ingestion/bigquery
Configure Statsig data warehouse ingestion from Google BigQuery, including authentication, scheduled queries, and mapping to events and properties.
## Overview
To set up connection with BigQuery, we need the following:
* Granting Permissions to a Statsig-owned Service Account
* Your BigQuery Project ID
Start by enabling the BigQuery source under Metrics -> Ingestion -> Add Source.
## Grant Permissions to Statsig's Service Account
You need to grant some permissions for Statsig from your Google Cloud console in order for us to access your BigQuery data.
1. In your BigQuery's [IAM & Admin settings](https://console.cloud.google.com/iam-admin/), add the Statsig service account you copied in the Statsig Console as a new principal for your project, and give it the following roles:
* `BigQuery User`
OR
Exposure event import is deprecated. If this is an important use case, see [Statsig Warehouse Native](https://www.statsig.com/blog/announcing-statsig-warehouse-native), available to Enterprise Customers
Exposure events are generated by your assignment tool, when it assigns your users to a certain variant of an experiment (e.g., show ad vs. hide ad).
#### Required
| Column | Description | Format/Rules |
| ---------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
| timestamp | The unix time your event was logged at | BIGINT. please cast timestamps into timezoneless unix time |
| experiment | Your experiment identifier | STRING/VARCHAR. Not null. Length \< 128 characters |
| group\_id | Unique identifier for the experiment groups | STRING/VARCHAR. Not null. |
| unit\_id | Unique user identifier | STRING/VARCHAR. User ID, Stable ID, etc. The same event row can have multiple IDs |
#### Optional
| Column | Description | Rules |
| -------------- | ----------------------------- | ------------------------------------------------------------------------------------------------ |
| metadata\_json | Metadata json about the event | JSON STRING. Statsig will unpack this json 1 level deep. Nested values will be stored as strings |
# Databricks
Source: https://docs.statsig.com/data-warehouse-ingestion/databricks
Configure Statsig data warehouse ingestion from Databricks, including authentication, scheduled queries, and mapping to events and user properties.
## Overview
To set up connection with Databricks, Statsig needs the following
* API Key
* Server Hostname
* HTTP Path
We can use any cluster in your project to connect to your data, but we recommend using a databricks [SQL warehouse/endpoint](https://docs.databricks.com/sql/admin/sql-endpoints.html) so that the cluster does not need to spin up for every pull.
### API Key
You can generate a new API key by going to "User Settings" in your Databricks console. There, you should be able to generate a new token as shown below.
We support you making multiple data connections to your project, but only support a single export connection.
1. [BigQuery](/data-warehouse-ingestion/bigquery)
2. [Redshift](/data-warehouse-ingestion/redshift)
3. [Snowflake](/data-warehouse-ingestion/snowflake)
4. [Databricks](/data-warehouse-ingestion/databricks)
5. [Synapse](/data-warehouse-ingestion/synapse)
6. [S3](/data-warehouse-ingestion/s3)
7. [Athena](/data-warehouse-ingestion/athena)
Warehouse Native users: You're viewing the Cloud docs for this page. If your project is configured as [Statsig Warehouse Native](/statsig-warehouse-native/introduction/), your data should already be available if you completed the [quickstart](../statsig-warehouse-native/guides/quick-start/).
### How it works
In Statsig console, you can:
1. Set up connection to your data warehouse
2. Query your data warehouse for appropriate data
3. Map your data fields to Statsig's expected schema
4. Bulk ingest & schedule future ingestions
Ingestion is set up on a daily schedule. Statsig will run a query you provide on your data warehouse, download the result set, and materialize the results into your console the same as those that came in through the SDK.
If data lands late or is updated, Statsig will detect this change and reload the data for that day (details below).
### How to Begin Data Ingestion
To begin ingestion from a Data Warehouse:
1. Go to your Statsig Console
2. Navigate to Data tab on the side navigation bar
3. Go to the "Ingestion" tab
Auto-generated **User Accounting Metrics** are not supported today for data warehouse ingestions.
### Troubleshooting Ingestions
If any ingestion errors occur, Statsig will notify you in project and direct your to the Ingestions page. You can diagnose an error directly in Statsig by following the step-by-step triage flow. Common errors may include missing permissions and out-of-date credentials.
### API Triggered Ingestion (mark\_data\_ready)
Enterprise customers can trigger ingestion for `metrics` or `events` using the statsig API. This will run your daily ingestion immediately after triggering, and can be helpful for companies whose data availability timing may vary day over day and want data to land as soon as possible in Statsig. This can be enabled by selecting "API Triggered" as your ingestion schedule - note that with this enabled, there will not be an automatic ingestion, but we will still re-sync data after the initial ingestion if we observe a change.
To trigger ingestion, send a post request to the `https://api.statsig.com/v1/mark_data_ready_dwh` endpoint using your statsig API key. An example would be:
```
curl \
--header "statsig-api-key: " \
--header "Content-Type: application/json" \
--request POST \
--data '{"datestamps": "2023-02-20", "type": "events", "sources":["source1", "source2]}' \
"https://api.statsig.com/v1/mark_data_ready_dwh"
```
Parameters:
* datestamps: Refers to the date of the data being triggered.
* type: `metrics` or `events`
* sources (only for multi-source ingestions): Array of strings representing the sources to trigger
This is rate limited to once every two hours, and there may be a few minutes delay after triggering before status updates while compute resources are created.
### Frequently Asked Questions
For frequently asked questions, see our [FAQ page](/data-warehouse-ingestion/faq).
# Redshift
Source: https://docs.statsig.com/data-warehouse-ingestion/redshift
Configure Statsig data warehouse ingestion from Amazon Redshift, including authentication, scheduled queries, and mapping to events and properties.
## Overview
To set up connection with Redshift, Statsig needs the following
* Cluster Endpoint
* Admin User Name
* Admin User Password
SHA256 passwords are not currently supported, please utilize MD5 to avoid issues.
You can find this information in your aws console within your specific cluster, as shown in the image below. (Open image in new tab for a bigger image)
Admin user name and password will be used by Statsig to create a user with restricted access to query from your data warehouse.
## SSH Tunneling
For Redshift connections, we also allow users to create an SSH tunnel into their Redshift cluster for a more secure and private access to the database.
To enable access, Statsig requires:
* SSH Host
* SSH Port
* SSH User
Statsig will use this information to generate an SSH key. Please add this generated key to your `~/.ssh/authorized_keys` file on your SSH proxy machine to enable SSH tunneling.
### Custom User Privileges
To create a custom user with specific privileges instead of using an admin user, run the following code in your Redshift cluster with your admin user.
Replace `` and `` with your value, which you will copy over into our console.
```sql theme={null}
# Create Statsig User
CREATE USER WITH PASSWORD SYSLOG ACCESS UNRESTRICTED;
# Give access to any Schemas that the Statsig User needs to read from
GRANT USAGE ON SCHEMA to ;
GRANT SELECT ON ALL TABLES IN SCHEMA to ;
# Create a Schema for Statsig User to write temporary data to
CREATE SCHEMA IF NOT EXISTS statsig_ingestion_staging;
GRANT ALL ON SCHEMA TO ;
```
After running the script, input the `` and `` you created in our console, during Connection Set Up stage under the Advanced settings options.
Admin user name and password will be used by Statsig to create a user with restricted access to query from your data warehouse. If you don't want to use this, skip ahead [here](/data-warehouse-ingestion/snowflake#custom-user-privileges)
### Account Name
For the Account Name field, please enter in the format of `..`. So, your information may look something like this:
`xy12345.us-central1.gcp`
To get this information navigate to bottom left in your Snowflake console, as shown in the picture below and copy the link URL:
Using `-` for Account Name
For the Account Name field, you can also enter your Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#format-1-preferred-account-name-in-your-organization), which typically takes the form `-`. To find the `` in the Snowflake console, click on your account profile (usually at the bottom left) to view account details as shown below.
### Database and Schema Name
For each data type, provide the database/schema of the table(s) you will be ingesting from.
` and `` with your value, which you will copy over into our console.
```sql theme={null}
BEGIN;
-- set up variable values to be used in statements later
-- make sure to configure user_name and user_password with your own values
SET user_name = ''; -- REPLACE WITH YOUR OWN VALUE
SET user_password = ''; -- REPLACE WITH YOUR OWN VALUE
SET role_name = 'STATSIG_ROLE'; -- CAN BE ANYTHING, BUT THE USER NEEDS TO
-- HAVE THIS ROLE AND THE ROLE NEEDS ACCESS TO THE TABLES PER THE GRANTS BELOW
-- change role to sysadmin for warehouse / database steps
USE ROLE sysadmin;
-- create a warehouse, database, schema and tables for Statsig
CREATE OR REPLACE WAREHOUSE STATSIG_INGESTION WITH warehouse_size='XSMALL';
CREATE DATABASE IF NOT EXISTS STATSIG_STAGING;
-- change current role to securityadmin to create role and user for Statsig's access
USE ROLE securityadmin;
-- create role for Statsig
CREATE ROLE IF NOT EXISTS identifier($role_name);
GRANT ROLE identifier($role_name) TO ROLE SYSADMIN;
-- create a user for Statsig
CREATE USER IF NOT EXISTS identifier($user_name)
password = $user_password
default_role = $role_name
default_warehouse = STATSIG_INGESTION;
GRANT ROLE identifier($role_name) TO USER identifier($user_name);
-- grant Statsig role access to create warehouse and schema
GRANT USAGE ON WAREHOUSE STATSIG_INGESTION TO ROLE identifier($role_name);
GRANT CREATE SCHEMA, MONITOR, USAGE ON DATABASE STATSIG_STAGING TO ROLE identifier($role_name);
-- grant Statsig role read access to database and schema passed in
GRANT USAGE ON DATABASE TO ROLE identifier($role_name);
GRANT USAGE ON SCHEMA . TO ROLE identifier($role_name);
GRANT SELECT ON ALL TABLES IN DATABASE TO ROLE identifier($role_name);
GRANT SELECT ON FUTURE TABLES IN DATABASE TO ROLE identifier($role_name);
GRANT SELECT ON ALL VIEWS IN DATABASE TO ROLE identifier($role_name);
GRANT SELECT ON FUTURE VIEWS IN DATABASE ACTUAL_DATA TO ROLE identifier($role_name);
COMMIT;
```
After running the script, input the `` and `` you created in our console, during Connection Set Up stage under the Advanced settings options.
Admin user name and password will be used by Statsig to create a user with restricted access to query from your data warehouse.
You can find this information in your Azure console within your Synapse workspace overview page, as shown in the image below. (Open image in new tab for a bigger image)
Schemas are only enforced when editing dynamic configs through the console or API, and are not used at code runtime.
For example, if you have a dynamic config that returns settings for a site banner, you might have a schema of:
```
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"title": {
"type": "string",
},
"description": {
"type": "string",
},
"cta": {
"type": "string",
}
},
"required": ["title", "description", "cta"],
}
```
Now, each of your rules must return an object including title, description, and CTA.
## Infer schema from current values
You can also infer schema based on the current values in your targeting rule variations. This is useful as a quick starting point for validations or for documenting the expected shape of your config.
Sequential testing can be used anywhere you do an experimental analysis. This includes your main experimental Results page as well as any [custom queries](/pulse/custom-queries/).
## Quick Guides
### Enabling Sequential Testing Results
In the **Setup** tab of your experiment, with Frequentist selected as your Analytics Type, you can enable Sequential Testing under the Analysis Settings section. This setting can be toggled at any time during the life of the experiment, and it does not need to be enabled prior to the start of the experiment.
An LR of 5.8, for example, indicates that the what you observed is 5.8x more likely under the alternative hypothesis as compared to the null hypothesis.
One of the nice things about SPRT is that this Likelihood Ratio is similar to how most people think about comparing options. Rather than reporting P-values and Significance levels, you can now report a result like "*With an LR of 3.5, it's 3.5x more likely that the feature worked*."
## Why SPRT?
* **Faster Decisions:** SPRT allows you to reach conclusions more quickly, potentially reducing experiment run time.
* **Intuitive Results:** Instead of p-values, SPRT uses the Likelihood Ratio, a more intuitive measure of evidence for or against your hypotheses.
* **Sequential Analysis:** Data is continuously evaluated as it is collected, allowing for early stopping when sufficient evidence is reached. There's no penalty for "peeking" in SPRT experiments.
* **Clear Outcomes:** SPRT enables you to confidently accept either the Null or Alternative hypothesis, rather than just “rejecting the null.”
* **Data-Informed:** Statsig’s implementation uses your past data and power analysis to inform the likelihood calculations and decision thresholds.
## Comparing SPRT to other analysis methods
| Category | Frequentist | Bayesian | SPRT |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Test Statistic | P-value:
While you can add overrides for an ID type that is different than the ID type of the experiment, those ID evaluations will not be resolved to the id type of the experiment and will not contribute to pulse results.
When you use the Statsig SDK for assignment, it takes care of randomization. When you control assignment of users, you're responsible for making sure users are balanced across experiment groups.
Metrics and experiments behave differently in Warehouse Native. Read about [Configuring Experiments in Warehouse Native](/statsig-warehouse-native/features/experiment-options).
This doc walks through the steps of creating a new experiment in the Statsig console. If you're looking for an end-to-end guide that includes integrating the Statsig SDK, see [Run your first experiment](/guides/abn-tests).
## User-level Experiments
To create a user-level experiment, follow these steps:
1. Log into the Statsig console at [https://console.statsig.com/](https://console.statsig.com/)
2. Navigate to **Experiments** in the left-hand navigation panel
3. Click on the **Create** button
4. Enter the name and description for your experiment as shown in the figure below
5. By default, your experiment runs in its own **Layer**. A Layer allows you to manage multiple experiments and feature flags together. If you want to add this experiment to an existing Layer, select **Add Layer** under **Advanced** in the experiment creation modal. You can also create a new Layer by selecting **Create New Layer**.
6. Click **Create**
**Shipping with Targeting On**
If you decide to continue targeting, shipping a group will not update the default value of any layer parameters.
For example, suppose **Demo Experiment** in a **Demo Layer** that has a parameter called **targeted\_layer\_param**, whose default value is set to
*targeted\_layer\_default\_value*.
When you decide to ship **Demo Experiment**, if you discontinue targeting,
**targeted\_layer\_param** will now take on the value from the **Control** group, *targeted\_layer\_control*, as its default.
Rollout times are available in 15 minute increments. Additionally, each configured phase represents a discrete increase to the next rollout percentage, not a gradual rollout amortized over the course of the entire phase.
Upon saving, you will be able to see a preview of the rollout and commit the schedule:
This is currently a beta feature.
## Shipping with a Holdback
Shipping with holdback lets you release an experiment variant (the “shipped” group) to most of your users while keeping a percentage in the control group for ongoing comparisons. Here’s how it works:
1. Make a decision and select a group to ship: From the Make Decision dropdown, choose which variant you want to ship.
2. Turn on the Ship with holdback option and specify the percentage of users you want to keep in the control (holdback) group.
Some users currently in control will move to the shipped group to achieve the desired allocation.
However, any user who has previously been in a test or shipped group will not be reassigned to control.
New users—those who have never been exposed to the experiment will be assigned based on the allocation percentages of each group.
Note that the new pulse results (Test segment vs. Holdback) will start when you ship with holdback, but your original experiment's results from the point of holdback decision will be retained and remain available to you.
From the history of experiment, you will see the new log of experiment decision and a 'View Results Snapshot' button where you can view the read-only snapshot of original results.
This is currently a beta feature.
# Stop Assignments
Source: https://docs.statsig.com/experiments/ending/stop-assignments
Stop enrolling new users into a Statsig experiment while continuing to analyze existing users so results stabilize before making a launch decision.
## Stopping New User Assignments in an Experiment
You have been running an experiment for a while. Your users are split across various control and treatment groups. But now you want to stop enrolling more users into your experiment and going forward analyze only the users who have been exposed thus far.
With the Stop Assignment option, you can do exactly that.
You will need to configure [Persistent Assignment](/server/concepts/persistent_assignment) for this feature to work. If you don't configure this, people already exposed to the treatment groups will no longer get the treatment experience. Persistent Assignment is required even if you use stable identifiers.
## What Stop Assignment Does
* Sets experiment allocation to 0% - no new users will be enrolled in the experiment
* Preserves existing user assignments - users already exposed continue to receive their control or treatment experience (only if Persistent Assignment is configured)
* New users will not be checked against the experiment and instead get the project’s default experience. To ship a specific variant to all new users, make a decision on the experiment or set this in code.
## Enabling Stop Assignment Option
The **Stop Assignment** option must first be enabled in Project Settings to show as an option in the **Make Decision** modal. To enable this option, head to **Settings** --> **Project Info** and toggle on the **Enable stop new user assignments for experiments** setting.
When an experiment includes more than two groups, interaction effects are evaluated **pairwise between groups**. You can view the interaction effect for specific group combinations by selecting the desired groups in the **“Select Comparison”** dropdown, as shown in the UI above.
# Meta-Analysis
Source: https://docs.statsig.com/experiments/exploring-results/meta-analysis
Combine results from multiple Statsig experiments into a meta-analysis to evaluate the overall impact of a series of related A/B tests over time.
## The Concept
As teams run a number of experiments, it is possible to glean learning across these experiments. This is meta-analysis. Examples of learning people seek to derive include
* How hard is a metric to move
* Are there more sensitive proxies for the metric we care about?
* How are teams doing relative to each other?
We've worked with multiple companies to get them to thousands of trustworthy experiments a year. Our inspiration here was looking at what they were trying to learn across these tests. We've built this to be useful whether you're running 50 experiments a year or 5000. Feel free to reach out to help influence our roadmap in [Slack](https://statsig.com/slack).
## Experiment Timeline View
This view lets you to filter down to experiments a team has run. At a glance you can answer questions like
1. What experiments are running now?
2. When are they expected to end?
3. What % of experiments ship Control vs Test?
4. What is the typical duration?
5. Do experiments run for their planned duration - or much longer or shorter?
6. Do experiments impact key business metrics - or only shallow or team level metrics?
7. How much do they impact key business metrics?
Holdouts can only be applied to Experiments and Feature Gates that use the same randomization unit.
If a team plans to run experiments on both User ID and Stable ID, two separate holdouts are required to evaluate the cumulative impact of each type of experiment.
When you ship an experiment in a layer - this would normally update the layer defaults, however, users in the holdout will *not* see those defaults, with the layer instead having a new set of default parameters just for held-out users:
We keep showing the group and logging exposures so that you can verify that the user experiences have recovered after the group was disabled.
### How To
* Log into the Statsig console at [https://console.statsig.com](https://console.statsig.com)
* On the left-hand navigation panel, select **Experiments**
* Select the experiment where you want to disable a group
* Click on the **...** menu in the top right corner
* Select the **Disable A Group** option
* Select the experiment groups you would like to disable, and hit **Confirm**
Be mindful that users in any reenabled group might have experienced multiple treatment experiences over the course of the experience. This may be reflected in the metric data collected for the group.
# Getting the Group
Source: https://docs.statsig.com/experiments/implementation/getting-group
Why you should read Statsig experiment parameters in code instead of checking group names, with examples for cleaner, more maintainable implementations.
One common misconception when working with experiments on Statsig is trying to check the experiment group in code. Checking the experiment group *in code* is actually an anti-pattern. It's not necessary with Statsig, and it will limit your ability to quickly test different variants.
Experiment groups are very useful for understanding what a set of parameters represents in the Statsig console. Comparing "Sorted Long List" vs "Default Search Results"
is easier to discuss than trying to understand what the `sorted = true, length = 10` parameters represent.
That being said, in code, its much more powerful to directly check parameters and their values. It's also simpler to reason about: rather than hard
coding in a particular value, your variable is dynamically evaluated by Statsig. In this way, parameters are the building blocks of your experiments when coding, rather than group names.
### Example: Group Names vs Parameters
Hard coding experiment group names would be both very fragile and very limiting. Let's see why.
In code, if you tried to use experiment groups, your function might end up looking like this:
```ts theme={null}
async function getSearchItems(user: StatsigUser, searchTerm: String): String[] {
const results = index.get(searchTerm);
const experiment = statsig.getExperimentSync(user, 'search_results');
// NOTE - these APIs don't actually exist - this is for the sake of an example
if (experiment.groupName === 'Sorted Long List') {
return results.sort().slice(10);
} else if (experiment.groupName === 'Sorted Short List') {
return results.sort().slice(3);
} else {
return results;
}
}
```
There are a few problems with this code:
1. Its very fragile. If the group name in code does not match the name in the Statsig console, you won't return the correct experience
2. Its static. I can't easily add another experiment group without changing the code. I can't add an "Unsorted long list" without a code change.
So instead, this is what the code would look like using experiment parameters directly:
```ts theme={null}
async function getSearchItems(user: StatsigUser, searchTerm: String): String[] {
let results = index.get(searchTerm);
const experiment = statsig.getExperimentSync(user, 'search_results');
results = experiment.get("sorted", false) ? results.sort() : results;
const numItems = experiment.get("length", 0);
return numItems > 0 ? results.slice(numItems) : results;
}
```
Now, your code is completely decoupled from the names of experiment groups in the statsig console. You are left with a set of dynamic parameters.
You can create whichever experiment groups you want out of these building blocks, and the same code will work. Want to test an unsorted list of 5 items
against a sorted list of 20 items? Just set it up in the Statsig console (and name it whatever you want).
If you were trying to check group names, you would have to go back and add conditions like:
```ts theme={null}
} else if (experiment.groupName === 'Unsorted Short List') {
return results.slice(5);
} else if (experiment.groupName === 'XL Sorted List') {
return results.sort().slice(20);
}
```
As you can see, using parameters directly when you are coding is much simpler and more flexible. It makes your code dynamic and offloads experimentation setup to the Statsig console. The group names you configure to describe each set of parameters will make it easy to compare one group against the other when it's time to analyze the results of your experiment.
## Rules
The diagnostics stream is meant to be used for debugging your integration, and understanding which groups a user is being bucketed into. The following defines the different Rules you will see, and what they mean.
| Rule | Meaning |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Not started | The experiment has not been started, so the allocation groups are not determined yet |
| Holdout | The user is in a holdout that this experiment references, so they are not in the experiment |
| Layer Assignment | The user is not allocated to this experiment because they are bucketed to a different part of the Layer |
| Targeting Gate/Inline Targeting | The user does not meet the requirements for the targeting gate or inline targeting |
| Not Allocated | The user is not allocated to this experiment because they do not meet the rollout % |
| \{group name}\{override name} | The user was forcefully bucketed into a given group by an experiment override |
| \{group name} | The user was bucketed into this experiment group |
| Abandoned | "Make Decision" selected the control group. This experiment has been abandoned. |
| \{group name} (Launched) | "Make Decision" selected this group as the launch group, so the user is seeing the launched experience. |
# Implement an Experiment
Source: https://docs.statsig.com/experiments/implementation/implement
Deploy a Statsig experiment in your code: pull configurations from the SDK, log exposure events, test variants locally, and launch to production users.
To deploy an experiment, you'll need to:
1. Pull the experiment configurations in your application
2. Log the events you'll want in your experiment results
3. Test your experiment in development or a lower environment
4. Click "Start"!
Every experiment needs to expose users into more than one bucket (#1) and log metrics on their behavior after exposure (#2, called "log events"). Statsig automates many of the annoying parts of setting up an experiment, like writing the code you can use to assign buckets, and conducting analysis on the exposures and log events. The experimenter's job is to devise the experiments - and use our SDKs to accomplish #1 and #2.
## Pulling experiment configurations from Statsig
In the code snippets below, we illustrate experimenting on a product demo flow, where you might experiment to improve conversion through the funnel to demo completion. For full implementation details, check out the [SDK documentation](/sdks/getting-started) for the language you'll be using, or walkthrough our example guide for [your first a/b test](/guides/abn-tests).
```js theme={null}
const user = { userID: loggedInUserID };
const demoConfiguration = statsig.getExperiment(user, "demo_experience");
// use parameters to control the experience
if (demoConfiguration.get("show_banner", false) {
showBanner();
}
const title = demoConfiguration.get("title", "Start Demo");
banner.setTitle(title);
```
You can also look at a code snippet for your particular experiment by clicking into the code snippet button on the experiment page and selecting the right SDK
_first_exposures.csv` - contains a list of users and their first exposure to the experiment.
2. Pulse Summary - This provides precomputed summary experimental data for all metrics and test groups including everything that's visible on Pulse (**around 10-100 kb**). This will contain:
1. `_pulse_summary.csv` - contains Pulse aggregate metrics computed over the duration of the experiment.
3. Raw Data - This provides raw exposures and metrics data at the user-day level. This is best used for manually inspecting data, or recomputing your own statistics (**around 10MB-1GB**). This will contain:
1. `_first_exposures.csv` - contains a list of users and their first exposure to the experiment. If this is the only file you are interested in, you can get this by exporting an "Exposures" report which will be much smaller in size.
2. `_user_metrics.csv` - contains a list of experimental users, and their calculated metrics for each day they were enrolled in the experiment.
In WHN, only the Pulse Summary may be exported, as the other two types of data are only stored [in your warehouse](/statsig-warehouse-native/pipeline-overview/#artifacts-and-entity-relationships). The availability of these exports are subject to our retention policy. We hold exposures data for up-to 90 days after an experiment is concluded. We hold raw user-level metrics data for 90 days.
### Pulse Summary File Description - For Feature Gates
| Column Name | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | Name of the Experiment or Feature Gate |
| rule | Name of the Feature Gate Rule. |
| metric\_type | Category of the metric. Different metric\_types are computed differently, including how they're computed in Pulse. |
| metric\_name | The name of the metric. For event metrics, this is the name of the event. |
| metric\_dimension | The subcategory of the metric. For example, if you log value in LogEvent, then value will show up as a subdimension. dimension = !statsig\_topline indicates that this row reflects an aggregate across all dimensions. |
| start\_date | The start date for this measurement |
| end\_date | The end date for this measurement |
| test\_units | The number of users in the test group |
| test\_mean | The average value of this metric across test users (or participating units when applicable) |
| test\_stderr | The standard error for the estimate of the mean for test users. This can be used to compute confidence intervals. |
| ctrl\_units | The number of users in the control group |
| ctrl\_mean | The average value of this metric across control users (or participating units when applicable) |
| ctrl\_stderr | The standard error for the estimate of the mean for control users. This can be used to compute confidence intervals. |
| abs\_delta | The absolute difference between the test and control mean (test\_mean - ctrl\_mean) |
| abs\_stderr | The estimated standard error of abs\_delta |
| rel\_delta | The relative difference between test and control mean, sometimes referred to as lift (test\_mean - ctrl\_mean)/ctrl\_mean |
| rel\_stderr | The estimated standard error of rel\_delta (abs\_delta/ctrl\_mean) |
| z\_score | The calculated Z-score |
### Pulse Summary File Description - For Experiments
| Column Name | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | Name of the Experiment or Feature Gate |
| rule | Name of the Feature Gate Rule. |
| experiment\_group | The group of users for which this metric is computed for. For a feature gate, this is pass/fail. For an experiment, this is the variant name. |
| metric\_type | Category of the metric. Different metric\_types are computed differently, including how they're computed in Pulse. |
| metric\_name | The name of the metric. For event metrics, this is the name of the event. |
| metric\_dimension | The subcategory of the metric. For example, if you log value in LogEvent, then value will show up as a subdimension. dimension = !statsig\_topline indicates that this row reflects an aggregate across all dimensions. |
| start\_date | The start date for this measurement |
| end\_date | The end date for this measurement |
| units | The number of users included in this metric estimate. |
| mean | The average value of this metric across units (or participating units when applicable) |
| stderr | The standard error for the estimate of the mean. This can be used to compute confidence intervals. |
### First Exposures File Description
| Column Name | Description |
| -------------------------- | --------------------------------------------------------------------------------------------- |
| unit\_id | Refers to the unit identifier used in the experiment (eg. user\_id, stable\_id, org\_id) |
| name | The name of the gate/experiment |
| rule | For gates, this refers to the rule name |
| experiment\_group | The group the user was assigned to |
| first\_exposure\_utc | The UTC timestamp when the user was first assigned to the experiment |
| first\_exposure\_pst\_date | The date in PST when the user was first assigned to the experiment |
| as\_of\_pst\_date | The date this data was generated |
| user\_dimensions | JSON-formatted key-value pairs describing the user's attributes at the time of first exposure |
### Unit Metrics File Description
| Column Name | Description |
| ----------------- | -------------------------------------------------------------------------------------------- |
| pst\_ds | The 24hr window the data refers to. All dates are anchored from 12:00a -> 11:59p PST. |
| unit\_id | Refers to the unit identifier used in the experiment (eg. user\_id, stable\_id, org\_id) |
| metric\_type | The category of the metric |
| metric\_name | The name of the metric |
| metric\_dimension | The name of the metric dimension. '!statsig\_topline' is the overall metric with no slicing. |
| metric\_value | The numeric value of the metric |
| numerator | For some metrics, we track the numerator |
| denominator | For some metrics, we track the denominator |
# Best Practices and Avoiding False Positives
Source: https://docs.statsig.com/experiments/interpreting-results/best-practices
Best practices for interpreting Statsig experiment results, including avoiding common biases, reading lift correctly, and trusting statistical significance.
We have some suggestions on how to interpret Pulse in a scientifically-sound way:
1. Have a hypothesis in mind before viewing Pulse. What are the metric(s) you expect to shift due to the change you made? What else could have happened? What are signs it has gone wrong?
2. Establish a small set of key metrics that are directly related to your hypothesis and would most directly establish that the experiment worked. Having more than a handful of key metrics is usually a sign of an ill-defined hypothesis or shotgun experimentation. Examining too many metrics will lead to a higher false positive rate (seeing results when only statistical noise exists).
3. Avoid cherry-picking results. For example, don't selectively pick three metrics that look good, but ignore the two that don't. Also avoid picking "good" or "bad" numbers that have no connection to your hypothesis. Context matters a lot, and statistically-significant results should have a plausible explanation (false positive can be a plausible explanation).
4. Seeing multiple (independent) effects that are consistent with a plausible story lends credibility that the observed effects are real, even with borderline p-values.
5. Expect to see false positives and be suspicious of statistically significant results with borderline p-values. For example, a 95% confidence interval (5% significance level) is expected to turn up one statistically significant metric out of twenty due purely to random chance. This number goes up if you start to include borderline metrics (eg. p = 0.06).
6. Look beyond your hypothesis. What other effects can you find? Are there tradeoffs? Are there unexpected behaviors? These can reveal information about your users and how they interact with your product. They are often the source of follow-up experiments and new ideas.
# Custom "Explore" Queries
Source: https://docs.statsig.com/experiments/interpreting-results/custom-queries
Run custom queries on Statsig experiment results to explore segments, joins, and aggregations beyond the built-in scorecard and drill-down views.
Custom queries are a way to run additional custom experiment analyses on your existing data beyond what is in your main Results tab. You may run them to gain deeper insights from your experiments and feature roll-outs, debug interesting results, or scope down your results to interesting sub-groups. Custom queries allow you to filter or group metrics by event or user dimensions, or filter to a specific set of users to see how an experiment or launch has impacted these users' experience.
Custom queries are experimental analyses just like in the main Results tab, and all the same statistical procedures apply. Results are computed as p-values and confidence intervals for your metric deltas, and advanced statistical methods like [CUPED](/stats-engine/methodologies/cuped) and [Sequential Testing](/experiments-plus/sequential-testing) can be used.
Be careful when drawing your inferences of Custom Queries, especially when grouping by a dimension with lots of options. This can increase your chance of seeing a false-positive statistically significant result.
### Dimension Loading Timing for Precomputed User Dimensions
When viewing results for precomputed user dimensions (which are configured and run on a schedule), be aware that these dimensions are loaded through separate asynchronous explore queries. This means:
* The main experiment results will appear first
* Precomputed dimensions will continue loading in the background and become available within a few minutes
* This timing gap is most noticeable immediately after the first reload of the day
* If you see "No dimensions available for this time range" for precomputed dimensions, wait a few minutes and refresh to see if dimensions have completed loading
This timing behavior only affects precomputed user dimensions that run on a schedule. User-triggered custom queries do not experience this asynchronous loading delay.
### Running a Custom Query
To run a Custom Query, navigate to the **Explore** tab within your experiment.
User groups in experiment results are based off of first-touch attribution. The filters and grouping applied will be based on the user attributes collected at the time of first exposure in the gate/experiment/layer check.
**Warehouse Native users**: You're viewing the Cloud docs for this page. Metrics and experiments behave differently in Warehouse Native. Read [How to Access Pulse Data in Warehouse Native](/pulse/access-whn).
You should **not** make any experiment decisions based on real-time results data in this first 24 hour window after experiment start. Experiments should only be called once the experiment has hit target duration, as set by your primary metric(s) hitting experimental power.
Read more about target duration [here](/experiments-plus/create-new#target-duration).
Given data during this early post-experiment start window is designed for diagnostic, not decision-making purposes, you will notice a few key differences between this real-time view and the results that will start showing after daily runs have initiated:
* Metric lifts do not have confidence intervals
* No time-series view of metric trends
* No projected topline impact analysis
* No option to apply more advanced statistical tactics, such as CUPED or Sequential Testing
All of these are available in daily Results, which will start showing in the next daily run.
#### Post-first Day Scorecard
This experiment result calculation window only affects whether a user is included in the experiment's analysis, and does not affect the treatment each user would receive. New users would still receive the experience for the group they get randomized into.
### Experiment Results Views
There are a few different views to see your Scorecard metric lifts, namely:
* **Cumulative results (default view)**: Displays the aggregate difference between experiment groups and visualizes the corresponding confidence intervals
* **Table view**: Displays the same data as the cumulative view but in a table format with additional fields
* **Daily results**: Shows the difference between experiment groups aggregated based on days since start of experiment
* **Days since exposure**: Shows the difference between experiment groups aggregated based on days since exposure to the experiment
Cumulative results includes a detailed view on hover, where you can additionally view the raw statistics used in the metric lift calculations, as well as topline impact.
GROUP BY
unit_id,
experiment_id,
group_id
HAVING COUNT(distinct group_id) = 1;
```
### Data Availability
When comparing a platform analysis to an **existing** experiment analysis that may have been run in the past, it's possible that the underlying data has since fallen out of retention or has been otherwise deleted. To check this, you can compare the table's retention policy to the analysis dates used in your original experiment analysis to make sure the data still exists.
Additionally, you should make sure your experiment in the vendor console is configured to analyze the same time range your original analysis used.
### Validation
The validation procedure for the initial metric data and join is to use the query provided in [Timestamps](/experiments-plus/reconciling-experiment-results#timestamps) section, modifying it to run on both platforms to evaluate that a target metric has the same totals per group across both platforms.
Warehouse Native platforms have an advantage here in that the SQL dialect and source data will generally be the same in both Vendor code and in your in-house code, making comparisons simpler.
We recommend picking one metric of interest, validating this data, and resolving any differences before checking in on Statistical/Metric methodologies.
## Statistical Features
Choices in statistical methodologies can significantly impact experiment results. The following are common root-causes for gaps in results, but we always recommend that users closely read the queries being run by the vendor to understand any particulars in methodology.
### Winsorization
Outlier trimming, or [Winsorization](https://docs.statsig.com/stats-engine/methodologies/winsorization/), can dramatically alter experiment outcomes. Turning off this feature in Statsig metrics is advisable when doing cross-system comparisons unless it is being manually applied.
### CUPED
[CUPED](https://docs.statsig.com/stats-engine/methodologies/cuped/) can significantly change variances and observed deltas, especially with high pre- and post-exposure data correlation and/or systematic differences in groups' pre-experiment data.
CUPED can be configured at a metric level, but you have the option to turn it off for a pulse result set after running analysis.
### Ratio Metrics
For ratio metrics using the delta method, only units with a non-zero denominator are included, affecting the analysis's comprehensiveness. Additionally, Statsig calculates ratios and means as
$\bar{u} = \frac{\sum_{i=0}^{n}(numerator_i)}{\sum_{i=0}^{n}(denominator_i)}$
and uses the [delta method](https://docs.statsig.com/stats-engine/variance/#ratio-and-mean-metrics) to correct for the cluster-based nature of these metrics.
## Metrics
Often, users misunderstand how a given metric is calculated. We have a comprehensive [guide in our documentation](https://docs.statsig.com/statsig-warehouse-native/configuration/metrics) with more details.
## Conclusion
Following this steps should yield an understanding of where gaps - if any - are coming from between two experiment platforms. Statsig puts a high emphasis on providing the intermediate and result datasets it uses, as well as the queries used in its analysis. This should make it easy in practice to understand where gaps arise.
All that said, this can be tricky - please feel free to reach out if you get stuck, and we'll be happy to help. We'd also suggest looking at the [Statsig Warehouse Native Documentation](https://docs.statsig.com/statsig-warehouse-native/introduction) and [Statsig Pipeline Overview](https://docs.statsig.com/statsig-warehouse-native/pipeline-overview/) for an overview of experiment pipeline patterns.
# Slicing by User Properties
Source: https://docs.statsig.com/experiments/interpreting-results/userproperties
Break down Statsig experiment results by user properties like country, platform, or subscription tier to identify heterogeneous treatment effects.
Statsig let's you slice results by user properties. Common examples of doing this include breaking down results by user's home country, subscription status or engagement level.
Even though layered experiments remain technically accessible via `getExperiment`, that API evaluates only the current experiment. Use `getLayer` so the SDK honors layer-level decisions, mutual exclusion, and shared parameters.
## A Word on Exposures
Calling `getLayer(LayerName)` by itself does not log an exposure. A `statsig::layer_exposure` event is logged when you access a specific parameter within the Layer using `getLayer(LayerName).get(Parameter)`.
* If the user is assigned to an experiment within the Layer, the `statsig::layer_exposure` event is billable.
* If the user is not assigned to an experiment within the Layer, the `statsig::layer_exposure` event is not billable.
Repeated reads of the same Layer parameter for the same user within the deduplication window may count as a single billable exposure.
Reads of different Layer parameters may count separately.
# Monitor an Experiment
Source: https://docs.statsig.com/experiments/monitor
Track health checks, exposure counts, and diagnostics for active Statsig experiments to catch sample ratio mismatch and instrumentation issues early.
Once an experiment launches you can monitor its health and exposure mix directly from the Statsig console.
## Experiment Health Checks
1. Open **Experiments** from the navigation.
2. Select the experiment you want to inspect.
3. Review the **Experiment Health Checks** banner at the top of the scorecard.
test * and *Ncontrol * are the estimated number of users in the test and control group. These are based on historical active user data along with experiment allocation and group size.
* *Z1-β * is the standard Z-score for the selected power. Typically *1-β = 0.8* and *Z1-β = 0.84*
* *Z1-α/2 * is the standard Z-score for the selected significance level in a 2-sided test. Typically *α = 0.05* and *Z1-α/2 = 1.96*
This calculation relies on statistics computed across the entire user base of the project. It does not account for the fact that experiments targeting only a subset of users may have different summary statistics for their key metrics.
For example, the metric mean and variance can be different in an experiment that targets only Android users or one that exposes users at the lower part of an acquisition funnel.
# Experiment Overrides
Source: https://docs.statsig.com/experiments/setup/overrides
Override Statsig experiment group allocation for specific users or environments during development and QA, so testers see a chosen variant deterministically.
## Override group allocation for an Experiment
During development, it can be useful to explicitly state which experiment group a user should fall into. For example, if a developer is testing that each of the experiment conditions work as expected, they may want to force themselves into each of the different conditions to test.
Overrides can be added based on Feature Gates and Segments, and will allow you to create rules that force all users that pass a given Feature Gate or Segment to be allocated to a given group. When fetching parameters for an experiment, if the user matches any of the overrides, the overridden result will be returned immediately.
**Note**:
* For Experiments that are in a Layer, the overrides must be set at the Layer level. A user can only be overridden into one Experiment within that Layer (since layers always make experiments within them mutually exclusive).
* It is best to add overrides to your experiment before it starts or at least before a user's first exposure. Users whose first exposures are controlled by overrides are excluded from Pulse results. Since these users are not randomized, we purposely exclude them from experimental results. Adding a large number of users to the override can affect the reliability of your experimental results.
* **Warning**: if you add overrides after a user has already been exposed in an experiment, that user will not be excluded from Pulse results. That user's events and metrics will continue to be attributed to the group they were first assigned to. However, the override will be applied and honored once you define it. This can cause your experiment results to be diluted or polluted since the user's actions may be attributed to one group while they were actually exposed to a different group. The overall impact from this issue will depend on how many users fall into this category.
* ID Overrides are evaluated first, then conditional overrides (from top to bottom).
* ID type used for ID Overrides may or may not match the experiment’s ID type.
CURE by Statsig .
## CUPED for Simple Aggregations
The methodology for simple aggregations is described in the original [Microsoft paper](https://www.exp-platform.com/Documents/2013-02-CUPED-ImprovingSensitivityOfControlledExperiments.pdf), as well as our in-depth [article](https://www.statsig.com/blog/cuped) on the technique.
The Cloud product uses stratification alongside CUPED to account for users who may not have pre-experiment data. Users are grouped into strata based on available pre-experimentation information. Treatment and control effects are first estimated within each stratum, then aggregated to produce an overall result. We then apply the standard difference-in-means and variance estimation. This approach allows us to retain users with missing pre-data while still benefiting from variance reduction where applicable.
## CUPED for Ratio Metrics
The Microsoft paper also gives details on how to implement CUPED for those with a different analysis unit (Appendix B). On Statsig, we extend it to work for our ratio metrics, where each experiment unit is represented by a numerator and a denominator. The variance reduction process is performed by finding the variance of experiment data, pre-experiment data, and the covariance between the two.
Denote the numerator, denominator, pre-experiment numerator, and pre-experiment denominator of a unit as $Y$, $N$, $X$, and $M$, respectively. Using the CUPED-reduced variance formula,
$$
Var(\frac{Y_{cv}}{N_{cv}})=Var(\frac{Y}{N})+\theta^2 Var(\frac{X}{M})-2\theta Cov(\frac{Y}{N}, \frac{X}{M})
$$
where optimal $\theta$ is found as
$$
\frac{Cov(\frac{Y}{N}, \frac{X}{M})}{Var(\frac{X}{M})}
$$
expanded to
\\
$$
\frac{Cov(\frac{Y}{\mu_N}-\frac{\mu_Y N}{\mu^2_N}, \frac{X}{\mu_M}-\frac{\mu_X M}{\mu^2_M})}{Var(\frac{X}{\mu_M}-\frac{\mu_X M}{\mu^2_M})}
$$
At this point, we have
$$
\frac{\hat{Y_{c}}}{\hat{N_{c}}}=\frac{Y_{c}}{N_{c}}-\theta( \frac{X_{c}}{M_{c}} - \mathbb{E}[R])
$$
$$
\frac{\hat{Y_{t}}}{\hat{N_{t}}}=\frac{Y_{t}}{N_{t}}-\theta( \frac{X_{t}}{M_{t}} - \mathbb{E}[R])
$$
While $\mathbb{E}[R]$ is hard to deduct, we recognized that the expectation term is the same for both group. We decided to substitute $\mathbb{E}[R]$ with $\frac{X_{c}}{M_{c}}$ so the formulas above are transformed to these following two:
$$
\frac{Y_{cv}(control)}{N_{cv}(control)}=\frac{Y(control)}{N(control)}
$$
$$
\frac{Y_{cv}(test)}{N_{cv}(test)} \\
:=\frac{Y(control)}{N(control)} - (\frac{Y(control)}{N(control)} - \theta \frac{X(control)}{M(control)}) + (\frac{Y(test)}{N(test)} - \theta\frac{X(test)}{M(test)}) \\
:=\frac{Y(test)}{N(test)} - \theta\frac{X(test)}{M(test)} + \theta \frac{X(control)}{M(control)}
$$
Using the optimal $\theta$, we are hoping to reduce group-level variance by plugging the parameter back in to calculate the adjustment. Please note that across-group $\theta$ does not necessarily reduce variance for one group, or the sum of variances of all groups, but in most cases it does. Our simulation shows that 98.3% of metrics saw a decrease by CUPED.
Statsig will use CUPED variance when all of the following are met:
* Core assumptions of the CUPED model are satisfied; this can be violated due to rounding error or other data artifacts
* E(X\_hat) = E(X)
* The pooled variance of the adjusted population across groups is \< the variance of the unadjusted population
* Enough units have pre-experiment values (> 100)
* Enough percentage of units have pre-experiment values (> 5%)
# Delta Method
Source: https://docs.statsig.com/experiments/statistical-methods/methodologies/delta-method
How Statsig applies the delta method to compute variances for ratio metrics and other non-linear functions of user-level metric values in experiments.
## Delta Method for Ratio Metics
Statsig uses the delta method when calculating the variance for variables that have a numerator and denominator.
The variance of ratio and mean metrics depends upon the numerator and denominator variables, which are typically correlated. For example, consider a *clicks per session* metric. The number of clicks and the number of sessions are two sets of observations coming from the same group of users, so they are not independent from each other. To properly account for this correlation, the variance of a ratio metric *R* is obtained using the delta method:
One-sided tests completely disregard the possibility of detecting the metric moving in the direction that isn't specified, but they give you higher sensitivity in the direction you are looking (which allots all your alpha to testing statistical significance in the one direction of interest). This results in one-sided confidence intervals (CIs) that are narrower in the direction of interest than their two-sided counterparts.
## How to enable this
When setting up an experiment and identifying metrics to measure, the default setting is to run a two-sided test. If you want to modify this, simply click on the metric name on the experiment setup screen. This will open a popup where you can modify the test type and indicate a desired direction you seek to measure.
Our V1 doesn't support Bayesian testing yet.
At Statsig, the default percentile for winsorization is 99.9%. This reduces the influence of extreme outliers caused by factors such as logging errors or bad actors.
Winsorization is applied to sum, event count, mean, ratio, and funnel metrics, including imported metrics. Winsorization will not be applied to Participation or User Accounting metrics.
Statsig Warehouse Native lets you configure this per metric - and choose explicitly the upper and/or lower bounds to apply.
## Metric Capping
This is a very simple, but effective technique to handle outliers. With this capability, you can define max values for a metric for whatever unit type(s) are configured for this metric. Any value surpassing the set cap will automatically be adjusted downward to match it.
For instance, if you determine that purchases greater than \$10,000 per day on your E-commerce platform should not skew analysis, any transaction exceeding this threshold will be adjusted downward to this limit, ensuring the integrity of your experiment analysis. Capped metrics are available for Event Count and Aggregation (sum) metric types.
# Metric Deltas
Source: https://docs.statsig.com/experiments/statistical-methods/metric-deltas
How Statsig computes metric deltas to compare absolute and relative differences between experiment groups, including formulas and interpretation guidance.
## Computing Metric Deltas
A metric delta refers to the difference in metric values between two groups, by default the test and control groups. This is usually the impact we care about when looking at experiment results. To account for the different number of users (or units) that constitute each group, we compare the mean metric value per user, not the total.
**Selecting Groups**
We define all deltas here to be the difference between a "treatment" group as compared to a presumably unchanged "control" group. However, Statsig enables comparison between any two groups as desired.
Two different metric deltas are available in Pulse. The **absolute delta** is simply the difference between the two means:
$$
\Delta \overline{X}=\overline{X}_t-\overline{X}_c
$$
It's often helpful to understand the impact relative to the baseline value of the metric. For example, an absolute delta of +1 clicks/user has different meanings with a baseline value of 1 (+100% increase) vs. a baseline value of 100 (+1% increase). The **relative delta** is computed using the mean of the control group as the baseline:
$$
\Delta \overline{X} \%=\frac{\overline{X}_t-\overline{X}_c}{\overline{X}_c} \times 100 \%
$$
If you reverse the order of group comparison in Pulse to be "control" vs "treatment", then all deltas will be reversed and the direction of change will be inverted.
## Computing Means
Properly computing the groups means is critical for obtained meaningful metric deltas. The exact methodology for calculating the metric means depends on the type of metric.
### Event Count and Sum Metrics
These metrics represent totals: Number of times an event occurs, sum of time spent, total purchase amount, etc. The mean is the average user-level total during the time period of the analysis.
The mean value of the metric $X$ for a group is given by:
$$
\overline{X}=\frac{1}{N} \sum_{i=0}^N \sum_{d=0}^{n_i} X_{i, d}
$$
where:
* $N$ is the number of users in the group
* $n_i$ is the number of days during the analysis period that user $i$ was the experiment
* $X_{i,d}$ is the metric value for user $i$ on day $d$
Only user metrics recorded after a user has been exposed to the experiment are included in the group mean.
### User Accounting and Event User Metrics (and legacy Event DAU)
Event User metrics set to "Daily Participation Rate" capture the number of distinct users that have the event each day. In Pulse results, they are normalized by the number of days the user is in the experiment. This represents the probability that a user is daily active for that event, i.e. the daily participation rate. In the terms defined above, the group mean is given by:
$$
\overline{X}=\frac{1}{N} \sum_{i=0}^N \frac{1}{n_i} \sum_{d=0}^{n_i} X_{i, d}
$$
where:
* $X_{i,d}$ takes value 0 or 1 depending on if user $i$ has the event on a given day $d$.
The following user accounting metrics are computed in the same may: *DAU, WAU, MAU\_28day, L7, L14, L28*
For new user accounting (*new\_DAU, new\_WAU, new\_MAU\_28day*) we count users that are new xAU at some point during the analysis window. So the group mean is given by:
$$
\overline{X}=\frac{1}{N} \sum_{i=0}^N \max \left(X_i\right)
$$
Where $\max(X_i)$ is the maximum value of the new xAU metric for user $i$.
**event\_dau** metrics are now in legacy support only and are no longer created for new events. Existing event\_dau metrics will continue to be available for any of your new experiments and will continue to be computed daily. For all new events, you should create an event\_user metric to measure daily active users.
### Custom Ratios, Means, Retention and Stickiness Metrics
These are metrics such as click through rate, average purchase value, sessions per user, etc. They're obtained by diving a numerator value, $X$, by a denominator value, $Y$. The mean value of a ratio metric $R$ for an experiment group is given by:
$$
\overline{R}=\frac{\frac{1}{N} \sum_{i=0}^N \sum_{d=0}^{n_i} X_{i, d}}{\frac{1}{N} \sum_{i=0}^N \sum_{d=0}^{n_i} Y_{i, d}}=\frac{\overline{X}}{\overline{Y}}
$$
Where $N$ is the number of users in the experiment group that participate in the metric, i.e. have a non-zero denominator value. $X_{i,d}$ and $Y_{i,d}$ are the $X$ and $Y$ values for user $i$ on day $d$.
Different approaches exist for dealing with ratio metrics in experiments. This implementation was selected because it's statistically sound as well as interpretable, given that:
* $R$ is the ratio of two means of independent observations: A set of user-level $X$ values and a set of user-level $Y$ values. This means the central limit theorem can be used to separately obtain the summary statistics of $X$ and $Y$.
* The group means are computed in the same way as the topline metric value, making it easier to interpret the means and relate them to the topline metric.
### Event User One-Time Event
For custom **event\_user** metrics with "One-Time Event" selected, statsig computes how many users have the event at any time after the user has been in the experiment. This result is not normalized by the number of days a user is in the experiment. The group mean is given by:
$$
\overline{X}=\frac{1}{N} \sum_{i=0}^N X_{i}
$$
where:
* $N$ is the number of users in the group
* $X_{i}$ takes value 0 or 1 depending on if user $i$ has the event at any point after entering the experiment
# p-Value Calculation
Source: https://docs.statsig.com/experiments/statistical-methods/p-value
What p-values mean in Statsig experiments, how they are computed, and how to interpret them alongside confidence intervals and lift estimates.
In Null Hypothesis Significance Tests, the p-value is the probability of observing an effect larger than or equal to the measured metric delta, under the assumption that the null hypothesis is true. In practice, a p-value that's lower than your pre-defined Type I Error threshold ($\alpha$) is treated as evidence for there being a true effect.
The methodology used for p-value calculation depends on the number of degrees of freedom ($\nu$). A two-sample z-test is appropriate for most experiments. Welch's t-test is used for smaller experiments with $\nu < 100$. In both cases, the p-value depends on the metric [mean](/stats-engine/metric-deltas) and [variance](/stats-engine/variance) computed for the test and control groups.
Typically, a p-value that indicates statistical significance (below the pre-determined threshold $\alpha$) could only occur with a confidence interval that does not cross 0. However, this phenomenon can occur in the Statsig UI, due to cases when the p-value of the difference between test and control is statsig, but due to uncertainty in the control, a relative delta confidence interval may cross zero (using [The Delta Method](/experiments/statistical-methods/methodologies/delta-method)) or be represented as a point estimate (using [Fieller Intervals](/experiments/statistical-methods/methodologies/fieller-intervals) ) while the absolute difference's p-value is statistically significant.
## Two-Sample Tests
### Two-Sided z-Test
The z-statistic (a.k.a. z-score) of a two-sample z-test can be computed in multiple equivalent formats:
$$
\begin{split}
Z &= \frac{\overline X_t - \overline X_c}{\sqrt{var(\overline X_t)+ var(\overline X_c)}} \\
&= \frac{\overline X_t - \overline X_c}{\sqrt{var(\Delta \overline{X})}} \\
&= \frac{\overline X_t - \overline X_c}{\sqrt{\sigma_{\overline{X}_t}^2 + \sigma_{\overline{X}_c}^2}}
\end{split}
$$
where:
* $Z$ is the observed z-statistic (not the z-critical value $Z_{\alpha/s}$)
* $var(\Delta \overline{X})$ is the variance of the absolute delta of means
* $var(\overline{X}_i)$ is the variance of sample means either control or treatment group (details [here](/stats-engine/variance))
* $\sigma_{\overline{X}_t}$ is the standard error of the mean of either control or treatment group (these are the terms you can find in Pulse under the Statistics tab of a metric)
The two-sided p-value is obtained from the standard normal cumulative distribution function:
$$
p-value = 2 \cdot \frac{1}{\sqrt{2\pi}} \int \limits _{-\infty}^{-|Z|}{e^{-t^2/2}dt}
$$
### Welch's t-test
For smaller sample sizes, Welch's t-test is the preferred statistical test for lower false positive rates in cases of unequal sizes and variances. In Pulse, Welch's t-test is automatically applied when the degrees of freedom $\nu < 100$.
We compute the t-statistic (a.k.a. t-score) identically as the two-sample z-statistic above. Additionally, we compute the degrees of freedom $\nu$ using:
$$
\nu = \frac{\left(var(\overline X_t) + var(\overline X_c)\right)^2}{\frac{var(\overline X_t)^2}{N_t - 1}+\frac{var(\overline X_c)^2}{N_c - 1}}\
:= \frac{var(\Delta\overline{X})^2}{\frac{var(\overline X_t)^2}{N_t - 1}+\frac{var(\overline X_c)^2}{N_c - 1}}
$$
The p-value is then obtained from the t-distribution with $\nu$ degrees of freedom.
### One-Sided Z-Test
The procedure for a one-sided z-test computes the z-statistic $Z$ in the same way as a two-sided test above.
The one-sided p-value is obtained from the standard normal cumulative distribution function as well, but with slight differences:
$$
p-value =
\begin{cases} 1 - \frac{1}{\sqrt{2\pi}} \int \limits _{-\infty}^{Z}{e^{-t^2/2}dt} &\text{if right-hand test}\\
\frac{1}{\sqrt{2\pi}} \int \limits _{-\infty}^{Z}{e^{-t^2/2}dt} &\text{if left-hand test}
\end{cases}
$$
where:
* $Z$ is computed above in the two-sided test. Note that this uses the signed z-statistic, not the absolute value of the z-statistic as in the two-sided p-value.
# Pre-Experiment Bias
Source: https://docs.statsig.com/experiments/statistical-methods/pre-experiment-bias
How Statsig detects and corrects for pre-experiment bias caused by uneven user distributions between treatment and control groups before exposure.
In some cases, users in two experiment groups can have meaningfully different average behaviors before your experiment applies any intervention to them. If this difference is maintained after your experiment starts, it's possible that experiment analysis will attribute that pre-existing difference to your intervention.
This can make a result seem more or less "good" or "bad" than it really is.
[CUPED](/experiments/statistical-methods/methodologies/cuped) is helpful in addressing this bias, but can't totally account for it.
Additionally, some metrics like retention are not viable candidates for CUPED and can't be easily adjusted.
Statsig proactively measures the pre-experiment values of all scorecard metrics for all experiment groups, and determines if the values are significantly different and could cause misinterpretations.
If bias is detected, users are notified and a warning is placed on relevant Pulse results.
### How it works
Statsig provides a "Days Since Exposure" view to help identify novelty effects and existing pre-experiment effects. For example, the test group of the experiment below had a consistently higher mean
than the control group in the week before exposure for this metric
**Example**: Take a simple example experiment with a Control group of 1000 users and a Test group of another 1000 users, which ran for 30 days. For an **event\_count** metric, we observed an Experiment Delta of +1.0 events per user (abs). The Topline Impact for this metric would be +33.33 events per day (abs).
## Computing Topline Impact
The topline impact is computed over the total duration of the experiment. This gives the most accurate estimate and tight confidence interval. The exact calculation depends on whether the metric represents an absolute quantity or a ratio:
### Count and Sum Metrics (event\_count, sum)
The absolute topline impact is derived directly from the experiment results. It depends on the difference in means between test and control, and the average number of users in the test group per day.
$$
Impact_{abs}=(X_t-X_c) \cdot N_t / n_{days}
$$
Knowing the absolute impact and the overall metric value (as seen in the [metrics dashboard](/metrics/console)), we can compute the relative impact. This is the percentage change in the overall metric value over the rollup window that is attributed to the active experiment.
$$
Impact_{rel}=\frac{Impact_{abs}}{Topline\_Value-Impact_{abs}} \times 100\%
$$
### Ratio and Mean Metrics
To properly derive the topline impact on a ratio metric we must understand the impact on the numerator (*X*) and denominator (*Y*) separately. The topline impact is the current value of the ratio metric minus the baseline value we obtain by subtracting the numerator and denominator impacts:
$$
Impact_{abs}=\frac{Topline\_X}{Topline\_Y}-Baseline\_Value
$$
Where the baseline value is the expected value of the topline metric if the experiment wasn't running:
$$
Baseline\_Value=\frac{Topline\_X-(\bar{X_t}-\bar{X_c}) \cdot N_t}{Topline\_Y-(\bar{Y_t}-\bar{Y_c}) \cdot N_t}
$$
The relative impact for ratio metrics is obtained by dividing the absolute impact by the baseline value:
$$
Impact_{rel}=\frac{Impact_{abs}}{Baseline\_Value} \times 100\%
$$
## Computing Projected Launch Impact
The layer allocation of the experiment and the size of the test group are used to estimate a scaling factor *m*, which represents the increase in absolute impact expected when a decision is made to launch the test group.
The launch factor over a rollup window is calculated as
$$
m_{rollup}=\frac{1}{\sum_{1}^{rollup}{layer\_alloc \times group\_pct}} \times rollup
$$
to accommodate changes in allocation during the experiment.
The targeting gate isn't factored in. The projected impact calculation assumes that the target gate remains the same after the experiment is launched.
### Count and Sum Metrics (event\_count, event\_dau, sum)
For count and sum metrics, the projected absolute impact is simply the current topline impact scaled by a factor of *m*. For example: Consider an experiment running with 50% layers allocation and 50/50 test/control split, so that 25% of all users are in the test group. If the allocation has been changing during this experiment, we will use a weighted average based on historical allocations. If the topline impact is currently +10 events per day, then launching the experiment would lead to +40 events per day.
$$
Projected_{abs}=Impact_{abs} \times m
$$
The relative projected impact is expected percentage change in the topline metric, relative to the baseline value of the metric without the experiment running.
$$
Projected_{rel}=\frac{Projected_{abs}}{Topline\_Value-Impact_{abs}} \times 100\% = Impact_{rel} \times m
$$
### Ratio and Mean Metrics
Similar to the topline impact calculation above, the projected impact of ratio metrics depends on the numerator and denominator impacts. We use the same scaling factor *m* to obtain the projected impact for each term:
$$
Projected_{abs}=\frac{Topline\_X+(m-1) \cdot (\bar{X_t}-\bar{X_c}) \cdot N_t}{Topline\_Y+(m-1) \cdot (\bar{Y_t}-\bar{Y_c}) \cdot N_t} - Baseline\_Value
$$
Where the first term represents the projected metric value after launch.
Finally, the projected relative impact of a ratio metric is the projected absolute impact divided by the baseline value of the ratio:
$$
Projected_{rel}=(\frac{Projected_{abs}}{Baseline\_Value}) \times 100\%
$$
## Confidence intervals
The confidence intervals for topline and projected impact are computed in the same way as the [confidence intervals](/stats-engine/confidence-intervals) for experiment deltas.
$$
CI(Impact) = Impact \pm Z \cdot \sqrt{var(Impact)}
$$
In the case of absolute impact of count and sum metrics, the variance calculation is simply a linear combination of the test and control variances:
$$
var(Impact_{abs})=[var(\bar{X_t})+var({\bar{X_c}})] \cdot N_t^2
$$
And for projected launch impact we get:
$$
var(Projected_{abs})=var(Impact_{abs}) \cdot m^2
$$
For ratio metrics and relative impacts, the variance is calculated using the Delta method. This properly accounts for the correlation between the various numerator and denominator terms, leveraging Taylor expansion to linearize expressions containing non-linear combinations of experiment variables.
For example, the variance in the relative impact of a count metric is given by:
$$
var(Impact_{rel})=var(Impact_{abs}) \cdot \frac{(Topline\_Value - 2 \cdot Impact_{abs})^2}{(Topline\_Value - Impact_{abs})^4}
$$
# Standard Error & Mean Variance
Source: https://docs.statsig.com/experiments/statistical-methods/variance
How Statsig computes variance for experiment metrics, including handling of ratio metrics, clustered data, and user-level aggregation across exposures.
The standard error (sometimes denoted "SE" or "std err") of the mean of each group is required for computing the confidence interval and p-value of a metric delta between those groups. The standard error of the mean can be obtained by dividing the sample standard deviation of $X$ by the square root of the number of users in the group.
$$
\sigma_{\overline X} = \frac{\sigma_{X}}{\sqrt{N}} = \sqrt{\frac{var(X)}{N}} = \sqrt{var(\overline{X})}
$$
Note that standard deviation is the square root of the variance. Since variances are easier to manipulate algebraically, here we derive the variance for each metric type and then take the square root to obtain the confidence intervals.
Pulse displays the standard error of the mean of each group alongside the units and mean of each group.
## Computing Variance
The variance of the absolute metric delta is simply the sum of the variances of the test and control means:
$$
var(\Delta \overline X) =var(\overline X_t - \overline X_c) = var(\overline X_t) + var(\overline X_c)
$$
In other words, it comes down to correctly calculating the variance of the means for each group.
### Count and Sum Metrics
For count and sum metrics, the variance of the sample mean for a given group is obtained directly from the sample variance:
$$
var(\overline{X}) = \frac{var(X)}{N} = \frac{\frac{1}{N-1}\sum_{i=0}^{N}(X_i-\overline{X})^2}{N}
$$
Where:
* $N$ is the number of users in the group
* $X_i$ is the metric value for user $i$
* $\overline{X}$ is the user-level average of $X$ for users in that group
### Ratio and Mean Metrics
Some metrics like ratio and mean metrics combines multiple variables $X$ and $Y$ instead of a single variable $X$. The variance of these metrics depends upon both the numerator and denominator variables, which are typically correlated. We'll call the metric of interest $R$ and we can compute the group mean $\overline{R}$ and group variance of the mean $var(\overline{R}$).
For example, consider a *clicks per session* metric. The number of clicks and the number of sessions are two sets of observations coming from the same group of users, so they are not independent from each other.
To properly account for any correlation, the variance of the mean of a ratio metric $R$ is obtained using the delta method:
$$
var(\overline R) = var\left(\frac{\overline X}{\overline Y}\right)
:= \left(\frac{\overline X}{\overline Y}\right)^2 \cdot \left(\frac{var(\overline X)}{\overline X^2} + \frac{var(\overline Y)}{\overline Y^2} - 2 \cdot \frac{covar(\overline X, \overline Y)}{\overline X\cdot \overline Y} \right)
$$
where the variance of the numerator and denominator means are computed in the same way as detailed above for count metrics, and the covariance is
$$
covar(\overline X, \overline Y) = \frac{covar(X, Y)}{N} = \frac{\frac{1}{N-1}\sum_{i=0}^{N}(X_i-\overline X)\cdot (Y_i-\overline Y)}{N}
$$
# Variance Reduction
Source: https://docs.statsig.com/experiments/statistical-methods/variance-reduction
Overview of variance reduction techniques in Statsig experiments, including CUPED, stratified sampling, and regression adjustment for higher sensitivity.
## Variance Reduction
[Variance](/stats-engine/variance) is a measurement of dispersion which measures the amount of "noise" in a metric or experiment results. Higher variance is associated with larger confidence intervals, and leads to experiments requiring more sample size to consistently observe a statistically significant result on the same effect size.
Reducing variance can lead to shorter experiment run times due to the lower sample required. Because of this, techniques have been developed to reduce the variance in experiment results in order to reduce run times and increase confidence.
At Statsig, we use a form of CUPED based on a [2013 Microsoft paper](https://www.exp-platform.com/Documents/2013-02-CUPED-ImprovingSensitivityOfControlledExperiments.pdf) (Deng, Xu, Kohavi, & Walker). This is automatically applied to experiments at Statsig, and is run for the topline results on key metrics in Pulse. This observably leads to significant variance reduction in the large majority of metrics where CUPED can be applied.
Refer to our [launch post for CUPED](https://blog.statsig.com/cuped-on-statsig-d57f23122d0e) for more details.
## CUPED - Controlled-experiment Using Pre-Existing Data
CUPED (short for Controlled-experiment Using Pre-Existing Data) is a technique which leverages user information from before an experiment to reduce the variance, and increase confidence in experimental metrics. At Statsig, this pre-experiment data is defined as the 7 days before each user's exposure rather than a fixed window before the experiment starts for all users. This can help to debias experiments which have meaningful pre-exposure bias (e.g. the groups were randomly different before any treatment was applied).
The Cloud product uses stratification alongside CUPED to account for users who may not have pre-experiment data. Users are grouped into strata based on available pre-experimentation information. Treatment and control effects are first estimated within each stratum, then aggregated to produce an overall result. We then apply the standard difference-in-means and variance estimation. This approach allows us to retain users with missing pre-data while still benefiting from variance reduction where applicable.
## Winsorization
Another common technique for reducing noise is Winsorization, which is a way to manage the influence of outliers.
Winsorization refers to the practice of measuring the percentile *Px * of a metric and setting all values over *Px * to *Px *.This reduces the influence of extreme outliers caused by factors such as logging errors or bad actors.
## Metric Selection
The metrics you use can dramatically influence the sensitivity of your analysis. The transformations above, in addition to techniques like creating threshold-based flags, can let you trade-off exact numbers for significantly more power. Please refer to our [blog post](https://www.statsig.com/blog/understanding-and-reducing-variance-and-standard-deviation) on the topic for more information.
## Literature
Here's a short list of useful content for understanding more about these techniques and its applications
* [Deng, Xu, Kohavi, & Walker](https://exp-platform.com/Documents/2013-02-CUPED-ImprovingSensitivityOfControlledExperiments.pdf) is the seminal paper on using this technique for online controlled experiments
* [Booking.com](https://booking.ai/how-booking-com-increases-the-power-of-online-experiments-with-cuped-995d186fff1d) has an excellent blog post on the theory and practice of CUPED
* [Improving the Sensitivity of Online Controlled Experiments: Case Studies at Netflix](https://www.kdd.org/kdd2016/papers/files/adp0945-xieA.pdf)
# Decision Framework
Source: https://docs.statsig.com/experiments/templates/decision-framework
Use a structured decision framework in Statsig to evaluate experiment results, including success criteria, ship versus iterate logic, and reviewer sign-off.
A Decision Framework for experiment templates allows teams to standardize their interpretation of results and decision-making process. Once configured, it provides clear recommendations for which group to ship based on experimental outcomes. While the framework highlights recommended actions based on metric movements, it does not enforce any actions.
## Setup
To configure a Decision Framework, find your desired experiment template under **Settings** → [**Templates**](https://console.statsig.com/templates), then navigate to the **Decision Framework** tab. By selecting one primary metric and one or more guardrail metrics, you can choose a recommended action based on metric performance.
Permissions for who can create or modify templates are managed via Statsig's Role-based Access Controls in **People** -> **Roles**. By default Org and Project Admins can modify or delete any Template.
You must create at least 1 experiment/ gate template for users to choose if you toggle on this setting, otherwise they will be blocked in creating new configs.
This setting only applies if templates aren't already required at the organization-level, in which case that overrides any team-level configuration).
To configure team-specific templates, navigate to **Settings** -> **People** -> **Teams** -> choose a team -> **Settings** and then choose which templates are allowed for gates, dynamic configs, and experiments.
Strip out `http` vs `https` and query params, leaving only the stable base URL, so that is what is hashed deterministically.
***
## 2. Define Metrics Before Shipping
Make sure the metrics you’ll want to measure are in your data warehouse, keyed on `page_url`.\
Register these with Statsig’s **metric catalog**. Because the same pipeline powers feature experiments, your existing CUPED or stratified-sampling settings automatically apply.
### Example Metrics
| Layer | Metric Source | Why it Matters |
| ----------------- | ----------------------------------------------------- | ------------------------------------ |
| Indexing lag | Impressions, average position (Search Console) | Early signal during re-crawling |
| Primary KPI | Organic sessions keyed by `page_url` (Statsig Events) | Measures traffic that actually lands |
| Quality guardrail | Conversion, bounce, read-depth, revenue | Ensures traffic is useful |
***
## 3. Implement the Change Behind an Experiment
* Create an experiment called `seo_title_test` in Statsig Docs.
* Target on the **Custom Unit ID `page_url`** with a 50/50 split across Control and Test.
* Expose the variant in the template renderer or CDN edge function.
***
## 4. Ship, Monitor, Decide
* Use **Power Analysis** to determine how long your experiment should run based on traffic volume.
* Expect first signals in 2–7 days; wait for re-indexing to plateau before things stabilize.
* Merge the winner into your template and archive the test; experiment summaries remain searchable forever.
### SEO-Specific Guardrails
| Guardrail | What to Watch | Why it Protects You |
| --------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Indexation Δ | `indexed_pages` vs baseline | A template tweak that blocks crawl (robots, canonicals, noindex) will show a sharp drop long before traffic falls |
| Cannibalization ratio | Avg. URLs served per query | Multiple pages newly ranking for the same query dilute CTR and can tank combined traffic |
| HTTP response mix | % 410 vs 301 vs 200 | A bulk 410 (gone) or mis-configured 301 can wipe out long-tail pages |
| Core Web Vitals drift | LCP & CLS p75 | Page-speed regressions may hurt rankings silently |
| Crawl budget | Avg. TTFB + bytes/page | Slow/bloated pages decrease crawl rate |
***
## 5. Concrete Page-Level Changes Worth A/B Testing
| Theme | Why It Might Move Organic Traffic | Typical Implementation Knob |
| ----------------------- | --------------------------------- | ----------------------------------------------------------------------- |
| Title & meta variants | Query-matching, CTR uplift | Add/remove brand suffix, noun → verb phrasing, insert dynamic price |
| Structured data | Rich-result eligibility | Inject FAQ, HowTo, Breadcrumb, or Product schema blocks |
| Internal-link blocks | Crawl priority & PageRank flow | Swap “related articles” widget ordering; test link count caps |
| Content snippets | Relevance & long-tail keywords | Auto-generate 50-word intro vs. none; expand FAQ length |
| Canonical/hreflang tags | Duplicate-content handling | Toggle self-canonical vs. cluster canonical; add `hreflang="x-default"` |
| Media handling | CLS/LCP scores influence rankings | Defer off-screen images; inline critical hero image; switch to AVIF |
| Pagination model | Crawl depth & index coverage | Classic `?page=` URLs vs. `rel="next/prev"` vs. load-more buttons |
| Performance budgets | Core Web Vitals ranking factor | 200 ms JS chunk split vs. baseline; CSS purge + inline critical-CSS |
| Ad layout | CLS penalties, user engagement | Reserve fixed ad slots vs. dynamic; lazy-load below first viewport |
| Schema position | Parser friendliness | Move JSON-LD block to `<head>` vs. end of `<body>` |
***
## 6. Is SEO Experimentation Right for You?
| Great Fit | Maybe Not Yet |
| ---------------------------------------------------------------- | ----------------------------------------------------------- |
| Large page surface (10k+ URLs): marketplaces, docs, publishers | Marketing sites with \<1k pages or sporadic organic traffic |
| Teams already shipping **weekly** and want proof before rollouts | Heavy paid-ads model where SEO is \<5% of acquisition |
| Companies with engineering bandwidth to template page changes | Sites on locked-down CMSs that forbid code/tag edits |
***
## 7. Key Takeaways
* **Segment by page, not user.** Use a Statsig Custom ID for deterministic hashing into Control/Test.
* **Measure beyond clicks.** Pair Search Console data with product analytics for full-funnel insight.
* **Move fast, break nothing.** Statsig’s sequential engine and guardrails catch bad bets early.
* **One platform for every test.** Product, pricing, UX, and SEO experiments in a single, trusted workflow.
***
Statsig also supports other experiment types such as **switchback testing** and **geo-testing**.
Geo-testing is particularly useful for measuring the **incrementality of ad spend**, which is hard to measure with traditional experiments due to privacy requirements.
# Switchback Tests
Source: https://docs.statsig.com/experiments/types/switchback-tests
Learn about switchback testing methodology and how to set up switchback experiments for marketplaces and network effect scenarios.
# What is Switchback Testing?
Switchback tests are an alternative experiment form, whereby an entire population is "switched" back and forth between test and control treatments on a set cadence vs. being split and evenly divided between test and control for the duration of the experiment.
Switchback tests are particularly common in marketplaces, whereby running a traditional A/B on one side- or a small %- of the marketplace would have an unintended consequence on the rest of the marketplace due to network effects, ultimately impacting experiment results.
Another common use case for switchbacks occurs when applying different variants to different users is infeasible for fairness, legal, or logistical reasons.
Switchback tests are often carried out across multiple "buckets", typically regions or other defined groups that are flipped between test and control treatments over the course of the experiment.
### Example
Let's say you are a rideshare platform and want to test pricing. You initially consider splitting your riders into two groups, one with the higher price and one with a lower price.
However, you quickly notice that the riders with the lower price are requesting rides at a significantly higher rate, and sucking up all the available driver supply in a given area. This leaves the riders with higher prices with not only a higher ride estimate, but longer ETAs when they open up their app, making them even less likely to request.
When you look at your experiment results you're not sure if the decreased ride request rate in the higher price group was due to the higher prices they saw or the fact that their ETAs went up- your experiment results are polluted! You've inadvertently introduced *bias* to your results via your experimental design.
In this scenario, you could consider running a Switchback test on your marketplace. To do this, you might switch 100% of your riders and drivers in a given metro in and out of the new pricing plan hourly and understand the impact on overall ride request rates during hours at which rider prices were higher vs. lower.
# Switchback Testing on Statsig
## Methodology
Our Switchback Testing methodology for computing results consists of 3 steps:
1. Attribute events to the corresponding switchback bucket, where each bucket is defined by the time window and grouping attribute.
2. Calculate the variant-level and bucket-level metrics based on the attributed events.
3. Calculate the difference in means between test and control. Use bootstrapping to obtain the confidence intervals.
### Event Attribution
Attribution of events to a particular bucket is based on the timestamp and unit\_id of the exposure, the length of the attribution window, and the timestamp of subsequent events for that unit\_id.
For example: User 123 is exposed to bucket A at 9:15 am. The test has an attribution window of 90 minutes. This means all events triggered by user 123 between 9:15 am and 10:45 am will be included in the metric calculations for bucket A.
### Bucket-level Metrics
Once we have all the events corresponding to a bucket, we calculate the scorecard metrics derived from these events.
Randomized bucketing is an advanced feature, please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
Statsig Slack community and we'll discuss options.
***
### How do I retrieve all exposures for a user?
The [Users tab](https://console.statsig.com/users) shows historical exposures. For hypothetical assignments (e.g., to bootstrap clients) you can call `getClientInitializeResponse` on the server. Pass `{ hash: 'none' }` if you need readable keys:
```js theme={null}
const assignments = statsig.getClientInitializeResponse(user, 'client-key', { hash: 'none' });
```
***
### What happens if I check a config that doesn't exist?
The SDK returns defaults—`false` for gates and the supplied fallback for experiments/layers. You'll see the evaluation reason `Unrecognized`; learn more in [SDK debugging](/sdks/debugging#evaluation-reason). This applies to deleted, archived, or unseen configs (e.g., filtered by [target apps](/sdks/target-apps)).
***
## Feature Gates
### If I change the rollout percentage, do existing users keep their result?
Yes. Increasing the pass percentage (e.g., 10% → 20%) keeps the original 10% and adds new traffic until you reach the new percentage. Decreasing it removes the newest slice first. To reshuffle everyone, you must resalt the gate. (Experiments behave differently—use targeting gates for deterministic control.)
***
## Statistics
### What statistical tests does Statsig use?
We use a two-sample Z-test for most experiments and [Welch's t-test](/experiments/statistical-methods/p-value#welchs-t-test) when sample sizes are small or variances differ.
***
### How does Statsig handle low sample sizes?
We fall back to [Welch's t-test](/experiments/statistical-methods/p-value#welchs-t-test) and offer CUPED/winsorization to boost power.
***
### When should I use one-sided vs. two-sided tests?
Use one-sided when you only care about movement in a single direction; it increases power but hides movement in the opposite direction.
***
## Experimentation
### How do I get started with an A/B test?
If the feature isn't live yet, wrap it in a [feature gate](/guides/first-feature) and roll out. If it's already in production, create an [experiment](/guides/abn-tests). Results appear in the Pulse view.
***
### Can I target experiments to specific users (e.g., iOS only)?
Yes. Use a feature gate with targeting rules as a pre-filter for your experiment.
status.statsig.com . To report an issue or receive help, reach out directly in our Slack Community .
***
# Best practices for Feature Gates
Source: https://docs.statsig.com/feature-flags/best-practices
Best practices for implementing Statsig feature gates, including naming, code structure, team collaboration, governance, and managing flag lifecycles at scale.
Statsig classifies the best practices for using feature gates into four categories: implementation, development, collaboration, and governance.
## Implementation
1. **Manage for ease and maintainability** – Use simple if/else gate checks for short lived gates that you can quickly clean up after the release. Use configuration parameters for longer lived gates to avoid nesting multiple gates and growing complexity in your code over time.
2. **Select the gating decision point** – Implement client-side feature gates to select users where most context is available and/or when the feature is primarily developed in the presentation layer (e.g. user registration flow). Implement server-side feature gates when most context is available with the application server and/or when the feature is primarily related to backend system behavior (e.g. new cache layer for better performance). Localizing these gating decisions within the service whose behavior is being changed is the best option in these cases.
3. **Focus on one feature** – Using one feature gate to control multiple features at a time can be confusing and can make troubleshooting issues difficult. If there are multiple parts of a feature that must work together, create a master feature gate to control child feature gates for these individual parts.
## Development
1. **Speed up development** – Shipping new functionality behind a feature gate ensures that the code path is not activated until you're ready to integrate with your dependencies. This enables you to ship service components faster without being blocked by any dependencies.
2. **Always be testing** - Use feature gates to ensure that in-development features remain inactive in production while continuing to test new functionality in staging or pre-production environments.
3. **Progressive delivery** – Ship code for in-development features early and often. Shipping code as part of the main branch that can be deployed to production at any time avoids painful merging of long-lived branches at a later point.
4. **Validate functionality with trusted users** – Use features gates to only expose new functionality to trusted and friendly users such as teammates, company employees, and beta customers before launching publicly. Verify that the new functionality is working as expected.
5. **Set up a phased canary release** – Use feature gates to progressively expose new functionality to a small percentage of users, validate user experience, and monitor production system health before launching broadly. In the initial stages, scale up slowly. We recommend the following rollout strategy, which increases by the same multiplier each time, increasing the bucket of new users exposed to the experiment by a larger margin each time: 0% -> 2% -> 10% -> 50% -> 100%
6. **Validate user and system impact** - Compare key user and system metrics against the default behavior. Common user metrics to test include daily and weekly active users, weekly retention, and conversion rates for key user actions. Common system metrics include error response rates, application crash rates, p50/p90/p99 request-response latency, and CPU utilization. You can create a metric for any key user or system behavior by logging the event that best proxies that behavior with Statsig.
7. **Ramp up or roll back** – Identify issues, and negative impact on users early. Use metric-based evidence to decide whether to release the feature more broadly. If you decide to launch, ramp up deployment (e.g. 10% -> 50% -> 100%).
8. **Clean-up after releases** – Once the release is complete, remove unnecessary gates from code. Once they are no longer checked, you are free to turn them off/delete them.
## Collaboration
1. Scoped Access - Invite verified teammates to create, review, and approve feature gates for a specific project.
2. Role-based Access Control (RBAC) - Ensure that only project members with the appropriate privileges can create and edit feature gate configurations with role-based access control.
## Governance
1. **Audit and record** - Set up audit logs for any changes that your team makes to any feature gates.
2. **Monitor and automate** - Set up automated health monitoring and alerts to improve visibility of your feature gates, reduce response times for any issues, and create automated workflows for common response patterns.
# Feature Gate rule criteria
Source: https://docs.statsig.com/feature-flags/conditions
Understand how Statsig evaluates feature gate rules from top to bottom and see the full list of supported targeting conditions and operators.
Statsig feature gates contain a list of rules that are evaluated in order from top to bottom. The page describes in more detail how these rules are evaluated and lists all currently supported conditions.
## Rule Evaluation
The rules that you create are evaluated in the order they're listed. For each rule, the **criteria** or **conditions** determine which users *qualify* for the Pass/Fail treatments. The Pass percentage further determines the percentage of *qualifying* users that will be exposed to the new feature. The remaining *qualifying* users will see the feature disabled.
Suppose you set up your rules as shown below, the following flow chart illustrates how Statsig evaluates these rules.
Once a user is exposed, they will be included in the analysis going forward. They saw the new feature and were affected. If the feature gate rules are modified or the user's attributes change in a way that the user no longer qualifies, they will stop receiving the new feature. However, they will continue to be counted for analysis. Once you roll out the feature, all users will see the new feature; alternatively, if you turn off the feature gate, all users will see the control (feature disabled). In either case (roll out or turn off), Statsig performs no further analysis.
When you add user IDs in the **Pass** or **Fail** lists of your feature gate, these users will see the appropriate treatment but will not be included in the analysis.
# Create a Feature Gate
Source: https://docs.statsig.com/feature-flags/create
Step-by-step guide to creating a feature gate in the Statsig console, adding targeting rules, implementing the gate in code, and reviewing examples.
## In the Statsig console
### Create a new Feature Gate
1. Log into the Statsig console at [https://console.statsig.com](https://console.statsig.com).
2. On the left-hand navigation panel, under **Feature Management**, select **Feature Gates**.
3. Click on the **Create** button.
4. Enter the name and the description of the Feature Gate you want to create. It's best to name your gate based on what you are rolling out, such as "Zippy Home Page" for a new homepage.
Gate is {client.checkGate("example_gate") ? "passing" : "failing"}.
);
```
In the code snippet example above, the Statsig SDK is checking from a client app whether you've set any rules named "Example Gate". It will render the text "Gate is passing" for users who pass your gate based on conditions you set, and "Gate is failing" for users who fail the gate conditions.
Statsig offers over 20 client and server-side SDKs. Check out the full list of [SDKs](/sdks/quickstart#all-sdks) to find the one that best fits your needs.
## Common Feature Gate setups
### Kill switches
You can set up a simple "kill switch" by first setting an `Everyone` criteria's Pass percentage to 100%. Then, if you need to completely disable the feature for all users at some point after code deployment, you can set the Pass percentage to 0%, effectively killing the feature for all users.
### OS-based flags
You can target users based on common application properties such as the operating system that the application is running on. For example, to target iOS users only, you can create a rule with the "Operating System" criteria, the "Any of" operator, and then listing "iOS" in the text field.
### Internal employees only
You can target users based on known user attributes. For example, you can use the user's **Email** attribute and the **Contains any of** operator, then enter the email domain of your company to target only internal employees.
### Defined user segments
You can also target users in a defined user [Segment](/segments).
### Parent/child flags
You can target users based on their eligibility of other Feature Gates, enabling powerful chaining, hierarchy, and dependencies of flags. [Flag lifecycle management](/feature-flags/feature-flags-lifecycle) makes it easy to manage, deprecate, and maintain dependent flags.
# Managing Feature Gate lifecycles
Source: https://docs.statsig.com/feature-flags/feature-flags-lifecycle
Learn how to manage feature gates through different phases of their lifecycle - from testing to full rollout to cleanup and archival.
A feature can go through different phases throughout its lifecycle - maybe it's still being tested out by a few users, or only recently fully rolled out to the world, or maybe it's been tried and true and you no longer need the feature behind a toggle.
Whatever phase the feature may be in, its gate should clearly reflect that, for a few important reasons -
* **Prevent incidents**: prevent a scenario where old code for a deprecated feature is accidentally touched or repurposed, with real business consequences like how [Knight Capital lost half-a-billion dollars](https://www.statsig.com/blog/lose-half-a-billion-dollars-with-bad-feature-flags-knight-capital).
* **Maintain healthy codebase**: messy code base with dead references to flags mean that your team has more volume of code to navigate on a daily basis, and it can even slow down new developers onboarding.
* **Reduce mental load**: mental tracking of all your features is no longer necessary because you will be able to see easily what next steps you need to take for the product (e.g. launch or kill a feature), as well as not having to worry about old features that are no longer relevant.
## Managing Feature Gate lifecycles
Statsig makes it easy for your feature gates to reflect the phase your feature is in by using **status**. A gate can be in one of four statuses:
Please confirm that these gates are not included in any active Holdouts before removing reference
* To find *all* gates that are good candidates to be removed from your codebase (i.e. have been **Launched** or **Disabled** more than 60 days ago)
* Go to Feature Gates catalog
* Click on filter icon: Status = **Launched** AND **Disabled**
* In search bar: "Modified: `
We recommend having a quarterly "feature gate cleanup party", where the team blocks out a chunk of time to identify all gates that need to be cleaned up (step #2) and remove the references from their codebase. One person can then follow up after 7 days to make sure all those gates are now receiving 0 checks on Statsig and can mark them as "Archived". Overtime, your team should see more **Archived** gates than **Launched/Disabled/In Progress** gates.
Consistent with any other changes to a gate, anyone will be able to make a change, but it will require the same review process for the change to be approved.
Yes, once the feature gate is **Launched** or **Disabled**, you will see a banner with an option to re-enable rule evaluation.
In that case, Statsig will return false. Unarchive the gate and make it permanent if you will need to reference it indefinitely (i.e. from an older version of a mobile app that still has users).
We recommend that you use Delete only for mistakes. Deletion removes the gate and its history from Statsig, and having your Feature Gate Catalog retain history of your gates will help you see valuable information like velocity of your team's feature releases, # of launches decisions made, etc.
Archival of a gate implies that any reference to the gate has been completely and permanently removed from your code. Therefore, as best practice, we recommend that you clone an archived gate, essentially creating a new gate with the same rules, instead of reusing a previously archived gate.
# Measuring multiple rollout stages
Source: https://docs.statsig.com/feature-flags/multiple-rollout-stages
Learn how Statsig handles continuous analysis and multi-stage feature flag rollouts for comprehensive measurement and experimentation.
## Continuous Analysis
For gate rules that rollout with a pass percentage ≤ 50% and without any rollback, data collected at earlier stages and later stages in the rollout will be consolidated into one analysis. This allows for a more complete and thorough analysis.
Valid continuous analysis rollouts include:
10% → 20%
10% → 20% → 50%
Invalid continuous analysis rollouts include:
10% → 5% (rollback)
10% → 70% (exceeds 50%)
When a rollout is no longer valid for continuous analysis, the new rollout step is analyzed separately from previous steps.
## Compatibility with Other Gate Features
### Balanced Gates
Gate rules that have multiple rollout stages are also [balanced](/feature-flags/view-exposures#balanced-gates) using downsampling.
In cases where pass percentage ≤ 50% we use the same hashing as the pass/fail and take an equal percentage of the other group.
When pass percentage > 50% we use an orthogonal random hashing to sample the larger group at a rate of $\frac{1-p}{p}$ where p is the fraction of users in the larger group. In the case of a gradual rollout, this prevents bias based on enrollment time period.
### CUPED/CURE
CUPED/CURE is available only when there have been no rollbacks AND when the rollout percentage has not exceeded 50% within a gate rule. Analysis is no longer continuous when there's a rollback or when 50% is exceeded, which means the pre-exposure data of a given unit is actually biased by earlier treatments.
# Feature Gate overrides
Source: https://docs.statsig.com/feature-flags/overrides
During development, it can be useful to explicitly state which users should pass or fail a given feature gate. This is where overrides come in.
## Override results of a feature gate
During development, it can be useful to explicitly state which users should pass or fail a given feature gate. This is where overrides come in.
Overrides are based of user IDs and can be set to pass or fail for a given user ID. During evaluation of a gate, if the user ID is overridden, the overridden result will be returned immediately before any rules are evaluated.
### Adding an Override
* Log into the Statsig console at [https://console.statsig.com](https://console.statsig.com)
* On the left-hand navigation panel, select **Feature Gates**
* Select the feature gate where you want to add an Override
* Click the **Add Override** button
A user can only exist on one of these lists at a time.
* Once you have added the user IDs, hit **Save**
### Deleting an Override
If you add an override but later decide it is no longer needed. You can remove it so the rules will be evaluated as normal.
* Log into the Statsig console at [https://console.statsig.com](https://console.statsig.com)
* On the left-hand navigation panel, select **Feature Gates**
* Select the feature gate where you want to add an Override
* Click the **Edit Overrides** button
Dynamic Configs are key-value configs that let you return structured data (not just true/false) based on targeting rules. They're more for customizing behavior, tuning parameters, or supporting complex logic *beyond booleans*. Feature Gates are simpler on/off switches for gating access to a feature. Technically, you can set up a Dynamic Config as a Feature Gate.
We have a full guide on [Choosing Feature Flags vs. Experiments](/guides/featureflags-or-experiments). (TL;DR—Use Feature Gates when you just want to measure the general impact of a feature rollout, and use Experiments when you have a more specific hypothesis or "test" in mind.)
## Related tutorials
* [Set up dev environments with Feature Gates](/guides/using-environments)
* [Customize dev environments with Feature Gates](/guides/testing)
* [Choosing Feature Flags vs. Experiments](/guides/featureflags-or-experiments)
* [Best Practices for Feature Gates](/feature-flags/best-practices)
# Permanent and Stale Gates
Source: https://docs.statsig.com/feature-flags/permanent-and-stale-gates
Manage the lifecycle of Statsig feature gates with Types to identify temporary flags ready for cleanup and mark gates intended as permanent integrations.
It is important for your codebase and team to bring feature gates to a final state (i.e. flags now permanently part of your codebase or completely removed) when they have served their purpose, as described [here](/feature-flags/feature-flags-lifecycle). On Statsig, you can use feature gate **Types** to easily keep track of your flags that might be ready to brought to their final state.
## Types
In your feature gates catalog, you'll see different **Types** displayed in the Status column, as well as under the filter option -
**Cloud Only Feature**
This feature is currently available only on Statsig Cloud. As we work on a WHN solution, please reach out to Statsig if you're interested in being an early customer.
## What are Pre-Post Results in Statsig?
Pre-Post Results is an analysis mode for Feature Gates in Statsig that allows you to roughly estimate the impact of feature rollouts when a traditional A/B testing isn't possible. By comparing key metrics before and after a feature gate is rolled out from 0% to 100% of users, you can identify the directional impact of your features in production.
**Recommended:** Ideally you want to monitor topline alerts for crashes, errors, latency, etc. *for a few days* after a Feature Gate rollout to make sure things are stable. We recommend starting with a 14-day evaluation period.
6. Select one or more alerts to monitor:
* Rollout alerts - For feature-specific regression detection
* Topline alerts - For system-wide health monitoring
Safeguards is available on our Pro and Enterprise billing tiers.
## When to use Safeguards
Use Safeguards when you want to:
* Limit the impact of a feature on a critical business or performance metrics
* Automate rollout progression to more users based on how your metrics are performing
* Maintain system stability by automatically responding to API errors, latency spikes, or infrastructure issues
## How Safeguards work
Safeguards work by listening to different types of alerts, such as Rollout Alerts and Topline Alerts, that you have created in your project. When any alert fires due to metric regressions, Safeguards automatically pause your rollout, rolls it back, or finish a rollout based on your settings.
Pre-requisite
You must create at least one Rollout Alert or Topline Alert before configuring Safeguard on a Feature Gate. See the [Alerts](/product-analytics/alerts-overview) documentation for setup instructions.
## Two types of Safeguards
There are two different types of alerts a Safeguard can use to take an action on your Feature Gate:
#### Rollout Alert
Definition: Monitor the regression of metric delta between users who pass and fail your Feature Gate
Use-case: When you want to ensure that your Feature Gate is not causing any negative drift on the users getting the new flag variation. Only works on partially rolled out rules (pass rate between 0% and 100%)
#### Topline Alert
Definition: Monitor absolute metric values regardless of Feature Gate assignment
Use-case: When you want to take an action on your Feature Gate when system metrics breach thresholds, regardless of confirming causation. Works on fully rolled out (0% or 100%) as well as partially rolled out rules
## Getting Started
Follow these tutorials to start using Safeguards:
* [Create a new Safeguard](/feature-flags/safeguards-create)
* [Manage an existing Safeguard](/feature-flags/safeguards-manage)
# Scheduled Rollouts
Source: https://docs.statsig.com/feature-flags/scheduled-rollouts
Configure pre-set, time-based feature rollout schedules in Statsig that automatically increase traffic percentages or flip rules at specific dates and times.
Feature Gates are powerful in ensuring a safe, controlled feature rollout. Scheduled Rollouts add a time-based scheduling layer to Feature Gates, enabling you to pre-set any rollout schedule you want, which will execute automatically. This is particularly useful if, for example, you have a feature launch happening in another timezone (and don't want to stay up all night!) or you have a standard, company-wide ramp-up schedule you follow with every feature release.
Scheduled rollouts are set at the Feature Gate **rule** level, enabling maximal flexibility. Not all rules in your Gate need to include a scheduled rollout, simply set it up for whichever rules make the most sense.
## Set up a Scheduled Rollout
To set up a Scheduled Rollout on a rule in your Feature Gate, simply tap on the "…" in the upper right-hand corner of the rule you want to schedule a rollout for.
Rollout times are available in 15 minute increments. Additionally, each configured phase represents a discrete increase to the next rollout percentage, not a gradual rollout amortized over the course of the entire phase.
Information on Bots & Filtering has been moved to its [own page](/experiments/monitoring/bots)
# Running an A/A Test using Sidecar
Source: https://docs.statsig.com/guides/aa-sidecar
Run an A/A test with the Statsig Sidecar Chrome extension to validate your experimentation setup and confirm metrics fire correctly before launching A/B tests.
In this guide, we will walk you through how to leverage Statsig’s sidecar to run an A/A test on your product.
This guide assumes that you have successfully set up and configured Statsig Sidecar. For a step-by-step guide on how to do this, see our ["setting up Sidecar"](/guides/sidecar-experiments/setup) guide.
## Why run an A/A (aa) test?
There are many reasons to run an A/A test, one of the most common being to validate a new experimentation engine you may be integrating with (in this case Statsig). For new users just getting started with Statsig, we often recommend running an A/A test to provide a “low-stakes” first test environment, ensuring that you’ve got your metrics set up correctly and are seeing exposures flowing through as expected before kicking off your first real A/B test.
## How to run an A/A test
### Step 1: Create a new Experiment in Sidecar
Navigate to the page on your website that you want to run an A/A Test. Open the Statsig Side car extension and click on 'New Experiment'. Fill in the title of your A/A test.
Experiment parameters and groups cannot be configured after launching an experiment. If you want to test in a staging environment, check out our docs on [using environments](/guides/using-environments/#configuring-environments).
## Step 2: In your application code
### Check the experiment
This tutorial assumes you have already [installed the Statsig Client SDK](/sdks/quickstart) in an existing application.
Next, we'll use a Statsig Client SDK to check a user's assigned experiment group and parameters in real-time. This will change the user's experience according to the variant they are assigned to. In this case, we fetch the value of the `enable_banner` parameter that we had created earlier.
```tsx Check Experiment theme={null}
const quickstartExperiment = myStatsigClient.getExperiment(user, "quickstart_experiment");
// the second parameter is the default fallback value if the experiment is not found
if (quickstartExperiment.get("enable_banner", false)) {
showBanner();
}
```
In this snippet, if this user is assigned to the Experiment group, they will be shown the banner. If they are assigned to the Control group, the banner will not be shown.
Notice that we never actually have to [hardcode the experiment group name](/experiments/implementation/getting-group) ("Control" or "Experiment") in the code. This is because the Statsig SDK will automatically fetch the experiment configuration from the Statsig server and return the correct value based on the user's variant.
## Step 3: Monitor experiment diagnostics
Now, if you run your code, the `showBanner()` function is called for users in the Test group. If you navigate to your experiment in the Statsig console and select the **Diagnostics** tab, you can see a live log stream of checks and events related to this experiment from your application.
You can read more about the Diagnostics tab [here](/experiments/implementation/getting-group#rules).
**example only — implementation may vary depending on your provider**
## Best Practices
* Use a provider-specific "Config Sync" [integration](https://console.statsig.com/integrations) — Statsig will automatically sync your Statsig configuration data to your provider's Edge Storage.
* Use a provider-specific Data Adapter — This will allow the Statsig SDK to initialize using the configuration stored at the edge near your function. Links for each provider provided below.
* Use [statsig-node-lite](https://www.npmjs.com/package/statsig-node-lite) — This is a slimmed down version of the Node SDK, which includes only the essentials and dramatically improves initialization performance for cold-start requests. After initialization, evaluate with Node Lite's sync methods, such as `checkGateSync`, `getFeatureGateSync`, `getExperimentSync`, and `getLayerSync`.
* Persist a uuid — As always, you'll need some sort of user identifier that can be used to consistently assign a user to your test buckets. This can typically be solved by generating a uuid in your function and setting it to a cookie.
* Persist assignments in a cookie — Some customers will set assignments to a cookie for the purpose of a performance optimization, allowing your code to skip sdk calls if the user is already assigned to a test. This is best defined as a session-cookie (a cookie that expires when user closes their browser).
* Persist client instance — [This pattern](/guides/serverless#usage) allows the Statsig client instance to persists across requests when the edge function remains warm and will improve performance.
* Use [Target Apps](/sdk-keys/target-apps) — Target apps will allow you to sync a specific subset of experiments/gates to your edge function, reducing the footprint of your project config and improving performance. Target Apps are compatible with all of the "config sync" integrations.
* Consider peeking at experiment assignments and avoiding automatic exposure logging. You should only log exposure events once a user has been exposed to the treatment, otherwise your test results may become polluted with users that didn't see the treatment. In Node Lite, use the explicit exposure-disabled sync methods, such as `getExperimentWithExposureLoggingDisabledSync`, `checkGateWithExposureLoggingDisabledSync`, `getFeatureGateWithExposureLoggingDisabledSync`, `getLayerWithExposureLoggingDisabledSync`, or `getConfigWithExposureLoggingDisabledSync`. If you use the top-level `Statsig` wrapper, log the exposure later with `manuallyLogExperimentExposure`, `manuallyLogGateExposure`, `manuallyLogLayerParameterExposure`, or `manuallyLogConfigExposure`; if you use a `StatsigServer` instance directly, use `logExperimentExposure`, `logGateExposure`, `logLayerParameterExposure`, or `logConfigExposure`.
* Node Lite does not use the Node Core `EvaluationOptions` pattern for disabling exposure logging. See the current [top-level `Statsig` API](https://github.com/statsig-io/node-js-lite-server-sdk/blob/main/src/index.ts) and [`StatsigServer` API](https://github.com/statsig-io/node-js-lite-server-sdk/blob/main/src/StatsigServer.ts) for the full method lists.
* You should consider how this can be managed downstream in your application. All SDKs have a means of tracking exposures manually, and you can also consider using the [HTTP API for logging exposures](/http-api#log-exposure-event).
* If you choose to log exposures from your edge function, you should consider using the `context.waitUntil` method if supported by your edge provider ([examples](/server/nodejsServerSDK#environment-specific-setup)).
## Cloudflare Implementation
Cloudflare allows its users to easily stand up a serverless edge worker that will get invoked prior to cache lookup and also allow you to modify the response to the viewer. The Worker architecture gives you full code control over how you'd like to map test assignments to resources you should serve to the user, allow you to modify both the URL (serving as cache-key) and headers used to fetch your resource from the CDN, passing the modified request through to origin on cache-miss.
The Cloudflare Worker runtime allows you to install [Statsig Node Lite SDK](https://github.com/statsig-io/node-js-lite-server-sdk) as a dependency and use it to determine test assignments before fetching a given resource.
We offer both an [integration with Cloudflare KV](/integrations/cloudflare), and a pre-built [KV Data Adapter](https://github.com/statsig-io/cloudflare-data-adapter-node/tree/master), ensuring that SDK initialization is performant and doesn't depend on requests over the network back to Statsig.
## Fastly Implementation
Fastly Compute platform supports Functions at the Edge, affording customers the ability to handle assignment at the edge.
### KV (fully supported)
[Fastly's KV storage solution](https://www.fastly.com/blog/be-among-the-first-to-try-the-greatest-kv-store-ever-made) is touted as being highly-performant and is now their recommended solution over their legacy ConfigStore documented below.
Statsig offers both a Config-Sync for Fastly KV as well as a KV DataAdapter which can be found [here](/integrations/fastly).
### ConfigStore (not recommended)
We initially built the [integration with Fastly's ConfigStore](/integrations/fastly), which was their only offering at the time. ConfigStore values are limited to 8 kilobytes, which will be met rather quickly as the number of gates and tests in your project increases. This will be paired with our [Fastly Config Store Data Adapter](https://www.npmjs.com/package/statsig-node-fastly), allow the SDK to initialize from ConfigStore rather than making a request over the network back to Statsig.
### Recommended pattern
The Fastly pattern is a bit different than some of the other providers — as recommended by [the Fastly AB Testing guide](https://www.fastly.com/documentation/solutions/tutorials/ab-testing-edge-compute/#use-the-allocations-on-your-origin-server), it does not involve modifying the cache-key (resource URL), but instead attaching `Fastly-ABTest-` headers, which will tell your origin server how to render the resource, and the origin response should include a `Vary` response header to tell Fastly CDN what to cache. This approach is documented thoroughly by Fastly, and it's recommended that their guide serves as the source of truth for the design pattern.
### Fastly VCL Implementation
Their legacy Varnish-based platform only supports configuration based caching and minimal scripting at the edge using VCL scripting language.
Practically speaking, there is no Statsig SDK (or any SDK for that matter) support at the edge for this reason. In this instance, the Statsig SDK must be implemented on the origin server, and cache rules must be configured to force a cache-miss and allow assignments to take place on the origin server.
## AWS Implementation
AWS has a variety of serverless solutions, below we will detail the recommended pattern and various limitations associated with each.
### Lambda\@Edge Implementation
Lambda\@Edge are Lambda functions that are designed to be triggered by CloudFront events.
Lambda\@Edge implementations carry a few unique challenges:
* At the time of writing this, AWS does not offer a KV store solution compatible with Lambda\@Edge. Their [KeyValueStore](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/kvs-with-functions.html) offering is only compatible with Cloudfront Functions. This means, you will either have to:
* Use the default Statsig SDK initialization, which will incur a hit over the network to Statsig to load configurations
* Bundle your project config statically into the function package. You can consider using our [Config-Change Webhook](/integrations/event_webhook#config-change-webhooks) to automate this. You'll need to download the configuration JSON at the following URL in order to bundle it into your Lambda package: [https://api.statsigcdn.com/v1/download\_config\_specs/SERVER\_SDK\_KEY.json](https://api.statsigcdn.com/v1/download_config_specs/SERVER_SDK_KEY.json)
* Store your project config in S3 and use Cloudfront as means to serve it optimally when fetching it from your Lambda\@Edge function.
* Function size is capped at 1MB in package size (for viewer request and viewer response triggers, which is what is required for this setup).
* Lambda model uses [four events triggers](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-cloudfront-trigger-events.html), calling your function at various stages of the request lifecycle. For this use case, you’ll need to use two: `Viewer Request` and `View Response`. AWS provides documentation on how requests can be handled and manipulated [here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-at-the-edge.html).
#### Viewer Request function
Viewer Request will be called before cache lookup, and will be used to define a uuid, generate test assignment and modify the request URL via `Request.URI`. This type of function cannot modify response headers, so you must pass any assignment and uuid info through to the Viewer Response function in order to set cookies. Event structure for each event documented here.
#### Viewer Response function
Viewer Response function is responsible only for setting uuid and assignment cookies as needed.
### CloudFront Functions Implementation
SDKs are not supported here. Cloudfront Functions have 1ms max runtime and 10KB max function size. You’ll have to use Lambda\@Edge, or consider incurring Cache-misses to do assignment at origin.
## Akamai Implementation
[Akamai has a documented pattern](https://www.akamai.com/blog/developers/better-a-b-testing-with-edgeworkes-edgekv) of using EdgeWorkers and EdgeKV for running AB tests using cached content, providing both code samples, as well as an overview of the [architecture](https://www.akamai.com/solutions/edge/serverless-computing/use-cases). You’ll need to add the Statsig SDK to the worker function as a dependency and call it for assignment (rather than the rudimentary coin flip using `Math.random()` shown in their code examples).
You can now use our [Akamai Edge integration](/integrations/akamai), which includes an integration with EdgeKV as well as a Node package that has been tested and validated within Akamai edge runtime.
# Create your first feature flag
Source: https://docs.statsig.com/guides/check-gate
How to call checkGate in Statsig client and server SDKs to evaluate a feature gate, including parameters, return values, and exposure logging.
This tutorial walks you through how to check your first Feature Gate in Statsig from end to end. Feature Gates, also known as feature flags, are a way to safely control the rollout of new features to your users without deploying additional code. Common examples for using Feature Gates include shipping new UI elements, API endpoints, or product features.
By the end of this tutorial, you will have:
* Created a **Feature Gate** in the Statsig console, with **targeting rules** to enable the feature for a segment of Users
* Initialized a **Statsig Client SDK**
* Checked a single **feature gate** in your code using the `checkGate` function
## Prerequisites
1. A [Statsig account](https://console.statsig.com/sign_up)
2. An existing application you can integrate the Statsig Client SDK into
## Step 1: In the Statsig console
### Create a Feature Gate
For the purposes of this tutorial, we will pretend we are adding a Feature Gate to deploy a new UI element to a user with the "statsig.com" email domain. You can follow along with a specific feature if you have your own scenario in mind.
1. Navigate to [Feature Gates](https://console.statsig.com/gates) in the Statsig console.
2. Then, click on **Get Started** if you don't have any Feature Gates set up yet, or **Create** to create a new one.
3. Name your gate "Example Gate". This name will also be used to identify the Feature Gate later using the SDK.
4. Enter a description for your Feature Gate. It's good practice to describe it in a way that other teammates can easily understand. For example: "This Feature Gate is for launching an example feature for Statsig employees only."
### Create a targeting rule
In Statsig, when you create a Feature Gate, they are enabled by default. In other words, all users will be excluded from the feature until you add a rule that lets users "pass" the gate.
This means that in order to actually turn on this feature, you will need to add rules to target this Feature Gate to a specific set of folks. Let's walk through doing this in the console.
1. In the console, on the page for the Feature Gate you just created, click on **Add New Rule**.
2. Give this rule a **Name**, such as "Statsig Users Only".
3. Select **Email** as our targeting criteria so we can target users based on their email address.
4. In the User section of the dropdown, select the **Any Of (Case Insensitive)** operator, and then add `statsig.com` for our email-based user targeting.
5. Set the **Pass Percentage** to `100%`. Doing so ensures that all users with the `statsig.com` email domain will pass the Feature Gate and see the new feature.
6. Click **Add Rule** to add this rule to your Feature Gate.
7. Next, hit **Save** on the bottom right to commit these changes to the Feature Gate.
You can now test this feature gate by configuring the User object in the "Test Gate" section.
### Create a Client API Key
Now that you've set up the Feature Gate from the console, it's time to integrate it into your product with the Statsig SDK. We'll first need to create a new Client API key to use in our product.
1. Navigate to [**Keys & Environments**](https://console.statsig.com/api_keys) in the Statsig console. You can also find this by going to **Settings** at the bottom left of the Statsig console.
2. Scroll down to **API Keys**. Click on **Generate New Key**.
3. In the dropdown, select **Client**.
4. Copy the Client API Key you just created to your clipboard.
## Step 2: In your code
### Initialize the Statsig SDK
Now that we have our Client API Key, we can go ahead and integrate the Statsig Client SDK into our product. For the purposes of this tutorial, we will use the React SDK, but you can follow along with a different SDK if you prefer.
Statsig offers over 20 client and server-side SDKs. Check out the full list of [SDKs](/sdks/quickstart#all-sdks) to find the one that best fits your needs.
1. Install the Statsig React SDK using your preferred package manager. For this tutorial, we will use npm.
```bash npm theme={null}
npm install @statsig/react
```
2. Import the SDK in your `App.js` file:
```tsx Import SDK theme={null}
import { StatsigProvider } from "@statsig/react-bindings";
```
3. Next, wrap your app's content within the `StatsigProvider` component. In the following code snippet, we're also creating a [User](/concepts/user) object so that we can target our Feature Gate.
```tsx Setup Provider theme={null}
function App() {
return (
Hello world
);
}
export default App;
```
4. Make sure to also replace `client-KEY` with the Client API Key you copied in Step 3.
### Check your Feature Gate
Finally, you can now evaluate a Feature Gate in your product code by getting the client with the `useStatsigClient` hook, and then calling `checkGate`. If you're not sure yet about where and how you want to place your flag, check out our doc on [Best Practices for feature flags](/feature-flags/best-practices).
1. Add the following code to your `App.js` file. In this snippet, the `example_gate` is the name of the Feature Gate you created in Step 1.
```tsx Check Gate theme={null}
const { client } = useStatsigClient();
return (
Gate is {client.checkGate('check_user') ? 'passing' : 'failing'}.
);
```
2. Run your app and see the result! The app should render the text "Gate is passing" since we already [Created a targeting rule](#create-a-targeting-rule) that targets all users with the `statsig.com` email domain, and we are using that same email domain in this client's User object.
3. Once you've set up your gate, you can easily [monitor the impact of your new feature rollout](/feature-flags/view-exposures) or [manage flag lifecycles](/feature-flags/feature-flags-lifecycle).
## Next steps
In this tutorial, we configured a simple feature flag. You can monitor basic metric impacts with this, but if you want to do more complex feature rollouts or metric analysis, continue to the next tutorial to run your first A/B test in Statsig.
# Guide to General CMS Integrations
Source: https://docs.statsig.com/guides/cms-integrations
Integrate Statsig with CMS platforms like Contentful, Webflow, and Framer to run content experiments and personalize pages without redeploying code.
### Using Statsig with a CMS
One fairly common question we get is around how to use Statsig with an existing CMS. While we also offer a no-code solution - [Sidecar](/guides/sidecar-experiments/introduction),
there are clever ways you can set up your code to integrate your CMS and Statsig so you can write code once, and then run experiments on
arbitrary combinations of parameters in the future.
We recommend using [Layers](/layers) to wire this up, so take some time to read up before continuing.
Layers are a unit of mutual exclusion between experiments in Statsig. Every user participates in only one experiment in a layer at any given time.
As such, we recommend you set up a layer for each surface you will be experimenting on with the help of your CMS
For the remainder of this guide, we will assume you are experimenting on a single surface - but repeat these steps if you plan to experiment on separate surfaces like your landing page, product page, blog, etc.
For the sake of example, let's assume we are parameterizing the Statsig landing page to plug in our CMS.
"); // note that you have a default value in code as well
// exact library and function call will map to your cms client library
cmsClient.getEntry(titleID);
```
If you repeat this for the subtitle, CTA, and all the other parameters on your landing page, they all become dynamic!
When you put a new CMS ID into statsig, your code will pull the updated content for that section.
Now, you can create new content in your CMS, and create an experiment in Statsig to try out that new variant. After creating the content, come back
to your layer and hit "Create Experiment in Layer":
Note that changes in nested configs are not listed (e.g. if this gate references another gate or segment via a "Passes Target Gate" or "User in Segment" condition, changes to the other gate or segment will not show in the history view).
## Audit Logs
Audit logs will show you the change history for all available entities across the entire project. These audit logs are stored indefinitely and you can filter by entity type or name, tag, target app, environment, action, and user who triggered the action.
Audit logs can be accessed programmatically or though the Statsig Console UI in **Settings** > [Audit Logs](https://console.statsig.com/audit_logs).
# Guide to Contentful
Source: https://docs.statsig.com/guides/contentful
Integrate Statsig with Contentful to run experiments on CMS-managed content, including connecting accounts, mapping variants, and tracking metrics.
The Statsig Contentful integration lets you create A/B/n tests and test different content blocks against each other directly from within Contentful. You can assess impact using business metrics on Statsig Cloud or Warehouse Native. Marketers can optimize content, obtain insights, and iterate continuously right from within Contentful.
* Run experiments on CMS content without engineering involvement
* Configure content to serve with each variation
* No performance penalty or flicker
The Statsig Contentful app will add a Statsig container that is connected to an experiment in Statsig. The user can then add Content Blocks to that container to start a test. The Statsig Contentful app lets marketers measure progress towards business objectives by testing content for lift in any core business metrics configured in Statsig.
## Integrating with Contentful
Our Contentful Marketplace App is publicly available. You can find it [here](https://www.contentful.com/marketplace/statsig). To use this integration effectively, you will need to do setup around the Contentful marketplace app, your Content types, and your actual codebase. These are one-time setups, then you will be able to seamlessly run A/B/n tests directly inside Contentful.
### Setting up the Statsig Marketplace App
* Navigate to the Marketplace in Contentful, and find the Statsig app. Click 'Install'.
* Statsig will prompt you to enter a Console API Key. You can find an existing Console API Key in your Statsig project under Settings > Keys & Environments. It's important that this key is **of type 'Console', and has read and write permissions**. Feel free to generate a new key of type 'Console' if a suitable one does not already exist for your project.
Ensure your experiment setup is finalized before publishing, as this will create your experiment inside of Statsig.
This guide assumes you have an existing Statsig account. Please go here to create a new free account if you don't already have one: [https://statsig.com/signup](https://statsig.com/signup)
### Step 1: Create an experiment
Start by creating a new Experiment on Statsig console. Put in a name and leave the rest of the fields empty/default. For the purposes of this walkthrough, that should do.
These steps also apply to feature gates, allowing you to partially roll out features based on custom Unit IDs.
***
### Step 1: Add `companyID` as a Custom Unit ID
1. **Log into the Statsig Console**: Head over to [Statsig Console](https://console.statsig.com/) and navigate to **Project Settings**.
2. **Find Custom Unit IDs**: Under **Manage Account** > **Info**, look for the **Custom Unit IDs** section.
In Statsig, feature flags are called feature gates . The terminology is interchangeable throughout this guide.
Both feature gates and experiments create control/test groups. Use this guide to pick the right tool for your launch and measurement goals.
***
## Quick Guidance
* **Choose a feature gate** when you want to roll out a feature gradually or monitor impact as you ramp.
* **Choose an experiment** when you need to compare multiple variants and quantify the lift across metrics.
***
## Key Differences
### Variants
* **Feature gate** → Two experiences only: pass vs. fail.
* **Experiment** → Any number of variants.
When viewing gate exposures you’ll see three buckets: Pass , Fail , and Fail – Not in Analysis . Only the balanced subset of the fail group is used for metric comparisons. Learn more in the [gate exposure methodology](/feature-flags/view-exposures#gate-exposures).
### Return Values
* **Feature gate** → Boolean (`true`/`false`) so your application toggles code paths.
* **Experiment** → JSON config that describes the variant (colors, copy, thresholds, etc.).
### Ramping knobs
* **Feature gate** → Adjust Pass % to send more traffic to the new experience. You can go beyond 50/50 (e.g. 99% vs 1%).
* **Experiment** → Adjust Allocation % to enroll more users, but splits cap at 50/50.
Once a user is assigned, neither control reshuffles existing users—you can safely ramp without re-bucketing.
If your app collects other relevant attributes (e.g., device type, region), pass them in the `user` object to improve experiment precision.
## Step 3 (Optional): Update User Info for Logged-in Users
When a user signs in or creates an account, call the SDK’s updateUser method to attach userID and other logged-in attributes. This allows user-level experiments and gates to evaluate with the authenticated identifier.
### Example (JavaScript):
```javascript theme={null}
const updatedUser = {
...user, // continue to send the deviceID!
userID: loggedInID,
email: signUpEmail
};
// Update the user object
await client.updateUserAsync(user);
```
Adding userID after login enables user-level experiments/gates to target and evaluate using userID. *Device-level* experiment evaluations remain based on stableID (or deviceID) and are not changed by adding userID, as long as you continue to pass that identifier as well! This preserves consistency of device-level bucketing.
***
# Guided Tutorial
Source: https://docs.statsig.com/guides/first-dynamic-config
Step-by-step tutorial to create your first Statsig dynamic config, including building a flexible homepage banner that you can update without redeploying.
Now that you have created your Statsig account, and perhaps even your [first feature](/guides/first-feature), this guide will help you make your app a bit more flexible with Dynamic Config.
Whether it be for server-side rendered UI, rate limiting configurations, ranking systems, algorithms, etc. Dynamic Config can help you update configurations on the fly.
This guide focuses on a client-side example, as it is easier to illustrate how Dynamic Configs work and can be used. You can and still should use Dynamic Config on the server side as well.
In this guide, we will be building a front page banner - something that may show up on an ecommerce site to advertise an upcoming sale, for instance.
Here, I will apply it to a stripped down version of the Statsig homepage. It will look something like this green banner when we are finished:
**Codepen Example**
This example is implemented in [a codepen](https://codepen.io/tore-statsig/pen/mdWEajo) where you can see the actual code, or fork it to quickly test your own Dynamic Configs.
### Step 1 - Create a new Dynamic Config
Start by creating a new Dynamic Config. Dynamic Configs live under the "Feature Management" tab in the Statsig Console.Pick a name related to the set of variables this config will hold. Since we are building a homepage banner, let's call it "Banner Config":
", {});
```
Now, let's fetch our config and construct the banner:
```js theme={null}
const bannerConfig = client.getDynamicConfig("banner_config");
const text = bannerConfig.get("text", null);
const backgroundColor = bannerConfig.get("backgroundColor", "black");
const color = bannerConfig.get("color", "white");
const fontSize = bannerConfig.get("fontSize", 14);
if (text == null) {
return;
}
const banner = document.getElementById("homepageBanner");
const bannerText = document.createElement("p");
banner.style.display = "block";
bannerText.innerHTML = text;
banner.style.color = color;
banner.style.fontSize = fontSize + "px";
banner.style.backgroundColor = backgroundColor;
banner.appendChild(bannerText);
```
Note that this js relies on the html page having the homepageBanner div:
```html theme={null}
```
And that's it! With just a handful of javascript, we integrated with the Statsig SDK and started using the Dynamic Config we created. Now, without updating our website, we can add a new rule to the Dynamic Config and return a completely new banner to a different set of people!
Here's what it looks like for me, viewing this webpage in chrome on a Mac:
Statsig refers to feature flags as feature gates across the console and SDKs. The terms are interchangeable throughout this guide.
Once your Statsig account is ready, follow the steps below to create and test-drive a new feature gate.
Navigate to the [Feature Gates page](https://console.statsig.com/gates) and click Get Started (or Create if you already have gates).
Mobile Registration with a note about the new mobile sign-up flow.
New gates default to returning false until you add targeting. Click Add New Rule , choose Operating System → Any of , and select Android and iOS . Set the pass percentage to 100% and click Add Rule , then Save .
Layer on a second rule for your team—for example Email → Contains any of with your company domain—so employees can exercise the feature regardless of device.
Head to [Project Settings → API Keys](https://console.statsig.com/api_keys) and copy the Client API key . Keep server secret keys on backends only, and use console API keys for programmatic configuration work.
Statsig supports many platforms—see [Client SDK options](/sdks/getting-started) for alternatives. This walkthrough uses the browser SDK so you can experiment directly in DevTools.
Paste the snippet below into the browser console on any site to fetch the SDK from jsDelivr:
```js theme={null}
const script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/@statsig/js-client@3/build/statsig-js-client+session-replay+web-analytics.min.js';
document.head.appendChild(script);
```
Replace YOUR\_SDK\_KEY with the client key from Step 4 and run:
```js theme={null}
const client = new window.Statsig.StatsigClient('YOUR_SDK_KEY', {});
await client.initializeAsync();
```
Then call:
```js theme={null}
client.checkGate('mobile_registration');
```
You should see false because the current session is not mobile and doesn’t use the employee email domain.
Enable the mobile device toolbar in Chrome DevTools.
true for the mobile profile.
Switch DevTools back to the desktop view and update the user with a company email:
```js theme={null}
await client.updateUserAsync({ email: 'teammate@statsig.com' });
client.checkGate('mobile_registration');
```
The gate passes again thanks to the email rule.
```js theme={null}
client.flush();
```
Open the gate’s Diagnostics tab to confirm each exposure, including the failing desktop check, mobile pass, and employee pass.
## Use the gate in production
Wrap feature logic in a gate check so only targeted users see the experience:
```js theme={null}
if (client.checkGate('mobile_registration')) {
show(mobileRegistrationPage);
} else {
show(oldRegistrationPage);
}
```
Happy feature gating!
# Integrating Statsig with Framer
Source: https://docs.statsig.com/guides/framer-analytics
Integrate Statsig product analytics with Framer sites to autocapture events, track conversions, and run no-code A/B tests on Framer-built pages.
## Introduction
Framer allows you to create interactive prototypes and websites with ease. By integrating Statsig, you can capture user behavior, and log custom events, directly within your Framer projects.
This guide will walk you through integrating Statsig into your Framer project using the JavaScript SDK.
## Installation
To start tracking user interactions with Statsig in your Framer project, follow these steps:
1. Copy your web snippet from Statsig, replacing "YOUR\_CLIENT\_KEY" with a Client API Key from your Statsig project, which you can find at [console.statsig.com/api\_keys](https://console.statsig.com/api_keys).
```html theme={null}
```
Go to your Framer project settings by clicking the gear icon in the top right corner - note you'll have to be on the "mini" site plan or above above to enable custom code.
In the General tab, scroll down to the Custom Code section and paste your Statsig snippet into the end of `` tag section. Save your changes and publish your site, then Statsig will be ready to track basic user interactions.
## Capture Custom Events
To track custom events within your Framer project, you can use window\.statsig.logEvent() inside a custom component.
Go to the Assets tab in your Framer project.
Click the plus icon next to Code and create a new code component.
Name the file CaptureButton and select New Component.
Replace the default code in the file with the following:
```js theme={null}
export default function CaptureButton() {
const handleClick = () => {
window.statsig.logEvent("click", "button");
};
return (
Click me
);
}
```
Save your changes (Cmd/Ctrl + S).
Drag your new CaptureButton component from the Code tab onto your Framer page, where you'd like it.
After publishing your site and clicking the button, after a couple minutes you should see the event show up in your Statsig metrics.
# Log your first custom event
Source: https://docs.statsig.com/guides/logging-events
How to log custom events to Statsig from client and server SDKs, including event names, values, and metadata used for metrics and analytics.
The first step towards building better products is tracking events. As the saying goes, "If you can't measure something, you can't understand it. If you can't understand it, you can't control it. If you can't control it, you can't improve it."
Regardless of if you plan to use Statsig for web or product analytics, or for experimentation, defining the key events and metrics for your product is the best place to start. Event data is consumable in [Metrics Explorer](/product-analytics/overview), can be turned into [custom metrics](/metrics/how-metrics-work), visualized in [dashboards](/product-analytics/dashboards), and used in [experiment results](/metrics/pulse) to show the impact of your experiments on the metrics you care about.
We try to make this easy in a few ways:
1. Our web SDKs offer [autocaptured web analytics](/webanalytics/overview) to automatically log common events like pageviews, clicks, and more.
2. We offer [integrations](/integrations/introduction) to connect your existing event data in Segment, mParticle, and other sources.
3. All of our client and server SDKs provide a simple `logEvent` API to instrument your own events in your app or webserver.
For general guidance on event logging and core concepts, read on or jump to the "Logging events via SDKs" section below.
## Identifying Users and the "StatsigUser" object
Many analytics platforms have a concept of "identifying" a user. In Statsig, this is the StatsigUser object that is set a initialization time in client SDKs, or with each event in Server SDKs.
The [`StatsigUser`](/concepts/user) is a set of properties that describe the user. It roughly has the same json definition across all SDKs and integrations:
```json StatsigUser Object theme={null}
{
"userID": "123",
"customIDs": {},
"email": "user@example.com",
"ip": "192.168.1.1",
"userAgent": "Mozilla/5.0...",
"country": "US",
"locale": "en-US",
"appVersion": "1.0.0",
"custom": {},
"privateAttributes": []
}
```
The `userID` field is reserved for a unique identifier for the user. This should be the ID of the logged in user.
`customIDs` are explained in "Group Analytics" below.
The other fields are fairly self explanatory, and power not just targeting and evaluation for feature flags, but can also be used for custom metrics and data queries in metrics explorer.
## Group Analytics
Another core concept in analytics is the idea of different "groups". For example, a user could belong to a certain company, organization, page, subreddit, facebook group, etc.
In Statsig, groups are represented by the `customIDs` field. This is a dictionary that can contain multiple IDs for a single user. For example, a user could have the following customIDs:
```json Group Example theme={null}
{
"userID": "123",
"customIDs": {
"companyID": "456",
"projectID": "abc"
}
}
```
Statsig computes all metrics at the user level, but also for each custom identifier. This means you can run experiments at a company level, where all users in a company will get the same experience, and compare the impact of company level metrics.
You can also use metrics explorer to slice and dice metrics at the company level, rather than the user level, if you set up a customID for it. For example, in the Statsig project, I can look at the console page views at a user or company level in metrics explorer:
You must provide the set of all IDs on each StatsigUser object.
## Best practices
### Set all known IDs on each StatsigUser object
In order to generate metrics for each user/group, Statsig needs to know the set of all IDs on each StatsigUser object. Whether this is at client sdk initialization time, or when calling `logEvent` in a server SDK, you need to pass each identifier for the user for it to contribute to those metrics.
If you use a logged out identifier for anonymous users, you should continue to pass that identifier even after the user logs in and you populate the logged in userID. This will enable any gates or experiments on the logged out identifier to continue to bucket the user appropriately, and calculate metrics at both the logged out and logged in level.
### Deduplicating custom events
At the moment, Statsig does not provide a way to deduplicate custom events that you log.
### Naming conventions
The most important aspect is consistency - you should pick a convention and stick with it. Your events and metrics catalogue can quickly become messy and difficult to navigate when there are similar events with different conventions. Technically speaking, Statsig can accept any type of name convention - E.g.; "Page View", "PageView", "Page-view" and "page\_view". Practically speaking, we recommend using "page\_view" — that is, to avoid spacing, and to use all lowercase characters. One thing to note, special characters cannot be used in event names. Statsig drops events that match this regex/contain this character set: `"\\[\]{}<>#=;&$%|\u0000\n\r"`. This will ensure there are no duplicate entries with different casing, and ensure other downstream systems connected via integration can accept and process the event properly given this is the most universally-compatible convention.
### What to measure
In general, if you're doing normal experimentation/product analytics, you'll want events that correspond to user actions. How you classify them will depend on what you're trying to do. In general, keep the following in mind:
1. Events should not have high cardinality if you don't have a lot of users. Otherwise, experimental/metrics data will be too sparse. E.g.; an eCommerce website should not log a separate event name for every single product page. But instead, should have a generic "product\_page\_view" event and include contextual page information within the `optional_event_metadata` object.
2. If you have a well-defined user funnel, you'll want each step to be a separate event.
3. If you have a less defined user journey, you'll want to log generic events (eg. "page\_view"), and add more details to either the value field (which should be the primary dimension of interest), or the `optional_event_metadata` object.
## Logging events via SDKs
All our SDKs provide a very simple API to log events. They look like this:
```js JavaScript theme={null}
statsig.logEvent(
event_name,
optional_event_value,
optional_event_metadata
);
```
Where event name describes a notable event in your product, like `sign_up`, `achievement_unlocked`, `add_to_cart`, `check_out`, etc.
These events can optionally take an event value. For instance, you can use this field to specify the type of achievement that was unlocked, or the name of the product that was added to cart, or the price of the item that was purchased.
In experiments, the "value" will generate an automatic breakdown of the event if there are fewer than 8 distinct values.
And finally, the metadata field allows you to specify even more details about the event. Here's an couple examples of how a `logEvent` call looks like:
```js JavaScript Example theme={null}
statsig.logEvent(
'add_to_cart', // Name
19.99, // Price
{
item_id: 'BC22010',
cart_size: '2',
user_segment: 'first_time_purchaser',
}
);
```
```csharp C# Example theme={null}
StatsigClient.LogEvent(
"level_completed", // Event Name
11, // Level number
new Dictionary()
{
{ "score", "452" }
}
);
```
**Size limits on event payload**
There are limits to how large each event field can be.
Object fields have an overall limit of 4096 on its stringified length.
String fields have a limit of 64 on its length.
See the [SDK reference](/sdks/getting-started) for more details on logging events in the language of your choice.
# Migrate your analytics data from Amplitude
Source: https://docs.statsig.com/guides/migrate-from-amplitude
Step-by-step guide to migrating product analytics from Amplitude to Statsig, including event mapping, user identity, and metric parity.
Migrating from Amplitude to Statsig is a strategic choice. Statsig is an all-in-one platform that offers analytics, experimentation, and feature flagging under one umbrella. Using all these products in a single tool is much more powerful.
Migrating amplitude data into Statsig usually involves two steps: export and ingest. This guide provides the essentials. For anything beyond these basics, please contact us.
## Step 1. Export your data from Amplitude
Amplitude offers a few different export methods. Pick the one that matches your data size and setup:
**1. S3 Export**
For high volume backfills, you can dump your Amplitude data into an S3 bucket.
**2. Warehouse Export**
If your Amplitude data is already in Snowflake, BigQuery, or Redshift, you can skip file downloads. Statsig can ingest directly from these warehouses (see Step 2.1)
**3. Export API**
Use Amplitude's Export API to pull gzipped JSON
* **Limit**: 4 GB per request so use hourly windows for large ranges
* **Example**:
```bash theme={null}
curl --location --request GET 'https://amplitude.com/api/2/export?start=&end=' \
-u '{api_key}:{secret_key}'
```
**4. UI Download (CSV/JSON)**
Go to Organization Settings → Project → Export Data
* Best for small datasets or initial testing
## Step 2. Transform your data
Amplitude and Statsig store events in slightly different formats. To make your Amplitude exports work in Statsig, you'll need to map your Amplitude data to Statsig's format. This step is required irrespective of how you choose to import data into Statsig in the next step.
| Amplitude field | Statsig field |
| ------------------ | ---------------------------- |
| `event_type` | `event` |
| `event_time` | `timestamp` (ms since epoch) |
| `user_id` | `user.userID` |
| `device_id` | `user.stableID` |
| `event_properties` | `metadata` |
| `user_properties` | `user` fields |
**Before transform**
```json theme={null}
// Amplitude event
{
"event_type": "purchase",
"user_id": "123",
"device_id": "device_abc",
"event_time": "2023-08-17T00:00:00Z",
"event_properties": {
"amount": 25,
"currency": "USD"
},
"user_properties": {
"plan": "premium"
}
}
```
**After transform**
```json theme={null}
// Statsig event
{
"event": "purchase",
"user": {
"userID": "123",
"stableID": "device_abc",
"plan": "premium"
},
"timestamp": 1692230400000,
"metadata": {
"amount": 25,
"currency": "USD"
}
}
```
## Step 3. Import into Statsig
Once your data look like Statsig events, you can start to bring them in. There are a few paths to import your data depending on how you exported:
| If you exported from Amplitude via... | Import into Statsig using... | Best when... |
| ------------------------------------- | ---------------------------- | ------------------------------------------------------- |
| S3 export | S3 ingestion | You're backfilling large datasets |
| Warehouse (Snowflake/BQ/Redshift) | Warehouse ingestion | Your Amplitude data already lives in a warehouse |
| Export API | Event Webhook | You're moving a few days/weeks of data programmatically |
| UI download (CSV/JSON) | Event Webhook | You're testing or moving a small slice of data |
**S3 ingestion**
* Just ensure the files are transformed to Statsig schema, in Parquet/JSON/CSV form, and then follow [Statsig's S3 ingestion](/data-warehouse-ingestion/s3) steps.
* Please note that you need to shard your Amplitude raw data into 1 day's data per directory for to be able into Statsig
**Warehouse ingestion**
* [Connect your warehouse to Statsig](/data-warehouse-ingestion/introduction)
* Point Statsig at a query that outputs events in the expected schema
* Statsig ingests on a recurring schedule
**UI download or Export API**
The simple way to get these events into Statsig is to replay them through the [Event Webhook](/http-api#post-event-webhook).
Think of it as a direct POST call: you take each row or JSON object, reshape it, and send it to Statsig one at a time or in small batches.
This is best for test runs or initial migrations, not for millions of events.
```bash theme={null}
curl -X POST https://api.statsig.com/v1/webhooks/event_webhook \
-H "Content-Type: application/json" \
-H "STATSIG-API-KEY: $STATSIG_SERVER_SECRET" \
-d '{
"event": "signup",
"user": { "userID": "abc" },
"timestamp": 1692230400000
}'
```
## Not sure where to start or need help?
If you're unsure how to approach Amplitude migration, please reach out to our team. We have worked with ex-Amplitude customers closely in the past to offer them hands on migration support.
We're always happy to discuss your team's individual needs or any other question you have - reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack).
# LaunchDarkly Migration Guide
Source: https://docs.statsig.com/guides/migrate-from-launchdarkly
Step-by-step guide to migrating feature flags and rollouts from LaunchDarkly to Statsig, including flag mapping, SDK swap, and rule recreation.
## Overview
Migrating from LaunchDarkly to Statsig is a strategic move. It can lead to efficient feature flag management and a stronger experimentation culture. By following this guide, you'll be well equipped to make the transition with confidence.
We will cover the following topics in this guide:
1. Conceptual differences between LaunchDarkly and Statsig
2. Deciding what to migrate vs. not
3. Importing flags into Statsig
4. Flipping evaluation from LaunchDarkly to Statsig
5. How to run the migration process
## Conceptual differences between LaunchDarkly and Statsig
It is important to understand a few fundamental differences in how LaunchDarkly and Statsig structure their feature management data models:
**Environment**: LaunchDarkly treats environments as top level concept where flags and segments must be duplicated and managed separately across environments. In Statsig, we have a centralized model where flags/configs handle environment-specific logic in their targeting rules.
**Flag types**: LaunchDarkly uses a mix of boolean, multivariate, and JSON flags. Statsig distinguishes between Feature Gates (boolean) and Dynamic Configs (typed multivariate configs with JSON values).
**Targeting**: LaunchDarkly relies on Contexts to evaluate flags. Statsig evaluates based on what we call a StatsigUser object.
#### Side by side comparison
| LaunchDarkly concept | Can we migrate? | Statsig notes |
| ------------------------------------ | --------------- | ---------------------------------------------------------------------------------------- |
| Project | ✅ Yes | Convert to Project |
| Environment | ✅ Yes | Convert to Environment (mark critical as production in Statsig) |
| Boolean Flags | ✅ Yes | Convert to Feature Gates |
| String, Number, and JSON Flags | ✅ Yes | Convert to Dynamic Configs |
| Segments | ✅ Yes | Convert to Segments (Big ID list segments won't be imported) |
| Targeting Rules | ✅ Yes | Convert to Rules |
| Context kind | ✅ Yes | Convert to Custom Unit ID in Statsig |
| Context attribute | ✅ Yes | Convert to Custom Fields in Statsig |
| Flag owner, tags, teams, and history | ❌ No | Statsig does not preserve any metadata or historical versions of a flag during migration |
#### User Context mapping example
LaunchDarkly supports multi-kind, structured user contexts. Statsig requires a user object to achieve this. In Statsig, User ID or Custom ID is equivalent to LD's key. Known top-level fields in Statsig include userID, email, ip, userAgent, and custom. All other fields go under the custom object.
**Example 1: LD User context to Statsig User object conversion**
```javascript theme={null}
// 1 - LD User context
{
"kind": "user",
"key": "user-key-123abc",
"name": "Anna",
"email": "anna@globalhealthexample.com",
"organization": "Global Health Services",
"jobFunction": "doctor",
"device": "iPad"
}
// 1 - Statsig User object
{
"userID": "user-key-123abc",
"email": "anna@globalhealthexample.com",
"custom": {
"name": "Anna",
"organization": "Global Health Services",
"jobFunction": "doctor",
"device": "iPad"
}
}
```
**Example 2: LD Multi context kind to Statsig User object conversion**
```javascript theme={null}
// 2 - LD Multi context kind
{
"kind": "multi",
"user": {
"key": "user_abc",
"name": "Anna",
"email": "abc@company.com",
"region": "us-east"
},
"org": {
"key": "org_xyz",
"tier": "enterprise"
}
}
// 2 - Statsig user object
{
"userID": "user_abc",
"email": "abc@company.com",
"customIDs": {
"org_id": "org_xyz"
},
"custom": {
"user_name": "Anna",
"user_region": "us-east",
"org_tier": "enterprise"
}
}
```
In Statsig, email is a top-level reserved field for the user object, so it should be placed directly as email (not user\_email). Statsig expects fields like userID, email, ip, and userAgent at the top level for user targeting and analytics.
## Deciding what to migrate vs. not
Before you begin migrating flags from LaunchDarkly to Statsig, take this opportunity to audit your flags in the current system and do a cleanup. Many organizations accumulate flag debt over time - from stale flags, dead experiments, deprecated toggles, and legacy kill switches. Migration is a chance to start fresh with only what's valuable and active.
Utilize filters such as 'Lifecycle' and 'Type' in LaunchDarkly to determine which flags are worth importing into Statsig.
Below is a decision framework you can use to decide which flags to import into Statsig. Our migration script follows this framework by default but you can alter it if you need.
We will only cover importing raw events into Statsig. We don't support importing user/group profiles, dashboards, reports, etc.
Once your raw events are in the Statsig project, you can re-create your critical dashboards here.
## Step 1. Export your data from Mixpanel
Mixpanel offers a few different export methods. Pick the one that matches your data size and setup:
**1. CSV Export**
Export small batches of events as CSV via the Events tab → query events → click "Export" button.
**2. Export API**
Use Mixpanel's [Raw Event Export API](https://developer.mixpanel.com/reference/raw-event-export) to pull JSONL data:
* **Limit**: Export one day's data at a time for optimal performance
* **Format**: JSONL where each line is a valid JSON object
```bash theme={null}
curl --location --request GET 'https://data.mixpanel.com/api/2.0/export?from_date=2023-01-01&to_date=2023-01-01' \
-u '{project_id}:{service_account_secret}'
```
**3. Data Pipelines (Bulk Export)**
For large data volumes, use Mixpanel's [Data Pipelines](https://docs.mixpanel.com/docs/data-pipelines) feature to export to:
* Cloud Storage (AWS S3, Google Cloud Storage, Azure Blob Storage)
* Data Warehouse (BigQuery, Redshift, Snowflake)
## Step 2. Transform your data
Mixpanel and Statsig store events in slightly different formats. Map your Mixpanel data to Statsig's format:
| Mixpanel field | Statsig field |
| ------------------------------------------------ | ---------------------------- |
| `event` | `event` |
| `properties.time` | `timestamp` (ms since epoch) |
| `properties.distinct_id` or `properties.user_id` | `user.userID` |
| `properties.device_id` | `user.stableID` |
| `properties.*` (other fields) | `metadata` |
**Before transform**
```json theme={null}
// Mixpanel event
{
"event": "Signed up",
"properties": {
"time": 1618716477,
"distinct_id": "user-123",
"device_id": "xyz",
"Referred_by": "Friend",
"URL": "website.com/signup"
}
}
```
**After transform**
```json theme={null}
// Statsig event
{
"event": "Signed up",
"user": {
"userID": "user-123",
"stableID": "xyz"
},
"timestamp": 1618716477000,
"metadata": {
"Referred_by": "Friend",
"URL": "website.com/signup"
}
}
```
## Step 3. Import into Statsig
Once your data looks like Statsig events, you can start bringing them in:
| If you exported from Mixpanel via... | Import into Statsig using... | Best when... |
| --------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------- |
| S3 export | [S3 ingestion](/data-warehouse-ingestion/s3) | You're backfilling large datasets |
| Warehouse (Snowflake/BigQuery/Redshift) | [Warehouse ingestion](/data-warehouse-ingestion/introduction) | Your Mixpanel data already lives in a warehouse |
| Export API | [Event Webhook](/http-api/overview) | You're moving a few days/weeks of data programmatically |
| CSV download | [Event Webhook](/http-api/overview) | You're testing or moving a small slice of data |
**Event Webhook (for API/CSV exports)**
```bash theme={null}
curl -X POST https://api.statsig.com/v1/webhooks/event_webhook \
-H "Content-Type: application/json" \
-H "STATSIG-API-KEY: $STATSIG_SERVER_SECRET" \
-d '{
"event": "Signed up",
"user": {
"userID": "user-123",
"stableID": "xyz"
},
"timestamp": 1618716477000,
"metadata": {
"Referred_by": "Friend",
"URL": "website.com/signup"
}
}'
```
**Important notes:**
* **S3 ingestion**: Shard your Mixpanel data into 1 day's data per directory for Statsig
* **Scale gradually**: After small tests, backfill in chunks to manage loads
* **Future tracking**: After historical import, switch Mixpanel code calls to Statsig SDKs
## Not sure where to start or need help?
If you're unsure how to approach Mixpanel migration, please reach out to our team. We have worked with other Mixpanel customers in the past to help them switch over to Statsig.
We're always happy to discuss your team's individual needs or any other question you have - reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack).
# Migration Overview
Source: https://docs.statsig.com/guides/migration-overview
Overview of migration paths to Statsig from other feature flagging, experimentation, and product analytics platforms with planning checklists.
Statsig combines feature flags, experimentation, and product analytics in one platform. Migrating ensures your data, flag, experiments, and decision workflows live in a single source of truth.
This guide outlines the overall migration process. For provider-specific steps (Amplitude, LaunchDarkly, etc.), see our dedicated guides.
## Migration Phases
### 1. Audit & Plan
* Identify the datasets, events, and feature flags you want to move
* Decide what needs full historical backfill vs. what can start fresh
* Document any dashboards or KPIs that need rebuilding in Statsig
### 2. Set Up Live Data
* Implement Statsig SDKs to start streaming new events and feature flag evaluations
* Validate critical events are firing with the correct schema
* Use Statsig for the newly recorded events and flags
### 3. Import Historical Data
* Export data from your existing tool (S3 or warehouse is preferred)
* Transform the schema to Statsig's event format (`event`, `user`, `timestamp`, `metadata`)
* Import via Statsig's Event Webhook, S3 ingestion, or warehouse ingestion
### 4. Validate & Decommission
* Compare metrics between your legacy tool and Statsig to ensure parity
* Rebuild dashboards and charts in Statsig
* Decommission old pipelines once Statsig is your single source of truth
## Best Practices
* **Start small**: Run a pilot project or test migration before backfilling all history
* **Align IDs early**: Ensure `userID` and `stableID` mapping is consistent. Identity mismatches are the most common failure point
* **Shard historical imports**: Break large datasets into daily partitions for stability
* **Rebuild insights intentionally**: Don't port all events and flags directly. Use migration as a chance to clean up stale data
* **Plan change management**: Teams need time to adjust workflows, queries, and dashboards so migrate for 1-2 teams before championing in the broader org
## Provider-Specific Guides
* [Migrate from Amplitude](/guides/migrate-from-amplitude)
* [Migrate from Mixpanel](/guides/migrate-from-mixpanel)
* [Migrate from LaunchDarkly (Feature Flags)](/guides/migrate-from-launchdarkly)
* Additional guides coming soon
## Get Help
Our team has helped many customers move off other tools so that everything is in Statsig. For tailored guidance, reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack).
# Open Source Script
Source: https://docs.statsig.com/guides/open-source-script
Use the open-source Statsig migration scripts to move feature flags, experiments, and metrics from third-party platforms into your Statsig project.
[This package](https://github.com/statsig-io/migrations) is designed to help automate migration of feature flags from LaunchDarkly to Statsig. It fetches feature flags from LaunchDarkly, translates them into Statsig's format, and creates corresponding feature gates in Statsig.
## Considerations
This script should work out of the box. It's recommended you start with a test environment of 5-10 flags. However, before running the script on a large scale, consider the following:
* **IMPORTANT**: If you don't need to customize this import script, you can just use [Statsig's in-console tool](/guides/ui-based-tool)
* The script uses a tag `Imported from LaunchDarkly` to identify migrated flags in Statsig. Ensure this tag is unique and recognizable.
* The script includes a function to delete all Statsig feature gates with a specific tag. Use this with caution to clean up after a test or failed migration.
* The script requires API keys for both LaunchDarkly and Statsig, which should be kept secure.
## Installation
To run the script, you need Node.js and npm installed on your system. You can execute directly:
```bash theme={null}
npx @statsig/migrations --from launchdarkly --launchdarkly-project-id default
```
## Configuration
* Provide your [LaunchDarkly API key](https://docs.launchdarkly.com/home/account/api) and [Statsig Console API key](/console-api/introduction) in the script
* Map LaunchDarkly environments to Statsig environments that aren't already the same by using `--environment-name-mapping` to the script.
* Map LaunchDarkly context kind to Statsig's custom unit ids and custom fields.
You can find the detailed instructions for these steps on the [Github repo](https://github.com/statsig-io/migrations).
## Running the Script
To execute the migration script, run the following command in your terminal:
```bash theme={null}
node index.js
```
The script will perform the following actions:
1. Fetch all feature flags from LaunchDarkly.
2. Translate each flag into Statsig's format.
3. Create feature gates in Statsig.
4. Write the migration status and details to a CSV file named `flag_migration_tracker.csv`
## Example Translations
The following examples show how LaunchDarkly feature flags are translated into Statsig feature gates:
**Example 1:** LaunchDarkly flag with email and name targeting conditions
Do not provide a `privateAttribute` key anywhere else in the `user` object. The entire `privateAttributes` dictionary is dropped, but any duplicate fields at the top level or in the custom object will still be logged (and evaluated against)
## Client vs Server SDKs
Client/single user environment SDKs send the user object with the `initialize` call to evaluate the user against every gate in your Statsig project.
*privateAttributes will be sent with this call but will not be stored or logged on Statsig servers*. In order to evaluate the conditions and rules for a gate, config, or experiment, Statsig servers need to know the privateAttributes field. It will be stripped from the users for any logging on Statsig servers.
Client SDKs will remove privateAttributes before any events are logged - they are only needed for gate evaluation.
Example with the `@statsig/js-client` SDK: [https://github.com/statsig-io/js-client-monorepo/blob/17fb70f1bea00d07e156cf6ff03b8024bbc1b197/packages/client-core/src/EventLogger.ts#L325](https://github.com/statsig-io/js-client-monorepo/blob/17fb70f1bea00d07e156cf6ff03b8024bbc1b197/packages/client-core/src/EventLogger.ts#L325)
If this does not meet your needs, our Server SDKs are able to make a stronger guarantee - `privateAttributes` will never leave your server. Statsig server SDKs
download the definition of each gate/config/experiment and evaluate them locally.
`privateAttributes` stripped from event logs with the `statsig-node` SDK: [https://github.com/statsig-io/node-js-server-sdk/blob/d1cb9431fb68b40f840254fce70363de1dc51aa5/src/LogEvent.js#L21](https://github.com/statsig-io/node-js-server-sdk/blob/d1cb9431fb68b40f840254fce70363de1dc51aa5/src/LogEvent.js#L21)
Evaluation happening locally to the server on `privateAttributes` in the `statsig-node` SDK: [https://github.com/statsig-io/node-js-server-sdk/blob/d1cb9431fb68b40f840254fce70363de1dc51aa5/src/Evaluator.js#L374](https://github.com/statsig-io/node-js-server-sdk/blob/d1cb9431fb68b40f840254fce70363de1dc51aa5/src/Evaluator.js#L374)
Don't just take our word for it - all of our SDKs are open source and [available on github](https://github.com/statsig-io). Feel free to dive in to the implementation of `privateAttributes` in the SDK you are using, or reach out to us on [slack](https://www.statsig.com/slack) and we can point you in the right direction.
To ensure that user PII is never transmitted over the network back to Statsig during Client SDK initialization, you should use [Client Boostrapping](/client/concepts/initialize#bootstrapping-overview) and provide the `privateAttributes` as part of the user object on the server to the `getClientInitializeResponse()` call. This will generate all of the assignments locally on your server, and these assignments can then be passed as `initializeValues` to the client SDK, negating the need to send any user attributes from the client device to Statsig.
## Event Logging
The privateAttributes field will be stripped from the user object for any `logEvent` calls on client or server SDKs. On server SDKs, you can simply not provide that field for `logEvent` calls if you wish - no evaluation is happening, so they are not necessary. If you are using the same user everywhere, the SDK will handle dropping the `privateAttributes` for you.
# Email AB Testing with SendGrid
Source: https://docs.statsig.com/guides/sendgrid-email-abtest
Run email A/B tests with Statsig and SendGrid by logging exposure events from sends to compare open, click, and conversion metrics across variants.
Email campaigns are a critical tool for any Marketing team. Finding the best performing Email template is a perfect use-case for an A/B test. Statsig allows you to run simple but powerful A/B tests on different parts of your email content. Since Statsig can integrate seamlessly with product analytics, you can run email experiments and understand deeper business level impact easily.
This guide assumes you have an existing Statsig account. Please go here to create a new free account if you don't already have one: [https://statsig.com/signup](https://statsig.com/signup)
### Step 1: Create an experiment
Start by creating a new Experiment on Statsig console. Put in a name and leave the rest of the fields empty/default. For the purposes of this walkthrough, that should do.
You can find your API Key by navigating to Statsig Project Settings -> API Keys, and copying the 'Client API Key'.
Make sure all the **Deliverability Data** and **Engagement Data** checkboxes are checked. Next, Enable the **Event Webhook Status** and hit Save.
The set up should look like this:
In order to avoid introducing any bias, it is best to split the recipient list at random. For instance, you want to ensure recipients within the same company are distributed evenly between the two lists.
Now you're good to go. Send those emails and Statsig will automatically track how well each variant in your A/B test is performing across email opens, clicks, etc.
## Monitoring the set up
When you've started the sends, you can verify everything is working as expected by navigating to the Diagnostics Tab in your experiment and looking at the 'Exposure Stream' at the bottom of the page. This shows a realtime stream of the page loads along with the variant they were allocated.
This page covers the legacy Sidecar flow. For Visual Editor v3, see [Advanced Configurations](/guides/sidecar-experiments/advanced-configurations-v3).
## Single Page App Support
Sidecar now officially supports integration within Single Page Apps.
This includes new Sidecar configuration tools and SDK methods that you can use to configure your own customer trigger points, giving you full flexibility to control when an experiment should run.
* **Disable Auto Run** - When selected, Sidecar will not automatically attempt to run the test on page-load.
* **Custom activation** using `StatsigSidecar.activateExperiment("")` to activate an experiment manually.
* **Prerun Script** - This allows you to define a custom script that will run only once per experiment if the url filter passes. You should use this to bind any listeners or evaluate any custom logic you need to control when to trigger the experiment using `activateExperiment`.
",
custom: { // optional attributes object
isLoggedIn: false
}
}
```
## Accessing the Statsig js client
For accessing the underlying Statsig js client instance, you can call `StatsigSidecar.getStatsigInstance()`.
## Configuring Runtime Options
This allows you to handle Consent Management, GDPR compliance and more. All of the [StatsigOptions](/client/javascript-sdk/#statsig-options) provided by the JavaScript SDK are also fully-supported with Sidecar. These can be passed to Sidecar via:
```js theme={null}
window.statsigOptions = {
// example of disabling logging for
loggingEnabled: 'disabled'
}
```
## Managing Consent
Prior to Sidecar script tag, configure these runtime options to disable browser storage and tracking:
```js theme={null}
window.statsigOptions = {
loggingEnabled: "disabled",
disableStorage: true
}
```
Later on, after the user gives consent, re-enable storage and tracking:
```js theme={null}
__STATSIG__.instance().updateRuntimeOptions({loggingEnabled: "browser-only", disableStorage: false});
```
## Persisting stableID across subdomains
Statsig uses `localStorage` as the preferred mechanism for storing the user's stableID. Localstorage keys do not persist across any origin boundaries including across subdomains. For example, a user visiting `https://example.com`, `https://show.example.com` and `https://account.example.com` would be issued three distinct stableIDs.
If you are assigning a user to a test on one subdomain, and tracking behavior for metrics purposes on a different subdomain, you'll need to have this solution in place to ensure Statsig can properly attribute cross-origin behavior to the Test Group assignment that took place on the initial experiment domain.
To install, simply paste the following in your HEAD section.
```html theme={null}
```
# Advanced Configurations
Source: https://docs.statsig.com/guides/sidecar-experiments/advanced-configurations-v3
Configure advanced Statsig Sidecar v3 settings, including custom triggers, multi-page tests, and integrations with analytics tools and consent providers.
## Runtime settings for SPAs and manual activation
Visual Editor v3 includes runtime settings that let you control when an experiment starts running on the page. These settings are configured on the experiment setup page in the Statsig Console.
* **Disable Auto Run** prevents Sidecar from automatically attempting to run the experiment on page load.
* **Custom activation** lets you start the experiment manually with `StatsigSidecar.activateExperiment("experiment_name")`.
* **Prerun Script** lets you define a custom script that runs once before the experiment starts when the targeting rules pass. Use this to bind listeners or evaluate custom logic before manually activating the experiment.
## Advanced Targeting & Segmentation
This approach allows you to set User Identity and Attributes for Sidecar, enabling you to perform more advanced targeting and results segmentation.
By default, Sidecar & Autocapture use `stableID` (an auto-generated device-level guid that gets stored in the user's localStorage) for tracking purposes. If you wish to enrich autocapture events with known user identities and attributes, you can define the following object *prior* to autocapture/sidecar being loaded.
Watch this [video tutorial](https://tinyurl.com/sidecar-targeting) on how to configure more advanced targeting for your Sidecar experiments.
```js theme={null}
window.statsigUser = {
userID: "",
custom: { // optional attributes object
isLoggedIn: false
}
}
```
## Available Sidecar methods
Sidecar exposes a small runtime API on `window.StatsigSidecar` for manual activation, manual event logging, and access to the underlying Statsig JavaScript client. After Sidecar initializes, `StatsigSidecar.getStatsigInstance()` returns the underlying client.
```js theme={null}
// Start a Visual Editor experiment manually when Disable Auto Run is enabled
StatsigSidecar.activateExperiment("experiment_name");
// Log a custom event
StatsigSidecar.logEvent("event_name", null, {
metadata_key: "metadata_value",
});
// Access the underlying Statsig JavaScript client after Sidecar initializes
window.postExperimentCallback = function () {
const client = StatsigSidecar.getStatsigInstance();
const config = client.getDynamicConfig("config_name");
const context = client.getContext();
};
```
## Configuring Runtime Options
This allows you to handle Consent Management, GDPR compliance and more. All of the [StatsigOptions](/client/javascript-sdk/#statsig-options) provided by the JavaScript SDK are also fully-supported with Sidecar. These can be passed to Sidecar via:
```js theme={null}
window.statsigOptions = {
// example of disabling logging for
loggingEnabled: 'disabled'
}
```
## Managing Consent
Prior to Sidecar script tag, configure these runtime options to disable browser storage and tracking:
```js theme={null}
window.statsigOptions = {
loggingEnabled: "disabled",
disableStorage: true
}
```
Later on, after the user gives consent, re-enable storage and tracking:
```js theme={null}
__STATSIG__.instance().updateRuntimeOptions({loggingEnabled: "browser-only", disableStorage: false});
```
## Persisting stableID across subdomains
Statsig uses `localStorage` as the preferred mechanism for storing the user's stableID. Localstorage keys do not persist across any origin boundaries including across subdomains. For example, a user visiting `https://example.com`, `https://show.example.com` and `https://account.example.com` would be issued three distinct stableIDs.
If you are assigning a user to a test on one subdomain, and tracking behavior for metrics purposes on a different subdomain, you'll need to have this solution in place to ensure Statsig can properly attribute cross-origin behavior to the Test Group assignment that took place on the initial experiment domain.
To install, simply paste the following in your HEAD section.
```html theme={null}
```
# Creating Your First Experiment
Source: https://docs.statsig.com/guides/sidecar-experiments/creating-experiments
Create and configure A/B experiments using the Statsig Sidecar Chrome extension without writing code or deploying changes to your production application.
Sidecar allows you to create and run A/B experiments easily without having to write code or push code to production. Here we'll see how you can create one such experiment and get results
This guide assumes you have followed the previous steps of installing side-car, creating a statsig account and setting up the API Keys correctly. Check out [Setup](/guides/sidecar-experiments/setup) for those instructions.
### Step 1: Navigate to the web page
Navigate to the web page you want to experiment on.
This integration is for tracking purposes only. We strongly advise against loading Sidecar itself via GTM, as this will delay the changes from being applied and result in "flickering".
### Overview
This integration with GTM will automatically send any GTM-tagged events to Statsig.
This guide assumes you have an existing Statsig account. Please go here to create a new free account if you don't already have one: [https://statsig.com/signup](https://statsig.com/signup)
## A word on performance
Sidecar (along with any type of client side tooling you install, be it open-source or via experimentation providers) will introduce some degree of page load latency. We recommend taking Sidecar for a spin and determining if the impact of your performance metrics fall within your acceptable threshold.
Customers that are very performance-minded typically use our [JS-SDK](/client/javascript-sdk) for testing on the web. When using the JS/React SDKs with [Client Bootstrapping](/client/javascript-sdk/init-strategies/#2-bootstrap-initialization), the latency introduced is very minimal since there are no network requests required for initialization.
# Measuring Experiments
Source: https://docs.statsig.com/guides/sidecar-experiments/measuring-experiments
Learn how to measure experiment results using autocapture, the manual tracking API, and Sidecar callbacks for analytics integrations.
## Using Autocapture
Sidecar automatically tracks various web activities, allowing you to create both simple and complex Metrics within Statsig console without writing a line of code. Create a new metric in the Metrics tab on the Statsig console to get started, and read more about the metrics we automatically log in [Autocapture on the Web](/webanalytics/autocapture).
See [Autocapture on the Web](/webanalytics/autocapture)
## Using the tracking API
You can track events manually for actions that are not autocaptured by the feature described above.
To track events back to Statsig, you can call `StatsigSidecar.logEvent` which takes the same arguments as the Statsig JS SDK as documented [here](/client/javascript-sdk#logging-an-event). This method can be called prior to completion of the init routine.
```js theme={null}
// example order event
StatsigSidecar.logEvent('Order', null, {
total: 54.66,
units: 3,
unitAvgCost: 18.22
});
```
## Per-assignment callback for outbound integrations
You can bind a callback that gets invoked each time Sidecar activates an experiment assignment, including experiments activated later by prerun scripts.
*This method should be defined anywhere prior to the Sidecar client script.*
```js theme={null}
window.statsigSidecarConfig = {
onExperimentEvaluation: function (event) {
/**
* add your own callback routine here
* ie; annotating 3rd party analytics tools with assignment info
*/
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "statsig_experiment_evaluation",
experiment_name: event.experimentName,
experiment_group_name: event.groupName,
});
}
}
```
The callback payload includes:
* `event.name` - always `"experiment_evaluation"`
* `event.experiment` - the full Statsig experiment object
* `event.experimentName` - the Sidecar experiment name, or the Statsig experiment name as a fallback
* `event.groupName` - the assigned group / variant, or `null` if unavailable
## Post-Experiment Callback for one-time readiness hooks
You can still bind `window.postExperimentCallback` if you need a callback after Sidecar finishes its initial run. This callback can fire even when there are no experiments, and it does not cover experiments that are activated later by prerun scripts.
```js theme={null}
window.postExperimentCallback = function(statsigClient, experimentIds) {
// One-time initialization hook after Sidecar finishes the initial run
}
```
#### Disabling All Logging
To disable all logging to statsig (both autocapture events and logging who has seen your experiments) append the following query string parameter to the Sidecar script URL: `&autostart=0`. This may be useful if you're dealing with GDPR compliance, and you can later re-enable events with `client.updateRuntimeOptions({disableLogging: false})`
# Taking your experiments to production
Source: https://docs.statsig.com/guides/sidecar-experiments/publishing-experiments
Publish, QA, and launch Statsig Sidecar experiments in production with step-by-step guidance covering preview links, approvals, and traffic ramp-up.
With the experiment configuration out of the way, we need to take this to production. Sidecar makes this easy with just a few clicks.
This guide assumes you have followed the previous steps of creating an experiment in Sidecar. Check out [Creating Experiments](/guides/sidecar-experiments/creating-experiments) for those instructions.
### Step 1: Publish the experiments
Once you are satisfied with the experiment configuration, go ahead and hit the blue *Publish* button. This is essentially a way to store all of your configurations in Statsig. If you want to make sure these changes have been stored successfully, you can on the `...` menu and choose *Go to Experiment Console*.
Publishing changes will not start any experiments, it will do the following:
* Sync any unsaved changes to Statsig (making them accessible in Console where you can configure Metrics and other targeting conditions if applicable).
* Include any configured tests in the Sidecar script installed on your website.
* Allow you to QA experiments on your site while they're in an Unstarted state.
_`
The image below depicts where you can find the experiment ID and each variation ID. Based on this example, you can force a preview of the Test Group by visiting the following URL:
* This guide assumes you have an existing Statsig account. Please go here to create a new free account if you don't already have one: [https://statsig.com/signup](https://statsig.com/signup)
* You will need to use Google Chrome web browser for this exercise.
* This page covers the legacy Sidecar extension flow. For Visual Editor v3, use the [Visual Editor setup guide](/guides/sidecar-experiments/sidecar-v3).
## Setup Sidecar Chrome Extension
### Step 1: Install Chrome Extension
If you don't already have the Sidecar extension, visit the [Chrome store](https://chromewebstore.google.com/detail/statsig-sidecar/blkgemeefnlkmicphlkodgdkhceibgcb) and click on the "Add to Chrome" button
Installing Sidecar JS via a Tag Manager can potentially lead to flickering and other unpredictable behavior. We strongly encourage installing Sidecar as a synchronous script tag.
### Additional Options
Add these query string parameters to the Sidecar script URL for additional controls over Sidecar client behavior
* `&reduceflicker=0` will disable the brief hiding of the `` tag while the client initializes
* `&autocapture=0` will disable event autocapture
Most website builders also support the ability to add script tags on your website. Here are some common website builder examples:
[Webflow](https://university.webflow.com/lesson/custom-code-in-the-head-and-body-tags?topics=site-settings), [Wordpress](https://wordpress.com/go/website-building/how-to-properly-add-javascript-to-wordpress-3-top-methods/), [Wix](https://support.wix.com/en/article/embedding-custom-code-on-your-site), [Squarespace](https://support.squarespace.com/hc/en-us/articles/205815928-Adding-custom-code-to-your-site), [Weebly](https://weeblytutorials.com/embed-javascript-weebly).
You can copy the script code from within the Sidecar Chrome extension
Sidecar v3 is in an open Beta release. Feel free to try the product, and share any feedback you have in our [Slack Community](https://statsig.com/slack).
## Prerequisites:
### 1. Installing the Sidecar Script
For experiments to take effect, you'll need to have the visual editor ("sidecar") script running on your website, on any page you'd like to experiment on:
```html theme={null}
```
Replace `client-key` with a client key from your Statsig project, which you can find at [Settings > Keys & Environments](https://console.statsig.com/api_keys).
Most website builders also support the ability to add script tags on your website, like:
[Webflow](https://university.webflow.com/lesson/custom-code-in-the-head-and-body-tags?topics=site-settings),
[Wordpress](https://wordpress.com/go/website-building/how-to-properly-add-javascript-to-wordpress-3-top-methods/),
[Wix](https://support.wix.com/en/article/embedding-custom-code-on-your-site),
[Squarespace](https://support.squarespace.com/hc/en-us/articles/205815928-Adding-custom-code-to-your-site),
[Weebly](https://weeblytutorials.com/embed-javascript-weebly).
### 2. Installing the Chrome Extension (for editing)
Additionally, to create edits for experiment variants - you'll need the new Statsig Visual Editor [Chrome Extension](https://chromewebstore.google.com/detail/statsig-sidecar-v3/mmgjfcbidnlghegclgpkgegpdhbopjhn) installed.
You also need to be a project admin, or have permissions to access console API keys, to use all Sidecar functionality.
## Creating an Experiment
You now create experiments in the console, on the Create Experiment dialogue, by changing the experiment type to "Visual Editor".
."
This can be any random string. Your server should reject any request that does not supply the same string you supplied when setting up the integration. One way to generate this is by running `openssl rand -hex 32`. Make sure to store and read this securely on your server.
*And that's it! You're off to the races with easier-to-recognize IDs throughout the Console.*
# Testing your Gates/Experiments
Source: https://docs.statsig.com/guides/testing
Test Statsig integration locally with overrides, local evaluation, and unit tests so you can validate feature gate and experiment behavior before launch.
Statsig enhances your engineering velocity by offering tools and features that allow you to test configurations quickly while ensuring reliable outcomes. This page highlights key features across the product to help you test efficiently.
***
## Overrides: Test Features, Experiments, or Holdouts
Overrides allow you to manually configure [features](/feature-flags/overrides#adding-an-override), [experiments](/experiments-plus/overrides), or [holdouts](/holdouts) for testing purposes. This method enables safe testing without affecting live production data or skewing experiment results. **Overrides are excluded from Pulse analysis** to maintain unbiased results.
* Use **Segments** to target overrides to pre-production environments or specific groups (e.g., employees) for testing.
If the environment tier is unset, all checks and event logs will default to "production."
Here's an example of setting the environment tier in your code for the **development** environment:
#### Example (JS Client SDK):
```javascript theme={null}
const client = new StatsigClient(, user, { environment: { tier: 'development' } });
```
#### Example (Node Server SDK):
```javascript theme={null}
await statsig.initialize(, { environment: { tier: 'development' } });
```
Refer to your language-specific SDK documentation for further details.
***
## Using Environments in Feature Gates
To configure environment-specific rules for a **Feature Gate**, follow these steps:
1. **Create a new Feature Gate**: In the Statsig Console, create a new Feature Gate. For example, name it "development mode" to target only your development environment.
Reordering environments doesn't affect any rule logic, but it helps convey the rollout hierarchy (e.g., development → staging → production) to your teams.
***
## Per-Environment API Keys
To enhance security and privacy, Statsig allows you to create per-environment API keys. This ensures that SDKs initialized with specific environment keys will only access the rules relevant to that environment.
### Steps to Generate Environment-Specific API Keys:
1. Go to **Project Settings** → [**Environments & Keys**](https://console.statsig.com/api_keys).
2. Click **Generate New Key**, and specify the environment for which you want to generate the API key.
The default environments—Development, Staging, and Production—share the same server and client-side API keys. You can generate new keys for custom environments as needed.
***
# A/B Testing with Webflow and Visual Editor
Source: https://docs.statsig.com/guides/webflow-sidecar-ab-test
Run no-code A/B tests on a Webflow site using Statsig Sidecar, including connecting the Chrome extension and tracking conversion metrics.
## Use cases & considerations
Webflow offers a comprehensive platform for businesses to design, build, and manage visually stunning websites and their content without the need for coding.
To experiment on a site that uses Webflow, we recommend using [Statsig Visual Editor](/guides/sidecar-experiments/introduction) to build test treatments and assign users to experiments when they land on your site, all without writing code.
#### Install the Visual Editor Chrome extension
Install the [Statsig Visual Editor Chrome extension](https://chromewebstore.google.com/detail/statsig-sidecar-v3/mmgjfcbidnlghegclgpkgegpdhbopjhn) and follow the [Visual Editor setup guide](/guides/sidecar-experiments/sidecar-v3#2-installing-the-chrome-extension-for-editing).
The extension allows non-technical users to build experiments and treatments directly on top of a live page. You can target by URL and configure text changes, style changes, image swaps, and custom JavaScript for advanced use cases.
#### Add the Visual Editor script to your Webflow site
1. Log in to your Webflow dashboard and navigate to your project.
2. Access the **Custom Code** section in your project settings.
3. Copy the Visual Editor script tag from the [Visual Editor setup guide](/guides/sidecar-experiments/sidecar-v3#1-installing-the-sidecar-script) and replace `client-xxx` with your Client SDK key from [Settings > Keys & Environments](https://console.statsig.com/api_keys):
``
While this HTTP API is available for direct use, we strongly recommend using one of our official SDKs for your programming language whenever possible. SDKs offer better performance, automatic error handling, and type safety. They also provide a more idiomatic integration with your codebase. Only use this HTTP API directly if there isn't an SDK available for your language or if you have a specific use case that requires direct API access.
Before you can start calling the server APIs, you need to take care of the following steps:
Create a free account on the [Statsig sign-up page](https://statsig.com).
An account will let you use the Statsig Console, where you can manage all of your Feature Gates, Dynamic Configs, and Experiments. Note that you will also be able to invite others to collaborate on your Statsig Projects, so they can interact with your gates and configs.
An API key is required in every API request. There are two types of API keys you can use with the HTTP API:
* **Server-side secret Key**: Used only from secure servers and should never be exposed in client-side code.
* **Client-SDK Key**: Safe to embed in mobile apps and front-end web apps.
If you're working with server-side logic or sensitive data, use the Server-side secret Key. If you're in doubt or working with public-facing code, use the Client-SDK Key.
Our API is built on top of HTTPS, and you can authenticate via the `statsig-api-key` header. All API requests use the POST method, and parameters are set by passing a JSON object in the request body.
**Why POST?** Even for fetching data, we use POST to ensure secure and flexible transmission of user-specific data (e.g., configurations or experiment results).
Statsig automatically logs exposure events whenever you call the APIs. These exposure events help attribute downstream events to experiments or feature gates, which are used to calculate metrics like analytics lift.
# Events Mode on Logs Explorer
Source: https://docs.statsig.com/infra-analytics/events-mode-logs-explorer
Use events mode in Statsig Logs Explorer to analyze log records as discrete events for higher-cardinality grouping, filtering, and visualization.
Events Mode brings the searching and filtering abilities from [Log Explorer](/infra-analytics/logs-explorer) to your *existing* Statsig events data. No additional instrumentation required!
* Debug user activity with more control
* Trace the sequence of actions a user performed
* Narrow in on specific events from metadata properties
Events Mode is available to all **Statsig Cloud customers**.
***
### To Get Started:
1. Open Logs Explorer from the left navigation.
2. Confirm you've switched from **Logs** mode to **Events** mode (The area next to the search bar should say **Events**).
3. Start searching across event names, properties, and time ranges.
***
### How to Construct your Search
You can search through events in two ways:
1. **Writing queries:** Use [syntax-based search](/infra-analytics/logs-explorer-queries) to target specific events and properties
2. **Using the query builder:** Point-and-click to construct filters without syntax overhead.
**Endpoint & Auth**
* Endpoint: `https://api.statsig.com/otlp`
* Auth header: `statsig-api-key: `
Direct trace export to the Statsig OTLP endpoint is only available for TypeScript/Node. For all other languages, send traces to your OpenTelemetry Collector and forward from the Collector to Statsig over OTLP/HTTP.
Need a deeper setup guide? See [Open Telemetry Logs and Metrics](/server/concepts/open_telemetry) for collector installation/config, and the [Traces Explorer quick start](/infra-analytics/send-traces) for language-specific trace examples.
***
## Application Telemetry quick starts
Install dependencies:
```bash theme={null}
npm install --save \
@opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-http \
@opentelemetry/exporter-metrics-otlp-http \
@opentelemetry/api-logs \
@opentelemetry/sdk-logs \
@opentelemetry/exporter-logs-otlp-http \
@opentelemetry/resources \
@opentelemetry/semantic-conventions
```
Initialize OpenTelemetry (e.g., `instrumentation.js`):
```js theme={null}
// instrumentation.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } = require('@opentelemetry/semantic-conventions');
// import if you want to enable traces
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-http');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
// For troubleshooting, set the log level to DiagLogLevel.DEBUG
// const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');
// diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
const statsigKey = process.env.STATSIG_SERVER_SDK_SECRET;
const headers = { 'statsig-api-key': statsigKey ?? '' };
const sdk = new NodeSDK({
resource: resourceFromAttributes({
[ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || 'statsig-node-service',
[ATTR_SERVICE_VERSION]: process.env.VERSION || '1',
env: process.env.NODE_ENV || 'development',
}),
traceExporter: new OTLPTraceExporter({
url: 'https://api.statsig.com/otlp/v1/traces',
// or
// url: /v1/traces
headers,
}),
metricReader: new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter({
url: 'https://api.statsig.com/otlp/v1/metrics',
// or
// url: /v1/metrics
headers,
}),
exportIntervalMillis: 60000,
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
```
To set up application logs with OTel, you can use the pino or winston bridges. The example below using [pino](https://getpino.io/#/) with
[pino auto instrumentation](https://www.npmjs.com/package/@opentelemetry/instrumentation-pino).
Install the pino instrumentation:
```bash theme={null}
npm i pino @opentelemetry/instrumentation-pino
```
```js theme={null}
// instrumentation.js (continued)
const { BatchLogRecordProcessor } = require('@opentelemetry/sdk-logs');
const statsigKey = process.env.STATSIG_SERVER_SDK_SECRET;
const headers = { 'statsig-api-key': statsigKey ?? '' };
const sdk = new NodeSDK({
// ... other config ...
logRecordProcessors: [
new BatchLogRecordProcessor(
new OTLPLogExporter({
url: 'https://api.statsig.com/otlp/v1/logs',
// or
// url: /v1/logs
headers
})
),
],
instrumentations: [getNodeAutoInstrumentations(), new PinoInstrumentation()],
});
// in your application code, e.g., app.js
const pino = require('pino');
const logger = pino();
logger.info('OTel logs initialized');
```
The Statsig SDK also supports forwarding logs to Log Explorer; see the alternative logging example below.
```js theme={null}
// Requires: npm i @statsig/statsig-node-core
const { Statsig, StatsigUser } = require('@statsig/statsig-node-core');
const s = new Statsig(process.env.STATSIG_SERVER_SDK_SECRET);
await s.initialize();
const user = new StatsigUser({
userID: 'a-user',
custom: { service: process.env.OTEL_SERVICE_NAME || 'my-node-service' },
});
// levels: trace, debug, info, log, warn, error
s.forwardLogLineEvent(user, 'info', 'service started', { version: process.env.npm_package_version });
try {
// your app code
} catch (err) {
s.forwardLogLineEvent(user, 'error', 'unhandled error', {
message: String(err?.message || err),
stack: err?.stack,
});
}
```
Run your service:
make sure that you require or import `instrumentation.js` before any other application code to ensure instrumentation is set up correctly.
```bash theme={null}
STATSIG_SERVER_SDK_SECRET=YOUR_SECRET \
OTEL_SERVICE_NAME=my-node-service \
node -r ./instrumentation.js app.js
```
Tip: you can configure exporters via env instead of code:
* `OTEL_EXPORTER_OTLP_ENDPOINT=https://api.statsig.com/otlp`
* `OTEL_EXPORTER_OTLP_HEADERS=statsig-api-key=${STATSIG_SERVER_SDK_SECRET}`
* `OTEL_EXPORTER_OTLP_PROTOCOL=http/json`
You can view the official Next.js OpenTelemetry instructions for [pages router here](https://nextjs.org/docs/pages/guides/open-telemetry) and for [app router here](https://nextjs.org/docs/app/guides/open-telemetry)
Install dependencies:
```bash theme={null}
npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/auto-instrumentations-node
```
Add `instrumentation.ts` at the app root (Next 13+):
```ts theme={null}
// instrumentation.ts
import { NodeSDK } from '@opentelemetry/sdk-node';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
// For troubleshooting, set the log level to DiagLogLevel.DEBUG
// const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');
// diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
export async function register() {
const headers = { 'statsig-api-key': process.env.STATSIG_SERVER_SDK_SECRET ?? '' };
const sdk = new NodeSDK({
resource: new Resource({
[ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || 'statsig-node-service',
[ATTR_SERVICE_VERSION]: process.env.VERSION || '1',
env: process.env.NODE_ENV || 'development',
}),
traceExporter: new OTLPTraceExporter({
url: 'https://api.statsig.com/otlp/v1/traces',
// or
// url: /v1/traces
headers,
}),
metricReader: new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter({
url: 'https://api.statsig.com/otlp/v1/metrics',
// or
// url: /v1/metrics
headers,
}),
exportIntervalMillis: 60000,
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
}
```
To set up application logs with OTel, you can use the pino or winston bridges. The example below using [Pino](https://getpino.io/#/) with
[Pino auto instrumentation](https://www.npmjs.com/package/@opentelemetry/instrumentation-pino).
Install the pino instrumentation:
```bash theme={null}
npm i pino @opentelemetry/instrumentation-pino
```
```js theme={null}
// instrumentation.ts (continued)
import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
const statsigKey = process.env.STATSIG_SERVER_SDK_SECRET;
const headers = { 'statsig-api-key': statsigKey ?? '' };
const sdk = new NodeSDK({
// ... other config ...
logRecordProcessors: [
new BatchLogRecordProcessor(
new OTLPLogExporter({
url: 'https://api.statsig.com/otlp/v1/logs',
// or
// url: /v1/logs
headers
})
),
],
instrumentations: [getNodeAutoInstrumentations(), new PinoInstrumentation()],
});
// in your application code, e.g., app.ts
import pino from 'pino';
const logger = pino();
logger.info('OTel logs initialized');
```
The Statsig SDK also supports forwarding logs to Log Explorer; see the alternative logging example below.
```js theme={null}
// Requires: npm i @statsig/statsig-node-core
import { Statsig, StatsigUser } from '@statsig/statsig-node-core';
const s = new Statsig(process.env.STATSIG_SERVER_SDK_SECRET);
await s.initialize();
const user = new StatsigUser({
userID: 'a-user',
custom: { service: process.env.OTEL_SERVICE_NAME || 'my-node-service' },
});
// levels: trace, debug, info, log, warn, error
s.forwardLogLineEvent(user, 'info', 'service started', { version: process.env.npm_package_version });
try {
// your app code
} catch (err) {
s.forwardLogLineEvent(user, 'error', 'unhandled error', {
message: String(err?.message || err),
stack: err?.stack,
});
}
```
In Next.js, mark '@statsig/statsig-node-core' as a server external package in `next.config.js` to avoid bundling.
### Using Vercel + Statsig integration
If you're deploying to Vercel, you can use the \[Statsig + Vercel integration]\((/integrations/vercel/) to automatically forward logs from Vercel to Statsig.
* Keep `STATSIG_SERVER_SDK_SECRET` out of client bundles (do not use `NEXT_PUBLIC_`).
* Client/browser tracing requires separate web tracer setup; do not send secrets client-side. Consider routing via a Collector.
Sending OTLP data directly to statsig without a collector is only supported for Node.js applications at this time. For other languages and frameworks, you can send OTLP data to a collector and have the collector forward the data to Statsig.
See the [Collector quick starts](#collector-quick-starts) below for example configurations. And see the [OpenTelemetry Language APIs & SDKs documentation](https://opentelemetry.io/docs/languages/) for installation and configuration instructions for other languages and frameworks.
***
## Collector quick starts
Running a Collector is optional but recommended for production workloads.
Use the OpenTelemetry Collector as a gateway to receive OTLP from your applications and forward to Statsig.
This is useful if you want to centralize telemetry collection, add advanced sampling methods like tail-based sampling, or scrape logs/metrics from hosts or Kubernetes.
Create a minimal `values.yaml` for the OpenTelemetry Collector that forwards all signals (traces, metrics, logs) to Statsig:
```yaml title="values.yaml" theme={null}
config:
receivers:
otlp:
protocols:
http:
grpc:
processors:
batch: {}
exporters:
otlphttp:
endpoint: https://api.statsig.com/otlp
encoding: json
headers:
statsig-api-key: ${env:STATSIG_SERVER_SDK_SECRET}
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp]
logs:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp]
```
Install the Collector with Helm:
```bash theme={null}
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
helm install otel-gateway open-telemetry/opentelemetry-collector \
-n otel --create-namespace \
-f values.yaml
```
Provide the Statsig key as an environment variable to the Collector pods (for example via a Secret and envFrom). Your applications then send OTLP to the in-cluster Collector endpoint (for example `http://otel-gateway-collector.otel.svc.cluster.local:4318`).
For a production setup that also scrapes Kubernetes logs/metrics, see the full guide: [Open Telemetry Logs and Metrics](/server/concepts/open_telemetry).
**Version requirement**
The `encoding: json` option in the OTLP HTTP exporter requires Collector v0.95.0 or newer. If you pin the image via Helm values, set `image.tag: "0.95.0"` (or newer).
Use Docker Compose to run a Collector gateway that accepts OTLP and forwards to Statsig.
```yaml title="docker-compose.yaml" theme={null}
services:
otel-collector:
image: otel/opentelemetry-collector-contrib:latest
command: ["--config=/etc/otel-collector-config.yaml"]
environment:
- STATSIG_SERVER_SDK_SECRET=${STATSIG_SERVER_SDK_SECRET}
volumes:
- ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
ports:
- "4317:4317" # OTLP gRPC
- "4318:4318" # OTLP HTTP
```
Create the Collector config referenced above:
```yaml title="otel-collector-config.yaml" theme={null}
receivers:
otlp:
protocols:
http:
grpc:
processors:
batch: {}
exporters:
otlphttp:
endpoint: https://api.statsig.com/otlp
encoding: json
headers:
statsig-api-key: ${env:STATSIG_SERVER_SDK_SECRET}
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp]
logs:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp]
```
Start the Collector:
```bash theme={null}
export STATSIG_SERVER_SDK_SECRET=YOUR_SECRET
docker compose up -d
```
Point your applications at the Collector (HTTP): `http://localhost:4318` (or `http://otel-collector:4318` from other compose services). The Collector forwards to Statsig with your key.
You can run the Collector in other environments (VMs, bare metal, etc) using the config below. See the [Collector documentation](https://opentelemetry.io/docs/collector/installation/) for other installation and deployment methods.
```yaml title="otel-collector-config.yaml" theme={null}
exporters:
otlphttp:
endpoint: https://api.statsig.com/otlp
encoding: json
headers:
statsig-api-key: ${env:STATSIG_SERVER_SDK_SECRET}
```
***
## Common Collector Configs (K8s & Docker)
The following examples show popular receivers/processors you can enable in your Collector and still export to Statsig via the same `otlphttp` exporter.
These components live in the contrib distribution. Use an image that includes them:
* Docker: `otel/opentelemetry-collector-contrib` or newer
* Helm: set `image.repository: otel/opentelemetry-collector-contrib` (and a compatible `image.tag`)
Helm values (contrib image):
```yaml title="values.yaml" theme={null}
image:
repository: otel/opentelemetry-collector-contrib
tag: "latest"
pullPolicy: IfNotPresent
```
### A. File logs (filelog receiver)
Reads and parses logs from files on disk. Useful for hosts, containers, or Kubernetes nodes.
Minimal example:
```yaml theme={null}
receivers:
filelog:
include: [ /var/log/myservice/*.json ]
start_at: beginning
operators:
- type: json_parser
timestamp:
parse_from: attributes.time
layout: '%Y-%m-%dT%H:%M:%S%z'
processors:
batch: {}
exporters:
otlphttp:
endpoint: https://api.statsig.com/otlp
encoding: json
headers:
statsig-api-key: ${env:STATSIG_SERVER_SDK_SECRET}
service:
pipelines:
logs:
receivers: [filelog]
processors: [batch]
exporters: [otlphttp]
```
Kubernetes tip: to tail container logs on nodes, mount host paths (e.g., `/var/log/pods` and `/var/lib/docker/containers`) into the Collector DaemonSet and set `include` to those paths.
### B. EC2 resource detection (resourcedetection processor)
Automatically adds AWS EC2 metadata (cloud provider, region/zone, instance id) to your telemetry.
```yaml theme={null}
processors:
resourcedetection/ec2:
detectors: [env, ec2]
timeout: 2s
override: false
service:
pipelines:
traces:
receivers: [otlp]
processors: [resourcedetection/ec2, batch]
exporters: [otlphttp]
metrics:
receivers: [otlp]
processors: [resourcedetection/ec2, batch]
exporters: [otlphttp]
logs:
receivers: [otlp]
processors: [resourcedetection/ec2, batch]
exporters: [otlphttp]
```
Permissions: the Collector must be able to reach the EC2 metadata service (IMDS). Ensure network access to `169.254.169.254` and IMDSv2 where required.
### C. Docker container metrics (docker\_stats receiver)
Emits container CPU, memory, network, and block IO metrics by querying the Docker daemon.
```yaml theme={null}
receivers:
docker_stats:
endpoint: unix:///var/run/docker.sock
collection_interval: 15s
processors:
batch: {}
exporters:
otlphttp:
endpoint: https://api.statsig.com/otlp
encoding: json
headers:
statsig-api-key: ${env:STATSIG_SERVER_SDK_SECRET}
service:
pipelines:
metrics:
receivers: [docker_stats]
processors: [batch]
exporters: [otlphttp]
```
Requirements:
* Linux only (not supported on darwin/windows).
* Mount the Docker socket into the Collector container: `/var/run/docker.sock`.
***
## Resources
* OpenTelemetry Collector: [https://opentelemetry.io/docs/collector/](https://opentelemetry.io/docs/collector/)
* Kubernetes Collector components: [https://opentelemetry.io/docs/platforms/kubernetes/collector/components/](https://opentelemetry.io/docs/platforms/kubernetes/collector/components/)
* Helm chart: [https://github.com/open-telemetry/opentelemetry-helm-charts](https://github.com/open-telemetry/opentelemetry-helm-charts)
* Collector configuration reference: [https://opentelemetry.io/docs/collector/configuration](https://opentelemetry.io/docs/collector/configuration)
* OTLP protocol specification: [https://opentelemetry.io/docs/specs/otlp/](https://opentelemetry.io/docs/specs/otlp/)
* Filelog receiver (contrib): [https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver)
* Resource detection processor (contrib): [https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor)
* Docker stats receiver (contrib): [https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/dockerstatsreceiver)
* Collector contrib distribution: [https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib](https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib)
# Logs Explorer Overview
Source: https://docs.statsig.com/infra-analytics/logs-explorer
Search and analyze all of your product’s logs in one place.
Logs Explorer lets you query logs, traces, and ingested events from a single interface. Use it the same way whether you’re debugging infrastructure issues or investigating product event streams.
* **Search**: Slice logs down to only what's relevant (by service, host, status code, etc.)
* **Group**: Aggregate logs by dimensions like region, status, or browser.
* **Visualize**: Plot log groupings over time to spot spikes, regressions, or anomalies instantly.
***
### Getting Started with Log Explorer
To get started with Log Explorer, follow the [OTEL onboarding guide](/infra-analytics/getting-started.mdx) to set up log ingestion. Once that's ready, you can navigate from **Infra Analytics → Log Explorer** from the Statsig left menu.
You can also use Logs Explorer in [Events Mode](/infra-analytics/events-mode-logs-explorer) to search and analyze your existing Statsig Events — no additional instrumentation needed. You can switch between Logs and Events mode using the dropdown left of the search bar.
Plain text searches will only match against the **log message field**, not the entire log body.
## Basics
### Property Prefixes
| Prefix | Description | Example |
| ----------- | ----------------------- | -------------------------------------- |
| `@property` | Event or log properties | `@traceId:"1a3cg5"` |
| `#property` | Reserved properties | `#custom_event:"shopping_cart_opened"` |
| `$user` | User identifiers | `$stableID:"abcdef"` |
| *none* | User properties | `tier:prod` |
### Logical Operators
These are query-level connectors. They combine or negate multiple conditions.
| Operator | Description | Example |
| ---------------------- | -------------------- | --------------------------------------- |
| `AND` (case sensitive) | Match all conditions | `level:error AND service:api-gateway` |
| `OR` (case sensitive) | Match any condition | `level:error OR level:warn` |
| `!=` or `!:` | Exclude a condition | `status!:error OR service!:api-gateway` |
### Other Operators
These are field-level conditions.
| Operator | Description | Example |
| ------------ | --------------------- | --------------------------------------- |
| `:` or `=` | equals | `status_code:200` or `status_code=200` |
| `!=` or `!:` | not equals | `level!:debug` or `level!=debug` |
| `>` `<` | greater/less than | `latency_ms>500` or `latency_ms<1000` |
| `>=` `<=` | greater/less or equal | `latency_ms>=500` or `latency_ms<=2000` |
### Wildcard Search
You can use the `*` character as a wildcard in queries. A wildcard matches zero or more characters inside a field value.
🐌 Wildcards can impact the performance of your query, so use them sparingly.
### Additional Examples
| Query | Description | Matches |
| --------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------- |
| `@"log.file.path":"/logs/pods/*"` | Path begins with `/logs/pods/` | `/logs/pods/1234/stdout.log` |
| `@"log.file.path":"*/logs/pods/"` | Path ends with `/logs/pods/` | `/mnt/storage/logs/pods/` |
| `service:"api-*"` | Services with names starting with `api-` | `api-gateway`, `api-auth` |
| `@route:"*products/*"` | Page routes containing the string `products/` | `shopify.com/products/tshirts`, `shopify.com/cart/products/view` |
| `@message!:""` | Return logs where the message field is **not null** | any log that has a `message` field |
# Infra Analytics Overview
Source: https://docs.statsig.com/infra-analytics/overview
Monitor and debug the health of your services directly inside Statsig with Infra Analytics, including logs, metrics, traces, alerts, and dashboards.
**[Infra Analytics](https://statsig.com/infra-analytics)** pulls in logs, metrics, and alerts so you get system-level observability in the same place you analyze product outcomes.
* Collect metrics and traces through OpenTelemetry (OTEL)
* Search and analyze logs to investigate issues
* Create alerts tied to service health
* Connect infrastructure signals to product analytics for a unified understanding of impact
## Feature Highlights
* **Logs Explorer**: Debug incidents with search, filters, and visualizations
* **Topline Alerts**: Catch regressions and anomalies with log/metric-based triggers
* **Metrics Explorer**: Inspect infrastructure metrics alongside product metrics
***
## Ready to Get Started?
* 👉 [Set up OTEL ingestion](/infra-analytics/getting-started) to start sending logs and metrics
* 👀 Traces are in limited preview — ping us in Slack if you'd like access
# Traces Explorer Quick Start
Source: https://docs.statsig.com/infra-analytics/send-traces
Minimal OTLP/HTTP code examples for exporting distributed traces to Statsig's Traces Explorer from Node.js, Python, Go, Java, and other popular languages.
Want Logs and Metrics too? See [Getting Started](/infra-analytics/getting-started) for more in-depth OpenTelemetry Collector setup instructions.
Use the OTLP/HTTP traces endpoint to forward spans into Traces Explorer. Authenticate with your Server Secret key in the header:
* Endpoint: `https://api.statsig.com/otlp/v1/traces`
* Header: `statsig-api-key: `
Direct to API is currently supported for TypeScript/Node only.
For all other languages, send traces to your OpenTelemetry Collector and configure it to forward to Statsig over OTLP/HTTP.
Point non-TypeScript apps to your Collector (for example `http://localhost:4318/v1/traces`) and configure the Collector to forward to Statsig:
```yaml title="collector.yaml" theme={null}
receivers:
otlp:
protocols:
http:
exporters:
otlphttp:
endpoint: https://api.statsig.com/otlp
encoding: json
headers:
statsig-api-key: ${env:STATSIG_SERVER_SDK_SECRET}
service:
pipelines:
traces:
receivers: [otlp]
exporters: [otlphttp]
```
```bash theme={null}
npm install @opentelemetry/sdk-node @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/api
```
```js theme={null}
// trace.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');
const { trace } = require('@opentelemetry/api');
const sdk = new NodeSDK({
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: 'trace-sample-node',
}),
spanProcessor: new BatchSpanProcessor(
new OTLPTraceExporter({
url: 'https://api.statsig.com/otlp/v1/traces',
headers: { 'statsig-api-key': process.env.STATSIG_SERVER_SDK_SECRET || '' },
}),
),
});
sdk.start().then(() => {
const tracer = trace.getTracer('example');
const span = tracer.startSpan('do-work');
span.setAttribute('example', true);
span.end();
setTimeout(() => sdk.shutdown(), 1000);
});
```
```bash theme={null}
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```
```python theme={null}
# trace.py
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
trace.set_tracer_provider(
TracerProvider(resource=Resource.create({"service.name": "trace-sample-python"}))
)
exporter = OTLPSpanExporter(
endpoint="http://localhost:4318/v1/traces", # your Collector
)
trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(exporter))
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("do-work") as span:
span.set_attribute("example", True)
trace.get_tracer_provider().shutdown()
```
```bash theme={null}
go get go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp go.opentelemetry.io/otel/semconv/v1.26.0
```
```go theme={null}
// main.go
package main
import (
"context"
"log"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
"go.opentelemetry.io/otel/sdk/resource"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)
func main() {
ctx := context.Background()
exporter, err := otlptracehttp.New(ctx,
otlptracehttp.WithEndpointURL("http://localhost:4318/v1/traces"), // your Collector
)
if err != nil {
log.Fatal(err)
}
tp := sdktrace.NewTracerProvider(
sdktrace.WithBatcher(exporter),
sdktrace.WithResource(resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceNameKey.String("trace-sample-go"),
)),
)
otel.SetTracerProvider(tp)
tracer := otel.Tracer("example")
ctx, span := tracer.Start(ctx, "do-work")
span.SetAttributes(attribute.Bool("example", true))
span.End()
_ = tp.Shutdown(ctx)
}
```
Need a deeper setup guide? See [Open Telemetry Logs and Metrics](/server/concepts/open_telemetry) for collector installation/config,
and if you want Logs and Metrics too? See [Getting Started](/infra-analytics/getting-started) for
more in-depth OpenTelemetry Collector setup instructions.
# Topline Alerts with Logs
Source: https://docs.statsig.com/infra-analytics/topline-alerts-logs
Detect infrastructure regressions by evaluating logs in real time with Statsig topline alerts on log volume, error rates, and pattern-based thresholds.
By combining log filters with [Topline Alerts](/product-analytics/topline-alerts), you will know immediately when things start failing without writing custom scripts or dashboards.
### When to Use Log-based Alerts
* **Monitoring success rates** - Catch regressions before they impact SLOs.
* **Detecting error spikes** - Trigger when 5xx or other errors rise above baseline.
* **Isolate by segment** - Identify failures concentrated in by region, client, or device type
## Create a Log-based Topline Alert (Statsig Cloud)
In this example, we're going to create a monitor for the success rate of a GET request.
Go to Analytics → Topline Alerts in the product menu.
Click +Create .
Enter a name for your alert.
Select statsig::log\_line as your event.
Apply filters to define what constitutes success and failure.
If you're unsure which fields to filter on, open the Logs Explorer and inspect the log body.
Define the formula for calculating your success rate.
(Optional) Add a group-by dimension.
Set thresholds and the evaluation window.
In this example, we will trigger a warning when success rate drops below 99.5%. We will trigger an alert when success rate drops below 99.0%.
Add the alert title and description for context.
Include diagnostic hints (e.g. "Check version X" or "Android requests timing out").
Add subscribers.
Set priority.
Click Save .
Once your alert is set up, you can visit the Diagnostics tab to see a history of alert triggers.
***
## Best Practices
* Set up [Slack notifications](/integrations/slack) for team visibility
* Keep formulas simple (ratios & percentages are easiest to scan)
* Add group-by dimensions (like country or app version) to pinpoint where issues occur
* Write clear notification text that explains what the alert means
# Custom Proxy for Statsig API
Source: https://docs.statsig.com/infrastructure/api_proxy/custom_proxy
Run a custom Statsig API proxy in your own infrastructure to cache SDK requests, reduce latency, and control egress traffic from production servers.
## Overview
Instead of sending API requests directly to Statsig, you can set up your own environment that proxies requests from your custom domain name to Statsig. This makes it less likely for tracking blockers to intercept your APIs, and allows you to capture more data.
There are many ways to set up custom proxies. We are showing instructions for a few common service providers here.
**Important: Default Endpoints Are Blocked**
The default Statsig endpoints (like `/v1/log_event`) are commonly blocked by tracking blockers. To ensure your proxy works effectively:
1. **Use a custom endpoint name** specific to your product (e.g., `/v1/my-product-data` instead of `/v1/log_event`)
2. **Rewrite the URL in your proxy** to map your custom endpoint to the actual Statsig endpoint (`log_event`)
3. **Do not use passthrough** for the endpoint path - you must rewrite it
Additionally, your proxy should not try to deserialize the payload body. This will improve robustness by reducing risk of integration issues from Server SDK -> Proxy -> Client SDK, as well as improve efficiency of the proxy. For example, client SDKs may change encoding to compress payloads, which would break if your proxy does not accept the new format (e.g. gzip).
## Approaches
### AWS CloudFront
#### Prerequisites
* Write access to your DNS settings.
* Write access on your AWS CloudFront and Lambda console.
* Access to a SSL certificate for your custom domain.
#### Setup
On your [AWS CloudFront console](https://console.aws.amazon.com/cloudfront/),
* Click on Create distribution.
* In the Origin section,
* Set the Origin Domain to `api.statsig.com`.
* Set the Protocol to `HTTPS only`.
You may see a different experience if you already have workers on your account.
3. Name you new worker whatever you would like and then click "Deploy".
In JavaScript, `networkConfig.api` is a base URL. The SDK appends endpoint paths like `/initialize` and `/rgstr` automatically. Use `initializeUrl` only when you want to override initialization independently of the other endpoints. There is no generic `api` fallback option; failover is configured per endpoint with `initializeFallbackUrls` and `logEventFallbackUrls`.
Depending on the SDK type, version, and proxy approach you are using, you may not need to append `'/v1'` to the end of your api string, for example `"https://my-statsig-proxy.com/"`.
### JavaScript Failover Example
If you want JavaScript clients to use your proxy as the primary endpoint and a second endpoint as failover, configure fallback URLs per endpoint:
```typescript theme={null}
Statsig.initialize(mySdkKey, myUser, {
networkConfig: {
api: "https://my-statsig-proxy.com/v1",
initializeFallbackUrls: [
"https://my-proxy-cache.com/v1/initialize",
],
logEventFallbackUrls: [
"https://my-proxy-cache.com/v1/rgstr",
],
},
});
```
### Configuring Custom Endpoints
If you've configured your proxy to use custom endpoint names (recommended to avoid tracking blockers), you'll need to configure the SDK to use those custom endpoints. The SDK will append the endpoint path to your base URL.
For example, if your proxy rewrites `/v1/my-product-data` to `/v1/log_event`, you would configure:
```typescript theme={null}
Statsig.initialize(mySdkKey, myUser, {
networkConfig: {
api: "https://my-statsig-proxy.com/v1",
logEventUrl: "https://my-statsig-proxy.com/v1/my-product-data",
},
});
```
Check your SDK's documentation for the specific configuration options available for customizing endpoint URLs.
# API Proxy
Source: https://docs.statsig.com/infrastructure/api_proxy/introduction
Introduction to Statsig API proxy options for caching SDK requests, reducing latency, and meeting compliance requirements in your infrastructure.
This section provides documentation on the various API proxy options supported when using Statsig.
## Why Use an API Proxy?
There are several compelling reasons to implement an API proxy for Statsig network requests:
1. **Mitigate Tracking Blocker Impact**: Reduce the effect of tracking blockers on Statsig API usage. Default Statsig endpoints are commonly blocked by tracking blockers, so using a custom proxy with product-specific endpoint names is essential for reliable data collection.
2. **Meet Security Requirements**: Comply with internal network security and topology standards.
3. **Enhance API Availability**: Improve API availability guarantees within your internal network boundary.
## API Proxy Deployment Options
API proxies can be deployed in various forms, each with its own advantages and considerations. The choice between a managed service and a self-hosted solution, or deploying outside versus inside your network, depends on your specific needs.
We offer documentation on the following options.
For both server SDKs and client SDKs:
* [Custom Proxy](/custom_proxy): A fully customizable proxy that you own and operate in your environment.
* [Managed Proxy](/infrastructure/managed-proxy): A lightweight, Statsig-owned proxy that provides out-of-the-box functionality.
For server SDKs only:
* [Forward Proxy](/server/concepts/forward_proxy): A Statsig-built proxy designed for deployment within your own environment.
Choose the option that best aligns with your infrastructure requirements and operational preferences. If you have any questions/concerns, drop on in to our [slack channel](https://www.statsig.com/slack) and let us know.
# Statsig Managed API Proxy
Source: https://docs.statsig.com/infrastructure/api_proxy/managed-proxy
Use the Statsig managed API proxy to cache SDK config and event requests, reduce client latency, and improve reliability without running your own proxy.
An API proxy gives you a unique URL to send and receive data to/from Statsig servers. This makes it less likely to be intercepted by client-side or DNS-side blockers. This way you'll be able to get the right configuration for your applications and more data back from your applications.
The Managed Proxy is available only for Pro or Enterprise tiers.
A quick-and-easy way to prevent adblocking, we recommend the custom proxy to low volume customers, or before you have the time to setup the [Custom Proxy](/custom_proxy), which is a more robust and customizable solution.
## Why use a proxy
A significant number of web-browser instances have some sort of tracking blockers installed. Sometimes these blockers end up blocking feature flags, experiments and even runtime dynamic config data, resulting in the exclusion of those users in the statistical power.
Using a proxy that's unique to your application signals these tracking blockers that this is a necessary component of your application that's required for its functioning.
## Setting up a managed proxy
If your project is in pro-tier or enterprise-tier, you will see an option to create a unique proxy for your SDK in the Settings -> Project -> Keys & Environments tab as shown below:
Currently the managed proxy that Statsig creates is hosted in `ap-south-1` region. If you want this hosted in a different region, reach out to Statsig support
## Using Your Proxy
Once you have a proxy setup, you will need to take its URL and apply it to the SDK. For JavaScript client SDKs, use `StatsigOptions.networkConfig.api`. You can visit [Statsig Options](/client/javascript-sdk#statsig-options) to read about the JavaScript-specific options. Other SDKs may expose the proxy base URL differently, but the managed proxy URL serves the same purpose.
The following is what initializing with a proxy looks like in JavaScript:
```typescript theme={null}
Statsig.initialize(mySdkKey, myUser, {
networkConfig: {
api: "https://my-statsig-proxy.com/v1",
},
});
```
In JavaScript, `networkConfig.api` is a base URL, not the same thing as `initializeUrl`. Use `initializeUrl` only when you want to override initialization independently. There is no generic `api` fallback option; endpoint failover is configured with `initializeFallbackUrls` and `logEventFallbackUrls`.
# Infrastructure Ops Overview
Source: https://docs.statsig.com/infrastructure/introduction
An overview of the Statsig infrastructure that powers reliable feature flagging, experimentation, and analytics at enterprise scale across global regions.
## Why Infrastructure Matters for Feature Flagging & Experimentation
Feature flagging and experimentation platforms require robust infrastructure to deliver consistent, low-latency responses that don't impact an application's performance. Every feature gate evaluation, experiment assignment, and analytics event must be processed reliably to ensure:
* **Consistent User Experiences**: Users should always receive the same feature variant throughout their session
* **Real-time Decision Making**: Feature flags need to evaluate in milliseconds to avoid blocking your application
* **Accurate Experiment Results**: Every user interaction must be captured and processed to generate reliable statistical insights
* **Business Continuity**: Infrastructure downtime can't block feature releases or compromise running experiments
## Enterprise-Grade Scale & Reliability
Statsig is built to process massive volumes of data while maintaining enterprise-grade reliability standards:
### Key Metrics
* **2+ Trillion** events processed per day
* **Over 3 Billion** unique monthly experiment subjects
* **99.99%** infrastructure uptime for API & Console
### Scalable Architecture
Statsig's infrastructure has been battle-tested by companies including including OpenAI, Atlassian, Microsoft, Notion, Flipkart, and other enterprises operating at massive scale. But all customers get access to enterprise-grade infrastructure from day one.
This means never a reason to switch tools or migrate to an "enterprise-grade" solution as you grow. Statsig can scale with you regardless of volume. Our investment in scaled infrastructure also allows us to offer affordable pricing across all products and customer tiers.
Infrastructure isn't limited to just serving configs and logging events. Statsig also provides comprehensive infrastructure management including:
* Real-time health checks and monitoring
* Automated guardrails on feature rollouts and releases
* Multi-region deployment for global availability
* Built-in redundancy and failover capabilities
## Getting Started
The section includes documentation about infrastructure setup and operations guide for your team when using Statsig. In general, Statsig works out of box with no additional setup required. Some instructions here apply to specific use cases due to special requirements.
If you have any questions/concerns, drop on in to our [slack channel](https://www.statsig.com/slack) and let us know.
# Reliability FAQs
Source: https://docs.statsig.com/infrastructure/reliability-faq
Frequently asked questions about Statsig reliability, including SDK failover behavior, multi-region architecture, SLAs, and customer-side mitigations.
Integrating your product with Statsig means depending on Statsig, and we take reliability seriously. Here are some questions many people have when trying to evaluate the risks, please feel free to reach out on Slack if you have questions that are not listed here.
## What does Statsig do to stay highly-available?
* We actively track internal Service Level Objectives (SLOs) for availability to make sure our service has a high uptime.
* Here are some examples of measures that we take to ensure our service reliability:
* We handle bursts gracefully via autoscalers and over-provisioned resources
* We have mechanisms to reduce unintended/malicious spikes and prevent DDoS attack
* Our services are deployed in multiple regions. In case of a region goes down, traffic will be routed to other healthy regions.
* We adopt the GitOps approach(e.g. code review, validation, CI/CD, etc.) for all of our infra changes to prevent human errors.
* We have a 24/7 eng oncall rotation to solve customer-facing alerts and issues.
## Does Statsig use any caching to help with latency?
* We use a combination of caching solutions, depending on the problem we are solving. For serving our console and API requests, most caching is done at the region or host level.
## What else does Statsig do to make sure the service is resilient?
* Our SDKs are designed to be resilient in case there is an issue in the API requests, to make sure a seamless experience on your side.
* Client SDKs:
* The SDKs will use the latest values from Statsig server if the user is able to reach Statsig server;
* Then it will use cached value from a previous session will be used, if available;
* After that, the APIs require you to have set default values in your code, so that will be used. This means the worst case scenario your users will get the default experiences.
* The SDKs will automatically retry failed event requests if for some reason Statsig event servers are unreachable. The Client SDKs will even persist failed log requests to local storage and retry in subsequent sessions.
* Server SDKs:
* They store rules for gates and experiments in memory, so it will be able to continue evaluating them even if Statsig is down.
* There is also an option to “bootstrap” your server SDKs with rule values from a previous session if Statsig is down when your server is starting up. This can be done with a [Server Data Store](/server/concepts/data_store/), which lets you plug a storage provider into the Statsig SDK, to store your rule values.
* The SDKs will automatically retry failed event requests if for some reason Statsig event servers are unreachable.
## What kind of automated testing does Statsig do?
* Unit and integration tests run on every pull request
* Continuous CI/CD running our unit/integrations test suites
* Synthetic tests for Console and API use cases, mimicking customer requests
* Stress tests to detect any performance issues
* Continuous SDK tests run on every pull request and on schedule
## What does Statsig do to protect runtime code?
We use Github and Dockerhub for code and binary storage. We keep track of the entire CI/CD process from source code to production deployment with traceable versioning and binary verification.
# Monitoring the SDK
Source: https://docs.statsig.com/infrastructure/sdk-monitoring
Monitor Statsig SDK health from the Statsig console, including initialization success rate, evaluation latency, network errors, and version adoption.
This latest release of structured logging and metrics, is currently only [available by the Python SDK](/server/pythonSDK/#sdk-monitoring-). Want it in another? Reach out in our [Support Slack](https://statsig.com/slack).
## SDK Metrics
Some Statsig SDKs provide built-in metrics to help you monitor its performance and impact on your application. The specific implementation may vary by programming language, refer to the documentation for the language-specific SDK interface.
### Metric Interface Methods
The following interface methods are provided by the Statsig SDK to track various metrics:
* **Initialization (`init`)**: This method is called on sdk initialization and allows users to initialize their observability client (such as StatsD, OpenTelemetry, etc.), preparing the SDK to send metrics and logs to the chosen observability tool.
* **Shutdown (`shutdown`)**: This method is called on sdk shutdown, and allow users to perform any actions to ensure graceful shutdown of the observability client, such as ensuring that any pending metrics or logs are properly handled and sent before the SDK is terminated.
* **Counter**: A method that tracks occurrences of specific events.
* **Gauge**: A method used to record point-in-time values, such as the number of active connections or other metrics that don’t accumulate over time.
* **Distribution**: A method that tracks distributions of numerical data over time, such as latency or response times.
* **Should Enable High Cardinality Tags**: This method is called on high cardinality tags and allows users to define if certain high cardinality tags (which can generate large data volumes) should be enabled for detailed tracking. By default, all high cardinality tags are disabled.
### List of Metrics
Below is a list of the primary metrics currently available in the SDK:
| **Metric Name** | **Type** | **Tags** | **Description** |
| ------------------------------------- | ------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `initialization` | distribution | `success`, `init_source`, `init_source_api`, `store_populated` | Tracks SDK initialization duration. |
| `config_propagation_diff` | distribution | `source`, `source_api`, `lcut*`, `prev_lcut*` | Measures the time difference between the last config updated time vs the time that sdk received the config. |
| `config_no_update` | counter | `source`, `source_api` | Tracks occurrences of no configuration updates. |
| `events_successfully_sent_count` | counter | N/A | Tracks number of events sent successfully to the Statsig server. |
| `sdk_exceptions_count` | counter | N/A | Tracks occurrences of unexpected exceptions caught. |
| `grpc_received_message` | counter | N/A | GRPC Streaming received a new message |
| `grpc_reconnected` | counter | N/A | GRPC streaming reconnected |
| `grpc_streaming_failed_with_retry_ct` | distribution | N/A | Streaming failed and how many retry we are on (to estimate how long the client has been disconnected) |
* All metrics are prefixed by `statsig.sdk.`, for example, the full initialization metric name in your integration will be `statsig.sdk.initialization`.
* While `sdk_exceptions_count` metric captures all exceptions, certain errors (e.g., temporary network connectivity issues or timeouts) are expected to occur occasionally and are generally not cause for concern. Use this metric to identify unexpected or persistent issues that may require investigation.
* Tags marked with `*` (such as `lcut` and `prev_lcut`) are high cardinality tags.
### Metric Tags
High cardinality tags are tags that can generate large data dimensions when enabled. These tags are disabled by default, but can be enabled as through `Should Enable High Cardinality Tags` method on the observability client interface. High cardinality tags include:
* `lcut`: The last configuration update timestamp.
* `prev_lcut`: The previous configuration update timestamp.
Metric Tags:
* `source`: The source of the configuration update, such as network/bootstrap/datastore.
* `source_api`: The API endpoint used to fetch the configuration update.
* `success`: Indicates whether the initialization was successful.
* `store_populated`: Indicates whether the configuration store was populated.
# Statsig Domains
Source: https://docs.statsig.com/infrastructure/statsig_domains
Reference list of Statsig domain names used by SDKs and the console so you can allowlist outbound traffic from your network and firewall.
Statsig uses the following domain names for its services. If you have a network policy set up inside your systems, you should allowlist
all of the domains below or select domains based on the features you use.
## Statsig Console
* `console.statsig.com`
* `cdn.console.statsig.com`
* `console.statsigcdn.com`
## Statsig API Services
These domains are used by our SDKs to communicate with our backend for feature gates, dynamic configs and event logging. They are also used for other Statsig APIs, e.g. console APIs, integrations.
* `api.statsig.com`
* `featuregates.org`
* `statsigapi.net`
* `events.statsigapi.net`
* `api.statsigcdn.com`
* `featureassets.org`
* `assetsconfigcdn.org`
* `prodregistryv2.org`
* `cloudflare-dns.com`
* `beyondwickedmapping.org`
Note that Statsig's SDKs may switch between these domains on-the-fly as part of our DNS resolution logic.
**Why such odd names?**
We constantly and dynamically update these domains to prevent overzealous blocking from browser ad blockers. These are updated whenever they pick up the existing ones.
### Don't care about ad-blockers?
Use the following approach to minimize the number of Statsig domains you need to whitelist. The [networkConfig](/client/javascript-sdk#networkconfig-object) initialization option allows you to specify a single domain for both the initialization server and the log event server.
```js theme={null}
new Statsig.StatsigClient('client-YOUR_KEY', {/* CONTEXT */}, {
networkConfig: {
initializeUrl: 'https://featureassets.org/v1/initialize',
logEventUrl: 'https://prodregistryv2.org/v1/rgstr'
}
});
```
### Server-side APIs
If you're just looking for a list of apis used by our backend/server SDKs, you need to allow:
* `api.statsig.com`
* `statsigapi.net`
* `api.statsigcdn.com`
* `prodregistryv2.org`
* `idliststorage.blob.core.windows.net` (see below)
### Statsig User Segment Storage API
The domain is used by our server SDKs to download the segment list for your project. If you do not use big id lists, you won't need this one.
* `idliststorage.blob.core.windows.net`
# Statsig IP Ranges
Source: https://docs.statsig.com/infrastructure/statsig_ip_ranges
Reference list of Statsig IP ranges used by SDKs and webhooks so you can allowlist inbound and outbound traffic in your firewall and network policies.
Statsig reserves the following IP addresses and ranges for use by its services. If you have a network policy set up inside your systems, you should allowlist
all of the IPs below or select IPs based on the direction of network requests.
## Outbound (Statsig -> Your Servers)
These IPs are used when Statsig sends requests to your servers/systems. For example, Statsig imports data from your data warehouse that has a network policy
allowing only certain IPs.
* 20.29.232.235
* 20.190.14.199
* 34.138.242.148/30 (4 addresses)
* 34.126.186.120/30 (4 addresses)
* 34.168.242.172/30 (4 addresses)
* 34.38.207.120/30 (4 addresses)
Webhook requests can be very high volume and may not be initiated from these IP Ranges. Consider using [Webhook Signatures](/integrations/event_webhook#webhook-signature) to validate webhook requests.
## Inbound (Your Clients/Servers -> Statsig)
These IPs back the domains (e.g. `api.statsig.com`, `featuregates.org`, `statsigapi.net`) of Statsig APIs.
* 34.120.214.181
* 34.128.128.0/29 (8 addresses)
# Agent Skills Repository
Source: https://docs.statsig.com/integrations/agent-skills
Use the public Statsig agent-skills repository to extend Cursor, Claude Code, and other coding agents with reusable Statsig workflows and capabilities.
The [statsig-io/agent-skills](https://github.com/statsig-io/agent-skills) repository contains reusable skill packs for coding agents. Skills are packaged, shareable workflows for repeated tasks, built on top of the Statsig MCP tools and Console API.
These skills build on the open [Agent Skills standard](https://agentskills.io/).
## Supported skills today
| Name | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `statsig` | Manage Statsig experiments, gates, dynamic configs, segments, layers, and audit logs through the Statsig MCP. |
| `statsig-create-cloud-metric` | Draft or execute Statsig Cloud metric creation requests through the Statsig Console API. |
| `statsig-dashboard` | Create, read, and update you Statsig dashboards. |
## Install from the repository
Install a skill from this repo with the Vercel `skills` CLI:
```bash theme={null}
npx skills add statsig-io/agent-skills
```
You can also:
* List installable skills: `npx skills add statsig-io/agent-skills --list`
* Install a skill globally for your user: `npx skills add -g statsig-io/agent-skills --skill statsig-dashboard`
* Install every skill in this repo: `npx skills add statsig-io/agent-skills --all`
After installation, compatible agents can discover each skill from its metadata.
## Requirements
* `STATSIG_CONSOLE_API_KEY` for Statsig Console API access
* Python 3 if you want to run bundled helper scripts directly
# AI Development with Statsig
Source: https://docs.statsig.com/integrations/ai_development_with_statsig
Use the Statsig MCP server with AI coding agents like Claude Code, Cursor, and Codex to add killswitches and log critical events for AI-written code.
## Statsig's Role in AI Development
Increasingly, developers are leaning on AI agents to accomplish small-to-midsized tasks.
For small feature additions, this is low risk - but can still introduce bugs or low-quality user experiences.
Having the agent be aware of Statsig means that it can automatically add logging for potential errors,
and add feature gates to new features (or make sure they're behind existing gates) so that you can manage rollouts safely and measure any degredation.
This adds up when considering the high velocity individuals can now achieve with help from these agents, and the ability of people to develop within codebases they have less context in with AI assistance.
## Recommended Approach
Our recommended approach is to use an `AGENTS.md` (or any analagous file, such as `CLAUDE.md`) to provide instructions that you can tailor to your own workflow.
The behaviors that are critical are:
* Adding gates to new features or codepaths, and tuning how aggressively to do so
* Automatically adding your user ID, and any test IDs your agent may log in as, to those gates for testing in development
* Adding critical logs for errors and user behaviors
* Currently adding these to tracking is manual, but we have plans to make this automatable via MCP for event count metrics.
### Boilerplate `Agents.md` file
Fill in your Statsig ID, and follow the [MCP guide](/integrations/mcp/overview) to set up the MCP server. Consider updating naming conventions and logic around when to ask.
We recommend using a limited-access console API key to control risk around a scenario where an agent deletes entities in Statsig.
```
# Statsig Development Guidelines
It is important that we selectively killswitch new features or any new, risky codepaths using Statsig Feature Gates so that we can turn them off if they cause issues.
## When To Use Gates
- We should consider adding a gate whenever we make significant changes to product features that have any risk of causing issues.
- It is possible for this to be spammy, so clarify with users during planning what should be killswitched.
- Start by assuming atomic, session-level features will be killswitched - e.g. "A new modal" would be, but not a copy change within a modal, or a bugfix.
- Sometimes, adding a gate is just as dangerous as the feature itself.
- Identify situations where this could occur - usually when adding the gate adds a large amount of complexity - and flag the risk to the user when asking if they want to create a gate.
Always ask the user if they want to gate the feature. Often, users will want to include the feature behind an existing gate, so ask in this way, when appropriate:
"This seems like a feature that you might want to be able to turn off remotely. Would you like to gate this feature, add it to an existing gate, or proceed without using gates?"
Look for gates already being used for this feature type - often in the same file or nearby in the file tree for client code.
Don't spend a bunch of time investigating code before asking, since it leads to a lot of hang time. This should be an early step in the process.
Quickly check in with the user on gating before you do a deep codebase scan - though you might want to use a quick context check to identify risk.
## How to Use Gates
- Create a new gate, if requested, using the statsig-local MCP server. If this server does not exist, ignore the above.
- After creation, use that gate in code, following the local codebase patterns for accessing statsig.
- This will normally be Statsig.useGate() or similar, but they may have an internal wrapper or use a general feature flag library which wraps Statsig.
- When creating the gate, start it with a default-fail rules. The user, or we, can add rules later to release the gate.
- Add a rule called "Development" which passes the user's ID, specified below. Make sure this is the first evaluated rule.
## Override instructions
- The user's ID is the string ""
- Use a custom ID gate condition, with the userID field set to that ID
## Naming Conventions
- For these features, create a feature gate which is a 3-4 word description separated by dashes.
- Do not use the word killswitch. Propose the name of the gate before creating it, allowing the user to update it if desired. Do not include your name (e.g. codex, claude, cursor) in the gate name.
## Logging
- We would like to measure our gate changes as we roll out features.
- If there's key interactions in the code which are not logged to Statsig, consider logging those events to statsig
- Include critical metadata (e.g. information about what happened, key numeric values)
Propose these logging changes to the user and see what they say, and only if they're very clearly needed. Similar to the gate checks, pattern match to what is in the repo already, e.g.
Statsig.logEvent or a wrapper like LoggingContext.log()
## Statsig Implementation Instructions
[left empty - fill with specific instructions about your Statsig implementation if it exists, such as specific calling patterns or gotchas]
## Guardrails and Critical Rules
- In this context, only use this MCP server to create gates
- Never run deletions or other destructive tools without explicit instructions from the user
```
# Akamai Edge KV
Source: https://docs.statsig.com/integrations/akamai
Run Statsig feature gate and experiment evaluations at the edge with Akamai EdgeWorkers for low-latency rules evaluation in your CDN layer.
## Overview
Statsig’s Akamai Edge KV integration pushes Statsig Configs to Edge KV, providing low latency for gate and experiment evaluations directly in Akamai Edge KV. If you have the correct prerequisites - this should take \~60 minutes to get to the point where you are able to check experiments or gates on Akamai.
## Prerequisites
You must have these prerequisites:
1. An Akamai account with [EdgeWorkers added to your contract](https://techdocs.akamai.com/edgeworkers/docs/add-edgeworkers-to-contract) and a Statsig account
2. [The Akamai CLI](https://developer.akamai.com/getting-started/cli)
## Setup Akamai EdgeWorker
1. Create an [EdgeWorker ID](https://techdocs.akamai.com/edgeworkers/docs/create-an-edgeworker-id-1)
2. Add the [EdgeWorker Behavior](https://techdocs.akamai.com/edgeworkers/docs/add-the-edgeworker-behavior-1)
3. Install the [Akamai CLI](https://developer.akamai.com/getting-started/cli)
4. Install the [Edgeworkers CLI](https://techdocs.akamai.com/edgeworkers/docs/akamai-cli#edgeworkers-cli)
5. Generate [EdgeGrid credentials](https://techdocs.akamai.com/developer/docs/edgegrid)
## Configure Integration
First, enable the Akamai integration in the Statsig Console.
Navigate to [Project Settings -> Integrations](https://console.statsig.com/integrations), and then select Akamai
### Authentication
You will need to input the following EdgeGrid credentials from the previous section:
```js theme={null}
const messages = [
{ role: "system", content: "You are a helpful assistant. You will talk like a pirate." },
{ role: "user", content: "What is the best way to train a parrot?" },
];
const result = await modelClient.complete(messages);
for (const choice of result.choices) {
console.log(choice.message.content);
}
```
```python theme={null}
response = modelClient.complete([
SystemMessage(content="You are a helpful assistant. You will talk like a pirate."),
UserMessage(content="What is the best way to train a parrot?")
])
self.assertIsNotNone(response, "Expected response to not be None")
for item in response.choices:
content = item.message.content
print(content)
```
```csharp theme={null}
var completion = await modelClient.Complete(
"You are a helpful assistant that speaks like a pirate",
"How do you train a parrot in 10 easy steps?"
);
Console.WriteLine(completion);
```
#### Output
```
Arrr, trainin’ a parrot be quite the adventure, savvy? Here be some tips fer ye:
1. **Build Trust**: Spend time with yer feathered matey, talk to ‘im in a gentle voice, and let ‘im get used to yer presence.
2. **Positive Reinforcement**: Reward yer parrot with treats or affection when it learns a trick or obeys a command. Parrots, like all creatures, respond well to praise!
3. **Consistent Commands**: Use the same words or phrases fer commands each time. Repeatin’ yerself helps the parrot make connections.
4. **Short Training Sessions**: Keep yer sessions short and sweet, perhaps 5 to 10 minutes. Parrots have short attention spans, ye see!
5. **Be Patient**: Not every parrot learns at the same pace. Keep yer cool, and don't lose yer temper; patience be key!
6. **Fun and Play**: Incorporate games into yer training to keep it interestin’. A happy parrot be a learnin’ parrot!
Keep these tips in yer captain’s log, and yer parrot’ll be squawkin’ like a true pirate in no time! Arrr!
```
## Streaming Completions
Sometimes you want to start streaming the AI responses back to your client, to reduce latency and increase responsiveness. You can accomplish that by using the Streaming API
```js theme={null}
const messages = [
{ role: "system", content: "You are a helpful assistant. You will talk like a pirate." },
{ role: "user", content: "What is the best way to train a parrot?" },
];
const stream = await modelClient.streamComplete(messages);
for await (const event of stream) {
if (event.data === "[DONE]") {
return;
}
for (const choice of JSON.parse(event.data)?.choices) {
process.stdout.write(choice.delta?.content ?? "");
}
}
```
```python theme={null}
response = modelClient.stream_complete([
SystemMessage(content="You are a helpful assistant. You will talk like a pirate."),
UserMessage(content="What is the best way to train a parrot?")
])
for update in response:
print(update.choices[0].delta.content or "", end="", flush=True)
```
```csharp theme={null}
var completion = await modelClient.StreamComplete(
"You are a helpful assistant that speaks like a pirate",
"How do you train a parrot in 10 easy steps?"
);
await foreach (var update in completion) {
if (!string.IsNullOrEmpty(update.ContentUpdate)) {
Console.Write(update.ContentUpdate);
}
}
```
# Text Embeddings
Source: https://docs.statsig.com/integrations/azureai/embeddings
Instrument Azure OpenAI embeddings calls with Statsig to log inputs, vectors, and metadata for AI evaluations and downstream experiments.
Embeddings are numerical representations of data (like text, images, or audio) that capture their essential features in a compact form, typically as vectors. For text, embeddings map words or sentences to vector spaces, where similar items are closer together, enabling comparisons and efficient searches. Developers use embeddings in tasks like semantic search, recommendation engines, and clustering, as they allow for analyzing and processing unstructured data with machine learning models that recognize and work with these patterns.
## Generate text embeddings
```js theme={null}
const result = await modelClient.getEmbeddings([
"Hello, world!",
"Goodbye, world!",
]);
for (const data of result.data) {
console.log(`Embedding: ${data.embedding}`);
}
```
```python theme={null}
response = modelClient.get_embeddings(["Hello, world!", "Goodbye, world!"])
for item in response.data:
length = len(item.embedding)
print(
f"data[{item.index}]: length={length}, [{item.embedding[0]}, {item.embedding[1]}, "
f"..., {item.embedding[length-2]}, {item.embedding[length-1]}]"
)
```
```csharp theme={null}
var embedding = await client.GetEmbeddings(["Hello, world!", "Goodbye, world!"]);
Console.WriteLine(embedding.First().ToArray());
Console.WriteLine(embedding.Last().ToArray());
```
#### Output
```
Embedding: -0.01918462,-0.025279032,-0.0017195191,0.018848283,-0.033795066,-0.019695852,-0.020947022,0.05158053,-0.03212684,-0.03037789,-0.0021458254,-0.028978731,-0.0024737532,-0.031481072,0.01033225,0.018606123,-0.046145335,0.041463535,0.00044186175,0.041221373,0.053679265,0.001873393,0.004567446,0.01002282,0.047867376,0.0022013208,-0.009834472,0.03847687,0.00089213194,-0.052118666,0.051150016,-0.03255735,-0.0140319485,-0.01263279, .....
```
# Getting Started
Source: https://docs.statsig.com/integrations/azureai/getting-started
Get started with the Statsig Azure OpenAI integration to log AI requests, capture metrics, and run experiments on prompts, models, and parameters.
## Step 1: Install the SDK in your server app
Start by installing the Statsig Azure AI SDK. Depending on your language/framework you would use the right package manager to install the SDK in your project
```shell theme={null}
npm i @statsig/azure-ai
```
```shell theme={null}
pip install azureai-statsig
```
```shell theme={null}
dotnet add package StatsigAzureAI
```
## Step 2: Create a model deployment in Azure AI Studio
Log into your Azure AI Studio console and create a new deployment that you'd like to use.
This guide assumes you have an existing Statsig account. Please go here to create a new free account if you don't already have one: [https://statsig.com/signup](https://statsig.com/signup)
Go to your **Project Settings** and choose the **Keys & Environments** tab on the left. Scroll down to **API Keys** section and copy the Server Secret Key. If one doesn't exist, you will have to create one, or ask your project admin to create one for you.
```js theme={null}
import { AzureAI } from "@statsig/azure-ai";
await AzureAI.initialize("");
```
```python theme={null}
AzureAI.initialize("")
```
```csharp theme={null}
using Statsig;
using Statsig.AzureAI;
await Server.Initialize("");
```
# Azure AI
Source: https://docs.statsig.com/integrations/azureai/introduction
Introduction to the Statsig Azure OpenAI integration for logging AI calls, capturing metrics, and running experiments on prompts and model parameters.
Statsig offers SDKs for integrating Azure AI models into server applications. These SDKs simplify the implementation of features like completions and embeddings in your server application. They provide easy-to-use APIs and automatically track metrics such as latency, token length, and model details, which you can use for optimization and experimentation. Use cases include:
* Implement Azure AI Models in your code with a [single lightweight framework](/azureai/model-client)
* [Stream completions](/azureai/completions) and [generate embeddings](/azureai/embeddings)
* [Capture invocation and usage metrics](/azureai/capturing-metrics/) with no extra work
* [Run A/B tests on parameters](/azureai/running-experiments) like model, prompt, temperature and more
```js theme={null}
const client = AzureAI.getModelClient("");
```
```python theme={null}
client = AzureAI.get_model_client("")
```
```csharp theme={null}
var client = Server.GetModelClient("");
```
## Option 2: Using hard-coded endpoint and key
This is the most direct way of instantiating an AI model client. However, this would mean you'll have to embed the endpoint and key in your code, or use another way (like an environment variable) to get the model endpoint and key into the process.
```js theme={null}
const modelClient = AzureAI.getModelClientFromEndpoint(
"",
""
);
```
```python theme={null}
modelClient = AzureAI.get_model_client_from_endpoint("", "")
```
```csharp theme={null}
var modelClient = Server.GetModelClientFromEndpoint(
"",
""
);
```
# Running A/B Tests
Source: https://docs.statsig.com/integrations/azureai/running-experiments
Run experiments on Azure OpenAI prompts, models, and parameters with Statsig, including variant configuration, exposure logging, and result analysis.
Azure AI SDK helps you easily and quickly run A/B tests to measure the effectiveness of different models and related parameters. By leveraging Statsig's powerful stats engine, you can gain real-time insights into model performance, optimizing for metrics like cost, accuracy, and latency. This integration enables you to experiment with various configurations, such as model type, prompt settings, or response parameters, and make data-driven decisions to enhance your application's efficiency and user experience.
## Example: Test GPT4o vs. GPT4o-mini
### Step 1: Create configs
Create two dynamic configs, one named `gpt-4o` and another named `gpt-4o-mini`. In the **Value** section add the endpoint, key and other default parameters like this:
Navigate to [Project Settings -> Integrations](https://console.statsig.com/integrations), in the Statsig Console, then select Cloudflare, and input:
* **Cloudflare Account ID**: Can be found in Cloudflare portal on the Compute (Workers) page, under Account Details
* **KV Namespace ID**: Create a new namespace, then go to Account Home -> Storage and Databases -> Workers KV, and copy the ID from the table view.
* **Cloudflare API Key**: In Cloudflare portal under Account Home -> Profile -> API Tokens. Use a token with Account.Workers KV Storage Edit Permissions.
You can also filter the configs that are synced to your KV namespace by Target App. This becomes important as you add more configs to your project, but for now, you can leave this unchecked.
Click **Enable**, then the Statsig backend will push a config to your KV namespace (\<60 seconds). In your KV namespace, navigate to **KV Pairs** - you'll see entry starting with `statsig-`. This is the `key` associated with your KV storage. Note this key down for later.
Now, we'll set up a worker to read those experiments and gates from your KV namespace. If you've never created a worker before, you can follow the instructions [here](https://developers.cloudflare.com/workers/).
After creating your worker, you will need to connect your KV store to your worker through a binding. Navigate to **Compute (Workers)** -> **Select Your Worker** -> **Bindings** -> **Add binding** -> **KV namespace**. Name your binding under **Variable name**. Under **KV namespace**, select your KV store name. For more information on connecting your worker to your KV store, you can follow the instructions [here](https://developers.cloudflare.com/pages/functions/bindings/).
Install the Statsig serverless SDK:
```bash theme={null}
npm install @statsig/serverless-client
```
The helper method takes two arguments, a handler function, and a ParamsObject. **Put *all* of your worker logic in the handler function**, along with your Statsig usage.
```javascript highlight={5} theme={null}
import { handleWithStatsig } from '@statsig/serverless-client/cloudflare';
export default handleWithStatsig(
async (request, env, ctx, client) => {
// Your business, and Statsig logic here
},
{
kvKey: 'kv_key',
envStatsigKey: 'statsig_key',
envKvBindingName: 'STATSIG_KV'
}
);
```
The required ParamsObject params (kvKey, envStatsigKey, envKvBindingName) must be stored as env variables, either in your wrangler.toml or as Cloudflare secrets.
Environment variable name containing your KV pair key
Environment variable name containing your Statsig client key
Your KV binding name
See StatsigOptions [here](/client/javascript-sdk#statsig-options)
**Best practice:**
* store `envStatsigKey` as a Cloudflare secret. You can set this in the Cloudflare dashboard under, **Worker → Settings → Variables and Secrets**
* store `kvKey` and `envKvBindingName` in your wrangler.toml
### Example Usage
This is an example of an end-to-end worker function that uses the Statsig SDK and returns a flag value. This is all you need - this will compile as the index.js file in your worker.
```javascript index.js expandable theme={null}
import { handleWithStatsig } from '@statsig/serverless-client/cloudflare';
export default handleWithStatsig(
async (request, env, ctx, client) => {
const randomUserId = Math.floor(Math.random() * 100).toString();
const gate = client.getFeatureGate("test_cloudflare_sync", { userID: randomUserId });
const value = gate.value;
client.logEvent('new_event', { userID: randomUserId });
return new Response(`Gate check result: ${value}`);
},
{
kvKey: 'kv_key',
envStatsigKey: 'statsig_key',
envKvBindingName: 'STATSIG_KV'
}
);
```
```wrangler wrangler.toml theme={null}
name = "test"
main = "src/index.js"
compatibility_date = "2025-09-10"
[vars]
kv_key = "statsig-1gh32fg61hds9876"
[[kv_namespaces]]
binding = "STATSIG_KV"
id = "b76664aa8259481e834e7c549443c6541"
[observability]
enabled = true
```
**That's it!** The helper automatically:
* Initializes the Statsig Client with config specs from your KV store
* Executes your handler code (Your business logic + Statsig usage)
* Flushes all events after your handler completes execution
* Cleans up resources
**Use the advanced/manual setup if:**
* You need fine-grained control over initialization timing
* You need fine-grained control over event flushing timing
* You need to customize error handling behavior
## Prerequisites
1. Completed the [Statsig Cloudflare KV integration setup](#configure-integration)
2. [Created and bound a KV namespace to your worker](#add-the-statsig-sdk-to-your-worker)
## Installation
First, you'll need to install the Statsig serverless sdk.
```bash theme={null}
npm install @statsig/serverless-client
```
## Import
Next, import the Cloudflare client.
```bash theme={null}
import { StatsigCloudflareClient } from '@statsig/serverless-client/cloudflare';
```
Then, you need to hook it all up. This involves:
1. Creating a `StatsigCloudflareClient` instance.
2. Initializing the Statsig client
3. Checking a Gate
4. Logging an event
5. Flushing events to Statsig
If you've used a Statsig sdk in the past, these steps should be familiar. The usage will be the same, the only difference is the sdk will initialize from the KV store instead of the statsig backend.
In our example, we are checking a gate called "test\_cloudflare\_sync" that is set to a 50% pass rate. We create a random userID on every request, and we should see it evaluate to true 50% of the time.
### 1. Creating a `StatsigCloudflareClient` instance
```bash theme={null}
const client = new StatsigCloudflareClient("");
```
The client instantiation takes two arguments:
* `sdkKey : string` This is your Statsig client API key. It is available from the [Project Settings](https://console.statsig.com/api_keys) page in the Statsig Console. This is used to authenticate your requests.
* `options : StatsigOptions` See here, for more [options](/client/javascript-sdk#statsig-options).
For best practice:
* store `sdkKey` as a Cloudflare secret. You can set this in the Cloudflare dashboard under, **Worker → Settings → Variables and Secrets**
### 2. Client initialization
The following line initializes the client by loading feature gate and experiment configurations directly from your Cloudflare KV store.
```bash theme={null}
const initResult = await client.initializeFromKV(env., );
```
The client initialization takes two arguments:
* `KvBinding` This is the binding you named earlier. Remember to provide this argument as `env.YOUR_KV_NAMESPACE_BINDING`
* `KvKey : string` This is the KV pair key that was generated through the Statsig integration. It can be found under **Workers KV** -> **Your KV namespace** -> **KV Pairs**
For best practice:
* store `kvBinding` and `kvKey` in your wrangler.toml
### 3. Checking a Gate
```bash theme={null}
const value = client.checkGate("test_cloudflare_sync", { userID: randomUserId });
```
This is a gate check in code.
The `checkGate` method takes two arguments:
* `name : string` The name of the Statsig gate that you are checking.
* `user : StatsigUser` The Statsig user object for whom the gate is being checked. For more information on the user object, see [here](/sdks/user#introduction-to-the-statsiguser-object).
Refer to the [Javascript on device evaluation sdk documentation](/client/jsOnDeviceEvaluationSDK) for how to check other entities like experiments and dynamic configs.
### 4. Logging an event
```bash theme={null}
client.logEvent('gate_check', { userID: randomUserId });
```
This is an event log in code.
The `logEvent` method takes two parameters:
* `eventOrName : string | StatsigEvent` This is the name and details of the event you are logging.
* `user : StatsigUser` The Statsig user object for whom the event is being logged.
For more information on event logging, see [here](/client/jsOnDeviceEvaluationSDK#logging-an-event).
### 5. Flushing Events
```bash theme={null}
ctx.waitUntil(statsig.flush());
```
This flushes all events from the sdk to Statsig. **Without this, you won't be able to get diagnostic information in the Statsig Console, nor any event data you logged**.
### Putting it all together
```Javascript theme={null}
import { StatsigCloudflareClient } from '@statsig/serverless-client/cloudflare';
export default {
async fetch(request, env, ctx) {
try {
const client = new StatsigCloudflareClient(env.statsig_key);
const initResult = await client.initializeFromKV(env.STATSIG_KV, env.kv_key);
const randomUserId = Math.floor(Math.random() * 100).toString(); //generates a random user id
const value = client.checkGate("test_cloudflare_sync", { userID: randomUserId });
client.logEvent('gate_check', { userID: randomUserId });
ctx.waitUntil(client.flush());
return new Response(`Value: ${value}, userID: ${randomUserId});
} catch (error) {
return new Response(`Error: ${error.message}`, { status: 500 });
}
}
};
```
```wrangler theme={null}
name = "test"
main = "src/index.js"
compatibility_date = "2025-09-10"
[vars]
kv_key = "statsig-1gh32fg61hds9876"
[[kv_namespaces]]
binding = "STATSIG_KV"
id = "b76664aa8259481e834e7c549443c6541"
[observability]
enabled = true
```
If you want to check on the evaluations you are getting, you can go to the gate you created for this example and look at the evaluations in the Diagnostics tab.
# Amplitude
Source: https://docs.statsig.com/integrations/data-connectors/amplitude
Connect Amplitude with Statsig to import events and metrics for experiment analysis or export Statsig data into Amplitude dashboards and notebooks.
## Overview
Statsig supports both incoming and outgoing events for Amplitude. As well as adding Amplitude Cohorts to Statsig ID Lists.
## Incoming - Receiving Events From Amplitude
Ingestion with this integration is available only for Statsig Cloud. For Warehouse Native, create a metrics source that references this data in your warehouse.
The following steps outline how to forward events from Amplitude into Statsig.
1. Get a Statsig "Server Secret Key" from the API keys page in [Project Settings](https://console.statsig.com/api_keys).
2. Go to Amplitude and navigate to the Data Destinations page. Click the
"Add Destination" button in the top right.
This is available for Enterprise contracts. Please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
### What is it?
Our Amplitude Integration offers the flexibility to forward first exposures instead of every exposure, reducing the overall number of events being forwarded. First exposures are calculated daily and forwarded to integrations at around 7pm UTC.
### How to enable
First ensure that the "first exposure" feature has been enabled for your company by reaching out to support team, your sales contact, or via our [Slack community](https://statsig.com/slack).
Once this is done you will be able to go into the event filtering tab of the integration and enabled "First Exposure" setting.
### Example Events In Amplitude
Example of a get\_experiment First Exposure in Amplitude.
Ensure you create and use a console API key from your [Statsig project settings](https://console.statsig.com/api_keys)
## Filtering Events
You can customize which events should be sent and received via Amplitude using [Event Filtering](/integrations/event_filtering)
# Braze
Source: https://docs.statsig.com/integrations/data-connectors/braze
Connect Braze with Statsig to send messaging events to Statsig for experiment analysis and to use Statsig audiences in Braze campaigns.
## Overview
Enabling the Braze integration allows you to export Statsig exposure events to your configured Braze app with information on the status of each user's feature gate and experimentation groups. These exposures will be forwarded to Braze as a [Custom Attribute](https://www.braze.com/docs/user_guide/data/custom_data/custom_attributes) object on the user. There will be one Custom Attribute per gate/experiment the user has been exposed to. The Custom Attribute in Braze will be named `statsig_exposure::{gate/experiment name}` and be of the form:
```
{
group_name: String,
timestamp: Time
}
```
You can then filter exposed users into a Segment in Braze. Custom Attributes will be forwarded to Braze users by having the unit ID from the gate/experiment as the `external_id` in Braze by default. You can choose to provide a custom Unit ID Type from your Statsig project to be forwarded as the `external_id` for all gate/experiment exposures. This can be provided in the ID Type Mapping section of the Setup dialog for this integration. The integration will attempt to use this custom ID Type if it is provided in the SDK call at the time of exposure, and will fall back to the experiment's Unit ID Type if not.
## Setup in Statsig
This is available for Enterprise contracts. Please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
After it has been enabled, you will be able to find 'Braze' as an option in your Statsig project's [list of integrations](https://console.statsig.com/integrations) from within Statsig console.
1. Open your [Braze dashboard](https://dashboard.braze.com/). Navigate to Settings > APIs and Identifiers, then open the API Keys tab.
2. Create or select an existing API key that has the 'users.track' permission. Enter the API Key Identifier in the Braze Integration Setup dialog in your Statsig project.
3. Find your Instance's REST Endpoint from the [Braze API docs](https://www.braze.com/docs/api/basics/#api-definitions/). Enter it in the Integration Setup dialog.
## Segment Filtering in Braze
Once your integration is set up in Statsig, exposures can start firing into your Braze app. When exposures arrive in Braze from a new gate/experiment, you can create a filter on these users.
1. Open your [Braze dashboard](https://dashboard.braze.com/). Navigate to Data Settings > Custom Attributes. You should see your new Custom Attribute from Statsig like below:
This is available for Enterprise contracts. Please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
### What is it?
Our Braze Integration offers the flexibility to forward first exposures instead of every exposure, reducing the overall number of events being forwarded. First exposures are calculated daily and forwarded to integrations at around 7pm UTC.
### How to enable
First ensure that the "first exposure" feature has been enabled for your company by reaching out to support team, your sales contact, or via our [Slack community](https://statsig.com/slack).
Once this is done you will be able to go into the event filtering tab of the integration and enabled "First Exposure" setting.
# Census
Source: https://docs.statsig.com/integrations/data-connectors/census
Connect Census reverse ETL with Statsig to sync audience segments and metric data between your data warehouse and Statsig for activation.
## Overview
Enabling the [Census](https://getcensus.com/) integration for Statsig allows Statsig to receive events from Census. This enables you to ingest data into Statsig from any sources that Census supports.
You can find all events that Statsig receives from Census in the [Metrics](/metrics) tab in the Statsig console. Statsig will automatically include these events in [Pulse](/pulse/read-pulse) and [Experiment](/experiments-plus/monitor) results for your feature gates and experiments respectively.
## Configuring Incoming Events
1. From the [API Keys](https://console.statsig.com/api_keys) tab in the Statsig console, copy the Statsig "Server Secret Key”.
2. From census, create a new [destination](https://docs.getcensus.com/destinations/overview) and select Statsig from the list of options.
3. Paste the Statsig secret into the field and click save.
The input Event Field must match the exact spelling as in the original Census event.
`config` - Name of the experiment/gate/dynamic config
`group` - Name of the exposed group (e.g. Control)
`value` - Value for custom events
`statsig_session_id` - Session ID
`category` - Type of exposure or name of the custom event (e.g. `statsig_gate_exposure`)
`unit_id` - Value of the unit ID (e.g. '123')
`unit_id_type` - Type of the unit ID (e.g. 'stableID')
## Filtering Events
Once the outgoing integration has been enabled, you can optionally configure event filtering to control whch events are populating the GA4 Data Stream:
This is available for Enterprise contracts. Please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
### What is it?
Our Heap Integration offers the flexibility to forward first exposures instead of every exposure, reducing the overall number of events being forwarded. First exposures are calculated daily and forwarded to integrations at around 7pm UTC.
### How to enable
First ensure that the "first exposure" feature has been enabled for your company by reaching out to support team, your sales contact, or via our [Slack community](https://statsig.com/slack).
Once this is done you will be able to go into the event filtering tab of the integration and enabled "First Exposure" setting.
# Hightouch
Source: https://docs.statsig.com/integrations/data-connectors/hightouch
Connect Hightouch reverse ETL with Statsig to sync warehouse-defined audiences and metrics into Statsig for targeting and experiment analysis.
## **Overview**
Enabling the **[Hightouch](https://hightouch.com/)** integration allows you to send events and keep segments up-to-date in Statsig via Hightouch. You can ingest data into Statsig from [any source](https://hightouch.com/integrations) that Hightouch supports.
You can find all events that Statsig receives from Hightouch in the [Metrics](/metrics) tab in the Statsig console, if you’re on a [Pro plan](https://www.statsig.com/pricing). Statsig automatically includes these events in [Pulse](/pulse/read-pulse) and [Experiment](/experiments-plus/monitor) results for your feature gates and experiments respectively. You can view your updated segment lists on the **[Segments](https://console.statsig.com/segments)** page.
## **Event configuration**
1. From the **[API Keys](https://console.statsig.com/api_keys)** tab in the Statsig console, copy the Statsig **Client-SDK API key**.
2. Go to the Hightouch [**Destinations** overview page](https://app.hightouch.com/destinations) and click the **Add destination**
button. Select **Statsig** and click **Continue**. Enter the **Client-SDK API key** and click **Continue**.
3. Give your destination a descriptive name, for example, "Statsig prod."
4. Once you've set up your Statsig destination and have a [model](https://hightouch.com/docs/getting-started/concepts#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs) and click the **Add sync** button to begin. Then, select the relevant model and the Statsig destination you previously set-up.
5. Select **Events** as the sync type.
6. Enter either a static value or select a column that contains **Event names**.
7. Optionally, select a column that contains the event timestamp. If empty, Statsig uses the time the event arrives at the server.
8. Choose source columns to sync as event metadata and user attributes, such as the **User ID**.
9. Finally, select whether you want the first sync to backfill event data or not. For more information about configuration options see [Hightouch’s Statsig docs](https://hightouch.com/docs/destinations/statsig#events).
10. Run the sync and check that events appear in your Statsig **[Metrics](/metrics)** tab.
## Segment configuration
The Hightouch integration lets you keep your segments up-to-date by adding or removing members based on changes in your source dataset.
1. From the **[API Keys](https://console.statsig.com/api_keys)** tab in the Statsig console, copy the Statsig **Console API key.**
2. Go to the Hightouch [**Destinations** overview page](https://app.hightouch.com/destinations) and click the **Add destination**
button. Select **Statsig** and click **Continue**. Enter the **Client-SDK API key** and click **Continue**.
3. Give your destination a descriptive name, for example, "Statsig prod."
4. Once you've set up your Statsig destination and have a [model](https://hightouch.com/docs/getting-started/concepts#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs) and click the **Add sync** button to begin. Then, select the relevant model and the Statsig destination you previously set-up.
5. Select **Segment** as the sync type.
6. Select whether you would like to create a new audience or use an existing audience to sync data to. If creating a new audience, you can give it a name. If you leave this input blank, Hightouch uses the name of your model for the audience.
7. Select the audience's ID type: either **userID** or **stableID**.
8. Select the source column and Statsig field to match records on. For more information see Hightouch's docs on [record matching](https://hightouch.com/docs/syncs/record-matching).
9. [Schedule your sync](https://hightouch.com/docs/syncs/schedule-sync-ui) to run as frequently as you need. You can view your updated segment lists on the **[Segments](https://console.statsig.com/segments)** page.
## Troubleshooting
If you have any questions, don’t hesitate to contact [Hightouch support](https://www.notion.so/Hightouch-page-in-Statsig-docs-42b88b32b82b491d9baf1694049955ab) for assistance.
# Mixpanel
Source: https://docs.statsig.com/integrations/data-connectors/mixpanel
Connect Mixpanel with Statsig to send Mixpanel events to Statsig for experiment analysis and to keep product analytics consistent across both tools.
## Overview
The [Mixpanel](https://mixpanel.com/) integration has two functions.
* Incoming: Statsig can sync your Mixpanel user cohorts with a Statsig ID list segment.
* Outgoing: Statsig can forward Statsig events to Mixpanel.
## Cohort Syncing
Ingestion with this integration is available only for Statsig Cloud. For Warehouse Native, create a metrics source that references this data in your warehouse.
Statsig can ingest user information via a [Mixpanel Cohort Syncing](https://developer.mixpanel.com/docs/cohort-webhooks)
1. On Statsig, navigate to [Segments](https://console.statsig.com/segments) on the left navigation menu and create a segment.
* **Name**: Must match the name of your Mixpanel cohort.
* **Type of segment**: Should be ID List.
Ingestion with this integration is available only for Statsig Cloud. For Warehouse Native, create a metrics source that references this data in your warehouse.
1. From the [API Keys](https://console.statsig.com/api_keys) tab in the Statsig console, copy the Statsig `Server Secret Key`.
2. Use your Statsig `Server Secret Key` to configure a Statsig Event Integration via mParticle's integrations directory.
### Mapping User IDs
In order to associate your mParticle events with your Statsig Feature Gates or Experiments, you must use mParticle's [IDSync framework](https://docs.mparticle.com/guides/idsync/introduction/) to ensure your mParticle events pass along the same user IDs used with the Statsig SDK.
## Configuring Outbound Events
To export your Statsig events to mParticle:
1. Go to your mParticle account and choose `Setup` then `Inputs` on the left-hand column to start configuring your integration.
Ingestion with this integration is available only for Statsig Cloud. For Warehouse Native, create a metrics source that references this data in your warehouse.
## Overview
Enabling the RevenueCat integration allows Statsig to pull billing, subscription, and revenue metrics into your Statsig projects. This provides easy mechanisms to optimize purchases and revenue by using Statsig's feature gates or experimentation tools without any additional logging.
Statsig integrates with RevenueCat through a Webhook and receives data as mentioned [in the RevenueCat documentation](https://docs.revenuecat.com/docs/webhooks)
## Configuring Incoming Metrics
1. Copy your **Statsig Server Secret Key** from the [API Keys](https://console.statsig.com/api_keys) tab in the Statsig console.
2. Navigate to your app in the RevenueCat dashboard and choose **Statsig** from the Integrations menu.
3. Enter your **Statsig Server Secret** and click **Save**.
Ingestion with this integration is available only for Statsig Cloud. For Warehouse Native, create a metrics source that references this data in your warehouse.
To ingest your events from RudderStack,
1. On [app.rudderstack.com](https://app.rudderstack.com/), navigate to "Connections" and click **Add Destination** .
2. Search for “Statsig” in the Destinations Catalog, and select the “Statsig” destination.
3. Give your connection a name and choose which Source should send data to the “Statsig” destination.
4. From the [Statsig dashboard](https://console.statsig.com/api_keys), copy the Statsig "Server Secret Key”.
5. Enter the Statsig “Server Secret Key” in the “Statsig” destination settings in RudderStack.
6. On the Statsig [Integration page](https://console.statsig.com/integrations) enable the RudderStack integration.
7. As your RudderStack events flow into Statsig, you'll see a live **Log Stream** in the [Metrics](/metrics) tab in the Statsig console. You can click one of these events to see the details that are logged as part of the event.
", "stableID", "",]
}
}
```
The `statsigCustomIDs` field in properties should be an array, where the even index is the name of the user ID type and the odd index is the value of the previous element in the array. Assuming you've created this custom ID type on Statsig (under **ID Type Settings** in your [Project Settings](https://console.statsig.com/settings)), Statsig will automatically recognize these custom identifiers to compute your experiment results appropriately.
#### Environments
By default, all events are treated as "production" events, but you can also differentiate your event traffic by specifying the environment that the events are coming from.
This allows you to avoid non-production data making it into your production metrics.
If you would like to include the environment tier, you can add it to the properties object of your event.
The required format is below:
```json theme={null}
{
...
"properties": {
"statsigEnvironment": {
"tier": "staging"
}
}
}
```
To learn more about environments see [Using Environment](/guides/using-environments).
## Configuring Outbound Events
To export your Statsig events to RudderStack,
1. Log into the Statsig console and navigate to the [**Integrations**](https://console.statsig.com/integrations) page.
2. Click on the **RudderStack** card and switch to the **Outbound** tab.
3. Follow the steps outlined in [RudderStack's Webhook Source](https://www.rudderstack.com/docs/stream-sources/webhook-source/) to get the required "Write Key" and "Data Plane URL".
4. Once filled out, hit enable to save your changes.
## Filtering Events
You can customize which events should be sent and received via RudderStack using [Event Filtering](/integrations/event_filtering)
# Segment
Source: https://docs.statsig.com/integrations/data-connectors/segment
Connect Segment with Statsig to forward customer data platform events to Statsig for experiment analysis, metrics, and audience targeting.
Enabling the Segment integration for Statsig will allow Statsig to pull in your Segment events. This allows you to run your experiment analysis on Statsig with all of your existing events from Segment without requiring any additional logging.
When Statsig receives events from Segment, these will be visible and aggregated in the [Metrics](/metrics) tab in the Statsig console. These events will automatically be included in your [Pulse](/pulse/read-pulse) results for A/B tests with Statsig's feature gates as well as all your [Experiment](/experiments-plus/monitor) results.
### Supported Segment Event Types
* [Track](https://segment.com/docs/connections/spec/track/)
* [Page](https://segment.com/docs/connections/spec/page/)
* [Group](https://segment.com/docs/connections/spec/group/)
* [Screen](https://segment.com/docs/connections/spec/screen/)
* [Identify\*](https://segment.com/docs/connections/spec/identify/)
Identify calls are only supported for syncing Segment Engage Audiences with Statsig Segments
### Benefits of using the Segment integration
Using the Segment integration has several benefits over other methods of event ingestion:
* Customers who are ingesting customer data with Segment will be able to quickly populate Statsig with metrics and can typically get up and running within a day
* Customers will only have to use Statsig's assignment SDKs (gate/experiment allocation), simplifying your code and engineer workflows
* Additional logging can be done via the [event logging SDKs](/guides/logging-events#logging-events-via-sdks) but will and additional code orchestration and a collection window
* With [event filtering](/integrations/event_filtering) you can control which events are ingested and make billing more predictable
* If you have [Segment Replay](https://segment.com/docs/guides/what-is-replay/), you can forward up to 7 days of historical events to Statsig for analysis
## Configuring Inbound Events into Statsig
Ingestion with this integration is available only for Statsig Cloud. For Warehouse Native, create a metrics source that references this data in your warehouse.
To send events collected from Segment into Statsig, you must configure the Statsig Destination within the your Segment account:
### Using OAuth
The easiest way to connect Statsig to Segment is via OAuth.
1. To get started, within the Statsig Console, go to **project settings → integrations → Segment → Enable**
2. Click “Configure Segment OAuth”
"]
}
}
```
The `statsigCustomIDs` field in properties should be an array, where the even index is the name of the user ID type and the odd index is the value of the previous element in the array. Assuming you've created this custom ID type on Statsig (under **ID Type Settings** in your [Project Settings](https://console.statsig.com/settings)), Statsig will automatically recognize these custom identifiers to compute your experiment results appropriately.
### Anonymous Users
#### Mapping anonymous users
The Segment integration also allows the mapping of top level fields to custom IDs you define in Statsig. To do this, visit the Segment panel on the Statsig Integrations page and look for the "Map Identifier" section. Here you can choose fields you would like mapped to a [Custom ID](/guides/experiment-on-custom-id-types).
This is particularly useful for working with the [Segment anonymous ID](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/identity/#anonymous-ids), which is passed as an event field `anonymousId`. By defining a custom ID called `segmentAnonymousId`, Statsig can easily map your anonymous Segment traffic to your metric data.
Values passed in `properties.statsigCustomIDs` will take precedence over mapped identifiers below.
It's important to note, that the Segment SDK may initialize after Statsig SDK, and the `anonymousId` may not be available in that scenario. It's important to check this in your specific implementation. If you're using vanilla javascript, you may want to wait for the `anonymousId` from the Segment SDK after initialization and call the `updateUser()` method on the Statsig SDK to update this ID.
#### Example Mapping Flow
Refer to the following diagram to help orient you to mapping `anonymousIds` in Segment to a custom ID representing anonymous users in Statsig:
Segment events are prepended with `segment::` so they can be easily distinguished from other sources
Data Warehouse Exports are an Enterprise-only feature. If you are on the Developer or Pro tiers and wish to upgrade to Enterprise, feel free to reach out to our team [here](https://www.statsig.com/contact/demo) or via support.
## How to Begin
1. Go to Statsig Console
2. Navigate to the Help and Tools Section on the side navigation bar
3. Go to “Exports List”
**Setup summary**
Configure:
* BigQuery Project ID
* BigQuery Dataset ID
* one destination table name per export type
Permissions:
* grant the Statsig service account `BigQuery User` at the project level
* grant the same service account `BigQuery Data Editor` on the target dataset
Statsig uses this access to create the table if needed and validate the connection by inserting and deleting a test row.
If you prefer to create the export tables yourself, you can use SQL like this:
```sql BigQuery Exposures theme={null}
CREATE TABLE IF NOT EXISTS `PROJECT_ID.DATASET_ID.EXPOSURES_TABLE` (
company_id STRING,
unit_id STRING,
unit_type STRING,
exposure_type STRING,
name STRING,
rule STRING,
experiment_group STRING,
first_exposure_utc TIMESTAMP,
first_exposure_pst_date DATE,
as_of_pst_date DATE,
percent FLOAT64,
rollout BIGINT,
user_dimensions STRING,
inserted_at TIMESTAMP,
rule_name STRING,
group_id STRING,
non_analytics BOOLEAN
);
```
```sql BigQuery Events theme={null}
CREATE TABLE IF NOT EXISTS `PROJECT_ID.DATASET_ID.EVENTS_TABLE` (
user_id STRING,
stable_id STRING,
custom_ids JSON,
timestamp TIMESTAMP,
event_name STRING,
event_value STRING,
user_object JSON,
statsig_metadata JSON,
company_metadata JSON
);
```
**Exposures**
Please note that we do not export exposures from rules that are 0%/100%.
| Field name | Type | Mode |
| -------------------------- | --------- | -------- |
| company\_id | STRING | NULLABLE |
| unit\_id | STRING | NULLABLE |
| unit\_type | STRING | NULLABLE |
| exposure\_type | STRING | NULLABLE |
| name | STRING | NULLABLE |
| rule | STRING | NULLABLE |
| experiment\_group | STRING | NULLABLE |
| first\_exposure\_utc | TIMESTAMP | NULLABLE |
| first\_exposure\_pst\_date | DATE | NULLABLE |
| as\_of\_pst\_date | DATE | NULLABLE |
| percent | FLOAT64 | NULLABLE |
| rollout | BIGINT | NULLABLE |
| user\_dimensions | STRING | NULLABLE |
| inserted\_at | TIMESTAMP | NULLABLE |
| rule\_name | STRING | NULLABLE |
| group\_id | STRING | NULLABLE |
| non\_analytics | BOOLEAN | NULLABLE |
**Events**
| Field name | Type | Mode |
| ----------------- | --------- | -------- |
| user\_id | STRING | NULLABLE |
| stable\_id | STRING | NULLABLE |
| custom\_ids | JSON | NULLABLE |
| timestamp | TIMESTAMP | NULLABLE |
| event\_name | STRING | NULLABLE |
| event\_value | STRING | NULLABLE |
| user\_object | JSON | NULLABLE |
| statsig\_metadata | JSON | NULLABLE |
| company\_metadata | JSON | NULLABLE |
**Setup summary**
Configure:
* Account Name
* Database Name
* Schema Name
* either Username and Password, or Private Key authentication
* one destination table name per export type
Permissions:
* the configured user must be able to create tables and insert/delete rows in the target database and schema
If you prefer to create the export tables yourself, you can use SQL like this:
```sql Snowflake Exposures theme={null}
CREATE TABLE IF NOT EXISTS DATABASE_NAME.SCHEMA_NAME.EXPOSURES_TABLE (
company_id STRING,
unit_id STRING,
unit_type STRING,
exposure_type STRING,
name STRING,
rule STRING,
experiment_group STRING,
first_exposure_utc TIMESTAMP,
first_exposure_pst_date DATE,
as_of_pst_date DATE,
percent DOUBLE,
rollout BIGINT,
user_dimensions STRING,
inserted_at TIMESTAMP,
rule_name STRING,
group_id STRING,
non_analytics BOOLEAN
);
```
```sql Snowflake Events theme={null}
CREATE TABLE IF NOT EXISTS DATABASE_NAME.SCHEMA_NAME.EVENTS_TABLE (
user_id STRING,
stable_id STRING,
custom_ids STRING,
timestamp TIMESTAMP,
event_name STRING,
event_value STRING,
user_object STRING,
statsig_metadata STRING,
company_metadata STRING
);
```
**Exposures**
| Field name | Type | Mode |
| -------------------------- | --------- | -------- |
| company\_id | STRING | NULLABLE |
| unit\_id | STRING | NULLABLE |
| unit\_type | STRING | NULLABLE |
| exposure\_type | STRING | NULLABLE |
| name | STRING | NULLABLE |
| rule | STRING | NULLABLE |
| experiment\_group | STRING | NULLABLE |
| first\_exposure\_utc | TIMESTAMP | NULLABLE |
| first\_exposure\_pst\_date | DATE | NULLABLE |
| as\_of\_pst\_date | DATE | NULLABLE |
| percent | DOUBLE | NULLABLE |
| rollout | BIGINT | NULLABLE |
| user\_dimensions | STRING | NULLABLE |
| inserted\_at | TIMESTAMP | NULLABLE |
| rule\_name | STRING | NULLABLE |
| group\_id | STRING | NULLABLE |
| non\_analytics | BOOLEAN | NULLABLE |
**Events**
| Field name | Type | Mode |
| ----------------- | --------- | -------- |
| user\_id | STRING | NULLABLE |
| stable\_id | STRING | NULLABLE |
| custom\_ids | STRING | NULLABLE |
| timestamp | TIMESTAMP | NULLABLE |
| event\_name | STRING | NULLABLE |
| event\_value | STRING | NULLABLE |
| user\_object | STRING | NULLABLE |
| statsig\_metadata | STRING | NULLABLE |
| company\_metadata | STRING | NULLABLE |
**Setup summary**
Configure:
* Cluster Endpoint
* Username and Password
* Staging Schema
* one destination table name per export type
Permissions:
* the configured user must be able to create tables and insert/delete rows in the target database and schema
* if your cluster is not directly reachable, you can also configure SSH tunneling
If you prefer to create the export tables yourself, you can use SQL like this:
```sql Redshift Exposures theme={null}
CREATE TABLE IF NOT EXISTS "DATABASE_NAME"."STAGING_SCHEMA"."EXPOSURES_TABLE" (
"company_id" VARCHAR,
"unit_id" VARCHAR,
"unit_type" VARCHAR,
"exposure_type" VARCHAR,
"name" VARCHAR,
"rule" VARCHAR,
"experiment_group" VARCHAR,
"first_exposure_utc" TIMESTAMP,
"first_exposure_pst_date" DATE,
"as_of_pst_date" DATE,
"percent" DOUBLE PRECISION,
"rollout" BIGINT,
"user_dimensions" VARCHAR,
"inserted_at" TIMESTAMP,
"rule_name" VARCHAR,
"group_id" VARCHAR,
"non_analytics" BOOLEAN
);
```
```sql Redshift Events theme={null}
CREATE TABLE IF NOT EXISTS "DATABASE_NAME"."STAGING_SCHEMA"."EVENTS_TABLE" (
"user_id" VARCHAR,
"stable_id" VARCHAR,
"custom_ids" VARCHAR,
"timestamp" TIMESTAMP,
"event_name" VARCHAR,
"event_value" VARCHAR,
"user_object" VARCHAR,
"statsig_metadata" VARCHAR,
"company_metadata" VARCHAR
);
```
Note: the default size for VARCHAR is 256 and we truncate all columns to 256 characters for Redshift.
If you anticipate certain columns will exceed these limits, please adjust accordingly and let us know to remove these limits.
Common longer columns are `user_dimensions` in exposures and `user_object`, `custom_ids`, and `company_metadata` in events.
**Exposures**
| Field name | Type | Mode |
| -------------------------- | ---------------- | -------- |
| company\_id | VARCHAR | NULLABLE |
| unit\_id | VARCHAR | NULLABLE |
| unit\_type | VARCHAR | NULLABLE |
| exposure\_type | VARCHAR | NULLABLE |
| name | VARCHAR | NULLABLE |
| rule | VARCHAR | NULLABLE |
| experiment\_group | VARCHAR | NULLABLE |
| first\_exposure\_utc | TIMESTAMP | NULLABLE |
| first\_exposure\_pst\_date | DATE | NULLABLE |
| as\_of\_pst\_date | DATE | NULLABLE |
| percent | DOUBLE PRECISION | NULLABLE |
| rollout | BIGINT | NULLABLE |
| user\_dimensions | VARCHAR | NULLABLE |
| inserted\_at | TIMESTAMP | NULLABLE |
| rule\_name | VARCHAR | NULLABLE |
| group\_id | VARCHAR | NULLABLE |
| non\_analytics | BOOLEAN | NULLABLE |
**Events**
| Field name | Type | Mode |
| ----------------- | --------- | -------- |
| user\_id | VARCHAR | NULLABLE |
| stable\_id | VARCHAR | NULLABLE |
| custom\_ids | VARCHAR | NULLABLE |
| timestamp | TIMESTAMP | NULLABLE |
| event\_name | VARCHAR | NULLABLE |
| event\_value | VARCHAR | NULLABLE |
| user\_object | VARCHAR | NULLABLE |
| statsig\_metadata | VARCHAR | NULLABLE |
| company\_metadata | VARCHAR | NULLABLE |
**Setup summary**
Configure:
* API Key
* Server Hostname
* HTTP Path
* Database
* one destination table name per export type
Permissions:
* the configured user or token must be able to create tables and insert/delete rows in the target database
If you prefer to create the export tables yourself, you can use SQL like this:
```sql Databricks Exposures theme={null}
CREATE TABLE IF NOT EXISTS DATABASE_NAME.EXPOSURES_TABLE (
company_id STRING,
unit_id STRING,
unit_type STRING,
exposure_type STRING,
name STRING,
rule STRING,
experiment_group STRING,
first_exposure_utc TIMESTAMP,
first_exposure_pst_date DATE,
as_of_pst_date DATE,
percent DOUBLE,
rollout BIGINT,
user_dimensions STRING,
inserted_at TIMESTAMP,
rule_name STRING,
group_id STRING,
non_analytics BOOLEAN
);
```
```sql Databricks Events theme={null}
CREATE TABLE IF NOT EXISTS DATABASE_NAME.EVENTS_TABLE (
user_id STRING,
stable_id STRING,
custom_ids STRING,
timestamp TIMESTAMP,
event_name STRING,
event_value STRING,
user_object STRING,
statsig_metadata STRING,
company_metadata STRING
);
```
**Exposures**
| Field name | Type | Mode |
| -------------------------- | --------- | -------- |
| company\_id | STRING | NULLABLE |
| unit\_id | STRING | NULLABLE |
| unit\_type | STRING | NULLABLE |
| exposure\_type | STRING | NULLABLE |
| name | STRING | NULLABLE |
| rule | STRING | NULLABLE |
| experiment\_group | STRING | NULLABLE |
| first\_exposure\_utc | TIMESTAMP | NULLABLE |
| first\_exposure\_pst\_date | DATE | NULLABLE |
| as\_of\_pst\_date | DATE | NULLABLE |
| percent | DOUBLE | NULLABLE |
| rollout | BIGINT | NULLABLE |
| user\_dimensions | STRING | NULLABLE |
| inserted\_at | TIMESTAMP | NULLABLE |
| rule\_name | STRING | NULLABLE |
| group\_id | STRING | NULLABLE |
| non\_analytics | BOOLEAN | NULLABLE |
**Events**
| Field name | Type | Mode |
| ----------------- | --------- | -------- |
| user\_id | STRING | NULLABLE |
| stable\_id | STRING | NULLABLE |
| custom\_ids | STRING | NULLABLE |
| timestamp | TIMESTAMP | NULLABLE |
| event\_name | STRING | NULLABLE |
| event\_value | STRING | NULLABLE |
| user\_object | STRING | NULLABLE |
| statsig\_metadata | STRING | NULLABLE |
| company\_metadata | STRING | NULLABLE |
**Setup summary**
Configure:
* Region
* Bucket
* one folder name per export type
Permissions:
* grant the Statsig IAM user bucket-level access to list the bucket and retrieve its location
* grant object-level read, write, and delete permissions, including multipart upload management
S3 exports are file-based. Statsig writes export files to the configured bucket and folder for each export type. In the export UI, the per-export destination is configured as a folder rather than a table.
**Export outputs**
| Export type | Destination shape |
| ----------- | ----------------------------------------------------- |
| Exposures | Files written to the configured folder in your bucket |
| Events | Files written to the configured folder in your bucket |
## Troubleshooting Exports
If you set up an Export flow in Statsig, Statsig can notify you if your data connection is failing. To enable notifications, go to Settings → My Account → Email Notifications → Edit and click Alerts to subscribe to these notifications.
If your Exports are failing, make sure your warehouse is connected with up-to-date credentials and the necessary Read, Write, and Delete permissions.
# Experiment Result Exports
Source: https://docs.statsig.com/integrations/data-exports/experiment_result_exports
Export Statsig experiment results into your data warehouse or BI tool for custom reporting, executive dashboards, and longitudinal experiment analysis.
## Overview
Your data is your data. Statsig makes it easy to export both the reports and the raw data your feature rollouts and experiments generate.
## How to
1. [Download experiment results](/pulse/export#how-to-export-pulse-data) from the Console as a CSV file - including a summary view, exposures and the raw data. This is meant for one-off downloads/analysis.
This solution is still functional, but can be manual and time consuming to set up with minimal error handling. We encourage you to check out the [Data Warehouse Ingestion](/data-warehouse-ingestion/introduction) solution instead.
## Overview
Statsig allows you to upload your pre-computed metrics data to a secure Azure blob owned by Statsig. We'll ingest all of your uploaded metrics for a day once you've signalled that a given day is finished uploading.
## Getting Started
Reach out in slack or to your primary Statsig point of contact. We'll set up an Azure blob storage container and provide you with credentials to connect.
## Filesystem Format
To allow for daily uploads, please set up your blob storage container with the following folders:
* `events/` for events data
* `metrics/` for metrics data
* `signals/` for signal flags when you've finished uploading data for a day. You can omit this folder and instead use the [`mark_data_ready` API](/metrics/ingest) instead, but you must use one or the other
We recommend writing folders by date partitions for ease of debugging, i.e. storing day's data in folders with ISO-formatted names (`YYYY-MM-DD`).
### Data Format
Please make sure your data conforms to the following schemas.
Events
```
| Column | Description | Rules |
| -------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| timestamp | UNIX timestamp of the event | UTC timestamp |
| event_name | The name of the event | String under 128 characters, using `_` for spaces |
| event_value | A string representing the value of a current event. Can represent a 'dimension' or a 'value' | Read as string format; numeric values will be converted into value |
| event_metadata | A dictionary in the form of a JSON string, containing named metadata for the event | String format. Not null. Length < 128 characters |
| user | A JSON object representing the user this event was logged for; see below | Escaped JSON string including the keys 'custom' and 'customIDs'. A userID or customID must be provided. |
| timeuuid | A unique UUID or timeUUID used for deduping. If omitted, will be generated but will not be effective for deduping | UUID format |
```
Please refer to docs for the [Statsig User Object](/concepts/user#user-attributes) for available fields. An example would look like:
```
{
userID: "12345",
customIDs: {
stableID: "",
...
}
email: "12345@gmail.com",
userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.40 Safari/537.36",
ip: "192.168.1.101",
country: "US",
locale: "en_US",
appVersion: "1.0.1",
systemName: "Android",
systemVersion: "15.4",
browserName: "Chrome",
browserVersion: "45.0",
custom: {
new_user: "false",
age: "22"
...
},
}
```
Metrics
Make sure to include all of metric\_value, numerator, and denominator, writing `cast(null as double)` for numerator and denominator if you are omitting them (or conversely for metric\_value if sending numerator/denominator).
| Column | Description | Rules |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| unit\_id | The unique user identifier this metric is for. This might not necessarily be a user\_id - it could be a custom\_id of some kind | String format. Make sure this is in the same format as your logged unit\_ids |
| id\_type | The id\_type the unit\_id represents. | String format. Must be a valid id\_type. The default Statsig types are user\_id/stable\_id, but you may have generated custom id\_types. Make sure this matches (case sensitive) a customID in your project, or you won't get experiment results |
| date | Date of the daily metric | Read as string format; can be written as ISO date. Statsig's dates are calculated in PST - we'll load custom metrics to whatever date you use here |
| metric\_name | The name of the metric | String format. Not null. Length \< 128 characters |
| metric\_value | A numeric value for the metric | Double format. Metric value, or both of numerator/denominator need to be provided for Statsig to process the metric. See details below |
| numerator | Numerator for metric calculation | Double format. Required for ratio metrics. If present along with a denominator in any record, the metric will be treated as ratio and only calculated for users with non-null denominators |
| denominator | Denominator for metric calculation | Double format. See above |
### Scheduling
Because you may be streaming events to your tables or have multiple ETLs pointing to your metrics table, Statsig relies on you signalling that your metric/events for a given day are done.
To do this, write a dataset with the single column `finished_date`, which contains all dates of data which have been written to Statsig. For example, once you have written data for `2022-06-22` you would insert a record with `finished_date` of `2022-06-22` to trigger ingestion of data from up to and including `2022-06-22`.
Unlike some other integrations like Snowflake, for S3 Statsig will skip dates; if your latest finished date is `2022-06-22` and you insert `2022-07-01`, we will ingest all data as of `2022-07-01` and infer that data for dates between (e.g. `2022-06-25`) is loaded.
Alternatively, you can use the `mark_data_ready` API and send a timestamp for which the data previous to that timestamp has finished loading into your container.
Note that, for events, Statsig processes days in PST. When you mark data ready for '2022-06-20', statsig will process events from `2022-06-20T00:00` PST to `2022-06-20T23:59....` PST. Keep this in mind when scheduling your signals!
This solution is still functional, but can be manual and time consuming to set up with minimal error handling. We encourage you to check out the [Data Warehouse Ingestion](/data-warehouse-ingestion/introduction) solution instead.
## Overview
The BigQuery integration allows you to export events and/or metrics from your BigQuery instance to Statsig.
Here are the steps to take to enable BigQuery integration with Statsig:
1. Set up tables in your BigQuery instance.
2. Give Statsig's service account corresponding permissions on the tables.
3. Enable the BigQuery integration in the Statsig console.
4. Insert data into tables and mark data to be ready for import.
## Set Up Tables in your BigQuery instance
1. In your project, create a new dataset where tables for Statsig should live. You can
use an existing dataset, but you will be giving the Statsig server user some permissions on
this dataset later.
2. Create a table for pre-computed metrics, and another for signalling when data
has landed with the statement below:
```
-- Replace statsig with your dataset name, if not using statsig
CREATE TABLE IF NOT EXISTS statsig.statsig_user_metrics(
unit_id STRING NOT NULL,
id_type STRING NOT NULL, -- stable_id, user_id, etc.
date DATE NOT NULL, -- YYYY-MM-DD. Statsig calculates dates according to PST
timeuuid STRING, --Generated unique UUID; we will generate if not provided
metric_name STRING NOT NULL,
metric_value NUMERIC,
numerator NUMERIC,
denominator NUMERIC
);
-- Replace statsig with your dataset name, if not using statsig
CREATE TABLE IF NOT EXISTS statsig.statsig_user_metrics_signal(
finished_date DATE
);
```
## Give permissions to Statsig's service account
1. In your Statsig console, navigate to Project Settings -> Integrations -> BigQuery. Here you will see the Statsig service account. Copy it to be used later.
2. In your BigQuery's [IAM & Admin settings](https://console.cloud.google.com/iam-admin/), add the Statsig service account you copied in step 1 as a new principal for your project, and give it "BigQuery Read Session User" role.
This ingestion pipeline is in beta, and does not currently support automatic
backfills or updates to data once it's been ingested. Only signal these
tables are loaded after you've run data quality checks!
#### Checklist
These are common errors we've run into - please go through and make sure your setup is looking good!
* The `id_type` is set correctly
* Default types are `user_id` or `stable_id`. If you have custom ids, make sure that the capitalization and spelling matches as these are case sensitive (you can find your custom ID types by going to your Project Settings in the Statsig console).
* Your ids match the format of ids logged from SDKs
* In some cases, your data warehouse may transform IDs. This may mean we can't join your experiment or feature gate data to your metrics to calculate pulse or other reports. You can go to the Metrics page of your project and view the log stream to check the format of the ids being sent (either `User ID`, or a custom ID in `User Properties`) to confirm they match
If your data is not showing up in the Statsig console
* Monitoring is limited today, but you should be able to check your snowflake query history for the Statsig user to understand which data is being pulled, and if queries are not executing (no history) or are failing.
* You should see polling queries within a few hours of setting up your integration.
* If you have a signal date in the last 28d, you should see a select statement for data from the earliest signal date in that window
* If that query fails, try running it yourself to understand if there is a schema issue
* If data is loading, it's likely we're just processing. For new metrics, give it a day to catch. If data isn't loaded after a day or two, please check in with us. The most common reason for metrics catalog failures is due to id\_type mismatches.
## Next Steps
Now that everything is set up, your data should start flowing into Statsig's metrics tab and experiment results, and should appear on your console by around noon the next day (PST). This may take longer if you choose an early first date, as we'll need to sequentially load your historical data.
Please shoot us a message on [Slack](https://www.statsig.com/slack) if you have any questions. We can also help making sure everything is set up correctly for you.
# Imports Overview (Deprecated)
Source: https://docs.statsig.com/integrations/data-imports/overview
Overview of data import options for Statsig, including ingestion from data warehouses, object storage, and customer data platforms via connectors.
This solution is still functional, but can be manual and time consuming to set up with minimal error handling. We encourage you to check out the [Data Warehouse Ingestion](/data-warehouse-ingestion/introduction) solution instead.
## Overview
Statsig has a number of ways by which you can send your own events or pre-computed metrics. We support some native integrations to read directly from your data warehouse, or you can choose to write your data to Azure storage owned by Statsig.
## How Metric Imports Work
Some specifics may vary based on your approach, but in general you will write your metrics data at a user-day-metric granularity to a table (or API endpoint) with a special schema. You'll write dates as rows to a special signal table (or API endpoint) when you've finished adding metrics for that day.
Statsig will poll this signal table hourly. Once you've marked your first day of data as ready, or marked the next day of your data as ready, Statsig will pull data from your table and then process it into metrics and experiment results.
Some notes:
* New imported metrics may not show up in your catalog until the following morning
* The earliest signal date we'll consider for your first day of imported metrics is 4 weeks ago
* Statsig doesn't show metrics that haven't had a value for 2 weeks in the Metrics Catalog today. This means that you should start your imports on a recent date for them to show up.
* Statsig currently imports dates ordinally without gaps. This means if you update the signal table for `2022-06-13` and `2022-06-15`, we won't load the data for `2022-06-15` until you mark `2022-06-14` and we finish ingesting that data.
## How Event Imports Work
Event imports behave similarly to Metric imports, with a schematized data source you own and triggers for ingestion.
One key distinction is that Statsig will events pull data continuously to avoid large batch loads timing out.
## Support
Please reach out in slack if you're having any issues with imports or have feature requests.
# Redshift (Deprecated)
Source: https://docs.statsig.com/integrations/data-imports/redshift
Import event and metric data into Statsig from Amazon Redshift on a schedule, including authentication, queries, and column-to-event mappings.
This solution is still functional, but can be manual and time consuming to set up with minimal error handling. We encourage you to check out the [Data Warehouse Ingestion](/data-warehouse-ingestion/introduction) solution instead.
## Overview
There are 2 ways to integrate with Redshift: using a data connector, or ingesting events and metrics to Statsig through S3.
## Using a Data Connector
To **ingest** events from Redshift, you can use our [Census integration](/integrations/data-connectors/census).
To **export** events to Redshift, you can use our [Fivetran integration](/integrations/data-connectors/fivetran).
## Direct Ingestion
S3 imports are currently a custom setup flow. You'll need to reach out to Statsig through Slack or through your support PoC in order to set up this integration.
The documentation below describes the steps to set up this integration. There are 3 main steps:
1. Create a pipeline to write your metric, event, and (optionally) signal data to an S3 bucket in parquet format
2. Create an IAM user with read and list access on that bucket and send that user's Key/Secret to Statsig. We will securely store these in a keystore service
3. Schedule ingestion through a `signals` dataset or through the `mark_data_ready` API
### Set up a data pipeline to S3
#### Filesystem Format
We will expect data in your S3 bucket to be saved in parquet format.
To allow for daily uploads, please set up your bucket with the following folders:
* `events/` for events data
* `metrics/` for metrics data
* `signals/` for signal flags when you've finished uploading data for a day. You can omit this folder and instead use the [`mark_data_ready` API](/metrics/ingest) instead, but you must use one or the other
We recommend writing folders by date partitions for ease of debugging, i.e. storing day's data in folders with ISO-formatted names (`YYYY-MM-DD`).
#### Data Format
Please make sure your data conforms to the following schemas.
Events
```
| Column | Description | Rules |
| -------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| timestamp | UNIX timestamp of the event | UTC timestamp |
| event_name | The name of the event | String under 128 characters, using `_` for spaces |
| event_value | A string representing the value of a current event. Can represent a 'dimension' or a 'value' | Read as string format; numeric values will be converted into value |
| event_metadata | A dictionary in the form of a JSON string, containing named metadata for the event | String format |
| user | A JSON object representing the user this event was logged for; see below | Escaped JSON string including the keys 'custom' and 'customIDs'. A userID or customID must be provided. |
| timeuuid | A unique UUID or timeUUID used for deduping. If omitted, will be generated but will not be effective for deduping | UUID format |
```
Please refer to docs for the [Statsig User Object](/concepts/user#user-attributes) for available fields. An example would look like:
```
{
userID: "12345",
customIDs: {
stableID: "",
...
}
email: "12345@gmail.com",
userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.40 Safari/537.36",
ip: "192.168.1.101",
country: "US",
locale: "en_US",
appVersion: "1.0.1",
systemName: "Android",
systemVersion: "15.4",
browserName: "Chrome",
browserVersion: "45.0",
custom: {
new_user: "false",
age: "22"
...
},
}
```
Metrics
Make sure to include all of metric\_value, numerator, and denominator, writing `cast(null as double)` for numerator and denominator if you are omitting them (or conversely for metric\_value if sending numerator/denominator).
| Column | Description | Rules |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| unit\_id | The unique user identifier this metric is for. This might not necessarily be a user\_id - it could be a custom\_id of some kind | String format. Make sure this is in the same format as your logged unit\_ids |
| id\_type | The id\_type the unit\_id represents. | String format. Must be a valid id\_type. The default Statsig types are user\_id/stable\_id, but you may have generated custom id\_types. Make sure this matches (case sensitive) a customID in your project, or you won't get experiment results |
| date | Date of the daily metric | Read as string format; can be written as ISO date. Statsig's dates are calculated in PST - we'll load custom metrics to whatever date you use here |
| metric\_name | The name of the metric | String format. Not null. Length \< 128 characters |
| metric\_value | A numeric value for the metric | Double format. Metric value, or both of numerator/denominator need to be provided for Statsig to process the metric. See details below |
| numerator | Numerator for metric calculation | Double format. Required for ratio metrics. If present along with a denominator in any record, the metric will be treated as ratio and only calculated for users with non-null denominators |
| denominator | Denominator for metric calculation | Double format. See above |
### Set up and Provide Credentials
* Navigate to your IAM console on AWS
* Go to Users->Add User
* Select the `Access key - Programmatic access` credential type
* Attach an appropriate policy which gives Read and List access to the appropriate bucket. Make sure this is scoped appropriately so the user only has access to the data intended!
Example policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": ""
}
]
}
```
Next, modify your bucket access policy (under `permissions` on your S3 bucket's page) to allows this user to access objects.
Example policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "statement1",
"Effect": "Allow",
"Principal": {
"AWS": ""
},
"Action": "s3:ListBucket",
"Resource": ""
},
{
"Sid": "statement2",
"Effect": "Allow",
"Principal": {
"AWS": ""
},
"Action": "s3:GetObject",
"Resource": "/*"
}
]
}
```
You can confirm your credentials are sufficient by adding any data to your metrics folder and running the following code in PySpark with the IAM user credentials:
```
sc._jsc.hadoopConfiguration().set("fs.s3n.awsAccessKeyId", '')
sc._jsc.hadoopConfiguration().set("fs.s3n.awsSecretAccessKey", '')
spark.read.parquet("s3:///metrics/*",inferSchema=True).show()
```
### Scheduling
Because you may be streaming events to your tables or have multiple ETLs pointing to your metrics table, Statsig relies on you signalling that your metric/events for a given day are done.
To do this, write a dataset with the single column `finished_date`, which contains all dates of data which have been written to Statsig. For example, once you have written data for `2022-06-22` you would insert a record with `finished_date` of `2022-06-22` to trigger ingestion of data from up to and including `2022-06-22`.
Unlike some other integrations like Snowflake, for S3 Statsig will skip dates; if your latest finished date is `2022-06-22` and you insert `2022-07-01`, we will ingest all data as of `2022-07-01` and infer that data for dates between (e.g. `2022-06-25`) is loaded.
Alternatively, you can use the `mark_data_ready` API and send a timestamp for which the data previous to that timestamp has finished loading into S3.
Note that, for events, Statsig processes days according to PST. When you mark data ready for '2022-06-20', statsig will process events from `2022-06-20T00:00` PST to `2022-06-20T23:59....` PST. Keep this in mind when scheduling your signals!
# Snowflake (Deprecated)
Source: https://docs.statsig.com/integrations/data-imports/snowflake
Import event and metric data into Statsig from Snowflake on a schedule, including authentication, queries, and column-to-event mappings.
This solution is still functional, but can be manual and time consuming to set up with minimal error handling. We encourage you to check out the [Data Warehouse Ingestion](/data-warehouse-ingestion/introduction) solution instead.
## Overview
There are 2 ways to integrate with Snowflake: using a data connector, or through direct ingestion from Snowflake.
## Using a Data Connector
To **ingest** events from Snowflake, you can use our [Census integration](/integrations/data-connectors/census).
To **export** events to Snowflake, you can use our [Fivetran integration](/integrations/data-connectors/fivetran).
## Direct ingestion from Snowflake
We also support direct data ingestion from Snowflake, through which Statsig will automatically pull data from Snowflake into your events.
You will need to do the following steps. Please follow the checklist below to avoid delays!
### 1. Set up your Snowflake data warehouse and user for Statsig integration
Insert `USER` and `PASSWORD` values to the below and run it in a Snowflake worksheet
on an account which has sysadmin and securityadmin roles.
This will create the table schemas and setup that Statsig's ingestion will use.
Statsig will use the user you create to access tables in the new Statsig schema. Make sure to use a unique and secure username and password and replace the placeholder values in the first 2 statements.
```sql theme={null}
BEGIN;
-- set up variable values to be used in statements later
-- make sure to configure user_name and user_password with your own values
SET user_name = ''; -- REPLACE WITH YOUR OWN VALUE
SET user_password = ''; -- REPLACE WITH YOUR OWN VALUE
SET role_name = 'STATSIG_ROLE';
-- change role to sysadmin for warehouse / database steps
USE ROLE sysadmin;
-- create a warehouse, database, schema and tables for Statsig
CREATE OR REPLACE WAREHOUSE statsig WITH warehouse_size='XSMALL';
CREATE DATABASE IF NOT EXISTS statsig;
CREATE SCHEMA IF NOT EXISTS statsig.statsig;
-- a table for ingestion of raw events
CREATE TABLE IF NOT EXISTS statsig.statsig.statsig_events(
time BIGINT NOT NULL, -- unix time
timeuuid STRING NOT NULL DEFAULT UUID_STRING(), --generated unique timeuuid
user STRING NOT NULL, --json user object
event_name STRING NOT NULL,
event_value STRING,
event_metadata STRING NOT NULL, --json metadata object
event_version BIGINT,
record_number NUMBER AUTOINCREMENT START 1 INCREMENT 1
);
-- a table for ingestion of metrics/user outcomes
CREATE TABLE IF NOT EXISTS statsig.statsig.statsig_user_metrics(
unit_id STRING NOT NULL,
id_type STRING NOT NULL, -- stable_id, user_id, etc.
date DATE NOT NULL, -- YYYY-MM-DD. Statsig calculates dates according to PST
timeuuid STRING NOT NULL DEFAULT UUID_STRING(),
metric_name STRING NOT NULL,
metric_value NUMBER,
numerator NUMBER,
denominator NUMBER
);
CREATE TABLE IF NOT EXISTS statsig.statsig.statsig_events_signal(
finished_date DATE
);
CREATE TABLE IF NOT EXISTS statsig.statsig.statsig_user_metrics_signal(
finished_date DATE
);
-- change current role to securityadmin to create role and user for Statsig's access
USE ROLE securityadmin;
-- create role for Statsig
CREATE ROLE IF NOT EXISTS identifier($role_name);
GRANT ROLE identifier($role_name) TO ROLE SYSADMIN;
-- create a user for Statsig
CREATE USER IF NOT EXISTS identifier($user_name)
password = $user_password
default_role = $role_name
default_warehouse = statsig;
GRANT ROLE identifier($role_name) TO USER identifier($user_name);
-- grant Statsig role access
GRANT USAGE ON WAREHOUSE statsig TO ROLE identifier($role_name);
GRANT USAGE ON DATABASE statsig TO ROLE identifier($role_name);
GRANT USAGE ON SCHEMA statsig.statsig TO ROLE identifier($role_name);
GRANT SELECT ON statsig.statsig.statsig_events TO ROLE identifier($role_name);
GRANT SELECT ON statsig.statsig.statsig_user_metrics TO ROLE identifier($role_name);
GRANT SELECT ON statsig.statsig.statsig_events_signal TO ROLE identifier($role_name);
GRANT SELECT ON statsig.statsig.statsig_user_metrics_signal TO ROLE identifier($role_name);
COMMIT;
```
Make sure all the statements ran successfully. This will create the schema and user that Statsig's ingestion expects.
### 2. Provide the credentials to Statsig
* Go to [console.statsig.com](https://console.statsig.com/) and log in
* Go to the settings page and navigate to the integrations tab.
* Find Snowflake in the integrations list and provide the requested credentials for the user you just created in step 1.
* You can use the "Test Connection" button to make sure we can establish a connection to the table using the credentials provided.
This ingestion pipeline is in beta, and does not currently support automatic
backfills or updates to data once it's been ingested. Only signal these
tables are loaded after you've run data quality checks!
number of Statsig SDK Events
reported to Datadog. This is meant for monitoring your project's Statsig
usage. This integration also has the option to allow non-production events
to be forwarded to Datadog.
Statsig events are mapped to Datadog metrics with listed tags as follows:
* statsig::gate\_exposure -> statsig.check\_gate.count
* environment
* name
* value
* statsig::config\_exposure -> statsig.get\_config.count
* environment
* statsig::experiment\_exposure -> statsig.get\_experiment.count
* environment
* group
* name
* statsig::layer\_exposure -> statsig.get\_layer.count
* environment
* name
* statsig::holdout\_exposure -> statsig.get\_holdout.count
* environment
* name
* value
#### Example of check\_gate metric
***
## Outgoing
If you are using a service that we don't have an official integration for, you can always use our Generic Webhook integration.
This integration just sends raw events to the provided webhook url.
### Setup
In your Project Settings, under the Integrations tab. Enable the Generic Webhook integration.
In the dialog that appears, enter the url of your destination webhook and then hit Enable to save the url and enable this integration.
, ]}`. Batches may contain 1 or more config change events.
Below are a few examples of some of the config change payloads. To best capture the exhaustive types of config webhooks and their payloads, it's recommended to run a service such as ngrok or some other service that will help you log incoming webhooks.
#### Gate Change
```json theme={null}
{
"user": {
"name": "Test User",
"email": "testuser@email.com"
},
"timestamp": 1709660061095,
"eventName": "statsig::config_change",
"metadata": {
"type": "Gate",
"name": "layout_v2",
"description": "Description: Change default page layout",
"action": "created"
}
}
```
#### Experiment Change
```json theme={null}
{
"user": {
"name": "Test User",
"email": "testuser@email.com"
},
"timestamp": 1709658507446,
"eventName": "statsig::config_change",
"metadata": {
"type": "Experiment",
"name": "heading_test",
"description": "- Updated experiment settings\n - Groups updated: control, test\n - Parameters added: heading\n - Parameters updated: directives",
"action": "updated"
}
}
```
### Filtering Events
Once you've enabled outbound events to your webhook, you can select which categories of Statsig events you want to export by clicking on the **Event Filtering** button and checking the appropriate boxes as shown below.
There are 2 main types of events: *Exposures* (e.g. events logged via the SDK) and *Config Changes* (changelogs for Statsig Console)
The actual event payload may look different than the examples above.
You can also use the **Debug** tool to
1. See requests made to the webhook, including diagnostic information such as number of events forwarded/filtered, request header & body, and more.
2. Send example requests to the webhook using any recently logged event or exposure
#### Configure Integration
First, enable the Fastly integration in the Statsig Console.
Navigate to [Project Settings -> Integrations](https://console.statsig.com/integrations), and then select Fastly
You will need to input the following:
* **Fastly API Key** - Can be found in Fastly portal under **Account** -> **API Tokens**.
* Create an **Automation Token** with:
* **global** and **global:read** scope
* **Store Type** - Select **"Config Store"** or **"KV Store"** depending on your storage type.
* **Config Store ID** OR **KV Store ID**- Your Store ID
There is also an option to filter the configs that are synced into your KV namespace by a Target App. You may wish to enable this in the future as the size of your config payload grows. For now, you can leave this unchecked.
After filling this out, click **Enable**.
Within a minute, the Statsig backend will generate a config payload from your statsig project and push it into your store. Under your Config or KV Store, look for a key starting with the prefix `statsig-`. This is the `key` associated with your Statsig config specs in your Store. Note this key down as it will be required later.
#### Install the Statsig SDK
Install the Statsig serverless SDK:
```bash theme={null}
npm install @statsig/serverless-client
```
#### Import the statsig SDK
Import the Statsig Helper:
```javascript theme={null}
import { handleWithStatsig} from "@statsig/serverless-client/fastly";
```
#### Use the SDK
```javascript theme={null}
handleWithStatsig(handler, params)
```
The helper method takes two arguments:
* `handler` This is your Fastly Compute code.
* `params : StatsigFastlyHandlerParams`
| Parameter | Optional | Type | Description |
| ----------------- | -------- | ---------------- | --------------------------------------------------------------------- |
| `statsigSdkKey` | No | `string` | Your Statsig client API key |
| `fastlyStoreType` | No | `string` | Either `kv` or `config`, signifying your Fastly store type |
| `storeId` | No | `string` | Your KV or Config store id |
| `keyId` | No | `string` | They key storing your Statsig config specs in your Fastly store |
| `apiToken` | No | `string` | Your Fastly API token used to authenticate requests to the Fastly API |
| `statsigOptions` | Yes | `StatsigOptions` | See StatsigOptions [here](/client/javascript-sdk#statsig-options) |
For best practice: store `statsigSdkKey` and `apiToken` in a Fastly [Secret Store](https://www.fastly.com/documentation/guides/compute/edge-data-storage/working-with-secret-stores/)
### Example Usage
```javascript index.js theme={null}
import { handleWithStatsig} from "@statsig/serverless-client/fastly";
async function myHandler(event, client) {
const user = { userID: Math.random().toString().substring(2, 5) };
const res = client.checkGate("pass_gate", user);
client.logEvent("pass_gate", user);
return new Response(
JSON.stringify({ res, user }),
{
status: 200,
headers: { 'Content-Type': 'application/json' }
}
);
}
const handleRequest = handleWithStatsig(myHandler,{
statsigSdkKey: "client-LhxVWHSeZt2uor***********",
fastlyStoreType: "kv",
storeId:"7b12fn*********",
keyId:"statsig-3htllY8XxFsJ*****",
apiToken:"7NaRxS6R**********"
})
addEventListener('fetch', (event) => event.respondWith(handleRequest(event)));
```
**That's it!** The helper automatically:
* Initializes the Statsig Client with config specs from your KV or Config store
* Executes your handler code (Your business logic + Statsig usage)
* Flushes all events after your handler completes execution
* Cleans up resources
### Advanced Usage
**Use the advanced/manual setup if:**
* You need fine-grained control over initialization timing
* You need fine-grained control over event flushing timing
* You need to customize error handling behavior
### Prerequisites
1. Completed the [Statsig Fastly integration setup](#configure-integration)
#### Install the Statsig SDK
Install the Statsig serverless SDK:
```bash theme={null}
npm install @statsig/serverless-client
```
#### Import the statsig SDK
Import the Fastly client:
```javascript theme={null}
import { StatsigFastlyClient} from "@statsig/serverless-client/fastly";
```
#### Creating a `StatsigFastlyClient` instance
```javascript theme={null}
const client = new StatsigFastlyClient("");
```
The client instantiation takes two arguments:
* `sdkKey : string` This is your Statsig client API key. It is available from the [Project Settings](https://console.statsig.com/api_keys) page in the Statsig Console. This is used to authenticate your requests.
* `options : StatsigOptions` See here, for more [options](/client/javascript-sdk#statsig-options).
For best practice: store `sdkKey` in a Fastly [Secret Store](https://www.fastly.com/documentation/guides/compute/edge-data-storage/working-with-secret-stores/)
### Client initialization
The following line initializes the client by loading feature gate and experiment configurations directly from your Fastly KV or Config store.
```javascript theme={null}
const initResult = await client.initializeFromFastly(,
,
,
);
```
The client initialization takes four arguments:
* `fastlyStoreType : string` This is the Fastly store type you are using represented by `kv` or `config`
* `storeId : string` The id of your Fastly store
* `keyId : string` This is they key storing the Statsig config specs in your store
* `apiToken : string` Your Fastly API Token
For best practice: store `apiToken` in a Fastly [Secret Store](https://www.fastly.com/documentation/guides/compute/edge-data-storage/working-with-secret-stores/)
#### Checking a Gate
```javascript theme={null}
const value = client.checkGate("pass_gate", user);
```
This is a gate check in code.
The `checkGate` method takes two arguments:
* `name : string` The name of the Statsig gate that you are checking.
* `user : StatsigUser` The Statsig user object for whom the gate is being checked. For more information on the user object, see [here](/sdks/user#introduction-to-the-statsiguser-object).
Refer to the [Javascript on device evaluation sdk documentation](/client/jsOnDeviceEvaluationSDK) for how to check other entities like experiments and dynamic configs.
#### Logging an event
```javascript theme={null}
client.logEvent('fastly_gate_check', user, value.toString());
```
This is an event log in code.
The `logEvent` method takes two parameters:
* `eventOrName : string | StatsigEvent` This is the name and details of the event you are logging.
* `user : StatsigUser` The Statsig user object for whom the event is being logged.
* `value : string` A value you would like to associate with this event
For more information on event logging, see [here](/client/jsOnDeviceEvaluationSDK#logging-an-event).
#### Flushing Events
```javascript theme={null}
event.waitUntil(client.flush());
```
This flushes all events from the sdk to Statsig. **Without this, you won't be able to get diagnostic information in the Statsig Console, nor any event data you logged**.
#### Putting it all together
```javascript theme={null}
import { StatsigFastlyClient } from "@statsig/serverless-client/fastly";
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
async function handleRequest(event) {
const client = new StatsigFastlyClient("client-LhxVWHSeZt2uor********");
const initResult = await client.initialzeFromFastly(
"kv",
"7b12fnfm7po7*********",
"statsig-3htllY8X**********",
"7NaRxS6RMGE-DTp*******"
);
const user = { userID: Math.random().toString().substring(2, 5) };
const value = client.checkGate("pass_gate", user);
client.logEvent("fastly_gate_check", user, value.toString());
event.waitUntil(client.flush());
return new Response(JSON.stringify({ kv, user }), {
status: 200,
headers: { "Content-Type": "application/json" },
});
}
```
## Other Considerations
### Polling for updates v5.13.0+
The SDK cannot poll for updates across requests since Fastly does not allow for timers.To optimize for edge use cases, we do not provide an api to recognize updates to your config specs. However, when a change is made to your project definition on the Statsig console, the changes will be propagates to the KV/Config store and will be reflected the next time you initialize the StatsigFastly client.
### Flushing events v4.16.0+
The SDK enqueues logged events and flushes them in batches. In order to ensure events are properly flushed, we recommend calling flush using `event.waitUntil()`. This will keep the request handler alive until events are flushed without blocking the response.
```
event.waitUntil(statsig.flush());
```
If you want to check on the evaluations you are getting, you can go to the gate you created for this example and look at the evaluations in the Diagnostics tab. If you want to check the events you logged, in the **Statsig Console**, go to **Data** -> **Events**
And there you have it - a working Fastly integration for Statsig.
### Size Limits
Fastly Config Store has maximum size limits that may prevent Statsig from pushing configs into Fastly. See [here](https://docs.fastly.com/products/edge-data-storage) for the latest Config Store limits. If your payload continues to grow, you will need to set the option to filter the payload by a Target App in the integration settings.
### Unsupported Features
Statsig ID Lists are not currently synced into Fastly KVs or Config Stores. If you rely on large (>1000) ID lists, you will not be able to check them in your Fastly compute services.
# Github AI Integration
Source: https://docs.statsig.com/integrations/github-ai-integration
Integrate Statsig with GitHub AI tools to keep feature gates and experiments visible to AI code reviewers and automate flag cleanup PRs.
## Overview
This feature is in open beta and might have rough edges currently. If you have feedback, please share with us!
The Statsig GitHub integration links your organization's code repository directly to your Statsig project. This allows Statsig to analyze your code base and create a private Knowledge Graph that maps relationships between your codebase and Statsig services such as Feature Gates, Experiments, and Metrics.
This integration connects your software development with measurable business impact, delivering contextual insights within Statsig.
You can choose to install the app on specific repositories or your entire organization. For the best results with Knowledge Graph, we recommend selecting all relevant repositories containing feature code.
### Connecting Additional Projects
GitHub allows a specific GitHub App to be installed only *once* per GitHub Organization. If you have multiple Statsig Projects (e.g., "Project 1" and "Project 2") that need access to the same GitHub Org, they will share the underlying connection.
To link a new project to an existing GitHub connection:
1. Navigate to **Settings** → **Integrations** in the Statsig console
2. Locate and select the **Statsig GitHub App** card. We will indicate if an existing connection exists for any other project.
3. Select the Statsig Project you wish to inherit the connection from
4. Confirm the link
### Migrating from Legacy (PAT) Integration
If you are using the older Personal Access Token (PAT) integration, we recommend upgrading to the GitHub App for improved security and functionality.
1. Navigate to **Settings** → **Integrations** in the Statsig console
2. Locate and select the **Statsig GitHub App** card
3. You will see a banner or indicator on the GitHub integration card prompting you to upgrade from PAT based connection
4. Follow the flow to install the GitHub App on your repositories
5. Once the App is installed, the system will automatically deprecate the old PAT connection
## Statsig GitHub Integration FAQs
1. **Will my data be used to train LLM models?**\
Statsig does not use your data to train LLM models nor does its sub-processors. Your data is secured to your organization and used to improve the services provided to you.
2. **Does Statsig store my source code?**\
Statsig does not permanently store your source code. Code is temporarily processed to extract metadata and embeddings in order to create the Knowledge Graph, and discarded when no longer necessary.
3. **How long does it take for the code insights to appear in Statsig?**\
Setting up the integration can take up to a few hours depending on the size of the repository. After the initial setup, we will index new data every 7 days.
4. **What security controls apply?**\
Information on Statsig's security practices is available [here](https://www.statsig.com/trust/security). Information on Statsig's AI governance is available [here](/compliance/ai_governance_security_privacy).
# Github Code References
Source: https://docs.statsig.com/integrations/github_code_references
Connect Statsig with GitHub to surface code references for feature gates and dynamic configs, so you can see exactly where each flag is used.
### Deprecated: PAT-based Integration
We have deprecated the Personal Access Token (PAT) based integration in favor of our new GitHub App-based integration. The new integration provides improved security and functionality, including AI-powered features like Knowledge Graph. Please migrate to the [GitHub AI Integration](/integrations/github-ai-integration) for the best experience.
## Overview
The Statsig Github Integration allows you to find [Feature Gate](/feature-flags/overview) and [Dynamic Config](/dynamic-config) references within your codebase on the Statsig Console. The integration leverages the Github API to access only references to the Feature Gate or Dynamic Config without storing any sensitive information.
## Configuration
Create a new Github developer token, either Classic or Fine Grained, with at least read access to the organization or repositories that you use Statsig.
This can be found in Github under **Settings** > **Developer Settings** > **Personal Access Token**.
Then, login to the Statsig Console and navigate to the Github Code References integration on the Integrations page.
This can be found in **Project Settings** > **Integrations Tab** > **Github Code References**.
The Integration should provide additional instructions on how to enable Github Code References.
', {/* USER */}, {/* OPTIONS */});
statsig.on('values_updated', function(evt) { // bind before init is called
if(evt.status && evt.status === 'Ready') {
window.dispatchEvent(new CustomEvent("statsig:ready", {
detail: { statsig: statsig }
}));
}
});
await statsig.initializeAsync();
```
#### Using statsig-js
```js theme={null}
await statsig.initialize('', '', {
initCompletionCallback: function (duration, success, message) {
window.dispatchEvent(new CustomEvent("statsig:ready", {
detail: { statsig: statsig }
}));
}
});
```
### Step 2: Create new tag
The code below assumes that the statsig client lives at `window.statsig`
```html theme={null}
```
## Outbound Integration (GTM Data is enriched with Statsig test assignments)
This pattern will allow you to enrich your GTM `dataLayer` with experiment assignment information.
ChatGPT App OAuth only supports Personal Console API Keys. Ensure your
Statsig org owner has enabled Personal Console API Keys creation for your
role [here](https://console.statsig.com/settings?tab=organization)
MCP OAuth only supports Personal Console API Keys. Ensure your Statsig org
owner has enabled Personal Console API Keys creation for your role
[here](https://console.statsig.com/settings?tab=organization)
On Claude Code, we recommend using OAuth and the HTTP transport directly. Run this command on the command line:
```bash theme={null}
claude mcp add --transport http statsig https://api.statsig.com/v1/mcp
```
This command will:
* Add the Statsig MCP server to your Claude Code configuration
* Configure it to use HTTP transport with OAuth authentication
* Set up the connection to Statsig's MCP endpoint
To authenticate via OAuth, run `/mcp` in Claude Code and follow the setup instructions:
1. Claude Code will open a browser window
2. Sign in to your Statsig account
3. Authorize the MCP server to access your Statsig project
4. The authentication will be saved for future sessions
While we recommend setting up Statsig MCP via OAuth, you can also authenticate with your Console API key. Run this command on the command line:
```bash theme={null}
claude mcp add --transport http statsig-local https://api.statsig.com/v1/mcp \
--header "statsig-api-key: console-YOUR-CONSOLE-API-KEY"
```
Replace `console-YOUR-CONSOLE-API-KEY` with your actual Statsig Console API key, which you can retrieve [here](https://console.statsig.com/api_keys). Ensure your API key has the right permissions — read-only keys can view data, while write keys can make changes to your project!
## Verification
After installation, you can verify the connection by:
1. Opening Claude Code
2. Asking Claude to list your Statsig experiments or gates
3. If configured correctly, Claude will be able to access your Statsig data
## Using Statsig MCP with Claude Code
Once configured, you can interact with your Statsig data through Claude Code:
* **Query Experiments**: "What experiments are currently running?"
* **Manage Gates**: "List all my feature flags"
* **Get Details**: "Show me the configuration for gate 'new-feature'"
* **Create Entities**: "Create a new experiment called 'checkout-test'"
## Troubleshooting
If you encounter issues:
* Make sure you have the latest version of Claude Code
* Verify your Statsig account has the necessary API permissions
* Check that the MCP server URL is correct: `https://api.statsig.com/v1/mcp`
* Try re-running the installation command
## Next Steps
* Learn about [MCP capabilities](/integrations/mcp#current-mcp-capabilities)
* Explore [use cases](/integrations/mcp#use-cases) for Statsig MCP
* Set up Statsig MCP in other tools: [Cursor](/integrations/mcp/cursor), [Codex CLI](/integrations/mcp/codex)
# Statsig MCP with Codex
Source: https://docs.statsig.com/integrations/mcp/codex
Configure the Statsig MCP server in Codex CLI, the Codex IDE extension, and the Desktop App so you can query Statsig data and manage features from Codex.
## Overview
You can set up the Statsig MCP server using an API key on Codex CLI, IDE Extension, and App today.
## Installation and Authentication via OAuth
MCP OAuth only supports Personal Console API Keys. Ensure your Statsig org
owner has enabled Personal Console API Keys creation for your role
[here](https://console.statsig.com/settings?tab=organization)
On Codex, we recommend using OAuth and the HTTP transport directly. Authentication will be saved for future sessions.
In Codex Desktop, navigate to Settings > MCP servers and add a new custom server. Set up via Streamable HTTP, with URL set to `https://api.statsig.com/v1/mcp`:
If you are working in Codex CLI or IDE extension, run the below command to add the Statsig MCP server into your `~/.codex/config.toml` file and restart Codex.
```bash theme={null}
codex mcp add statsig --url https://api.statsig.com/v1/mcp
```
This command should open a browser window for you to sign in to your Statsig account and authorize access to your Statsig project.
Once you've signed in, restart Codex and run `/mcp` in CLI to validate the Statsig MCP is listed as an available MCP server. Make sure status is set to enabled:
```toml theme={null}
[mcp_servers.statsig]
url = "https://api.statsig.com/v1/mcp"
command = "npx"
args = ["--yes", "mcp-remote", "https://api.statsig.com/v1/mcp", "--header", "statsig-api-key: console-YOUR-CONSOLE-API-KEY"]
trust_level = "trusted"
enabled = true
```
Replace `console-YOUR-CONSOLE-API-KEY` with your actual Statsig Console API key, which you can retrieve [here](https://console.statsig.com/api_keys). Ensure your API key has the right permissions — read-only keys can view data, while write keys can make changes to your project!
## Using Statsig MCP with Codex
With Statsig MCP configured in any Codex environment, you can:
* **Explore Experiments**: "List all my active experiments"
* **Manage Gates**: "What gates are currently stale?"
* **Configure Dynamic Configs**: "Show me the configuration for the dynamic config 'dynamic-config'"
* **Get Insights**: "Show me details about the experiment called 'new-checkout-flow'"
## Next Steps
After installation, you can:
* List experiments, gates, and dynamic configs
* Create and update experiments, gates, and configs
* Access your Statsig data directly from Codex
For more information about available MCP capabilities, see the [MCP capabilities](/integrations/mcp#current-mcp-capabilities) section.
# Statsig MCP with Cursor
Source: https://docs.statsig.com/integrations/mcp/cursor
Set up the Statsig MCP server in Cursor IDE so the agent can read experiments, feature gates, and metric data while writing and reviewing code.
## Installation and Authentication via OAuth
MCP OAuth only supports Personal Console API Keys. Ensure your Statsig org
owner has enabled Personal Console API Keys creation for your role
[here](https://console.statsig.com/settings?tab=organization)
You can add the Statsig MCP with OAuth to Cursor in two ways:
### Option 1: Quick Install (Recommended)
[Click here](cursor://anysphere.cursor-deeplink/mcp/install?name=statsig\&config=eyJ1cmwiOiJodHRwczovL2FwaS5zdGF0c2lnLmNvbS92MS9tY3AifQ%3D%3D) to automatically add the Statsig MCP to Cursor.
### Option 2: Manual Configuration
1. Open Cursor settings
2. Navigate to **Settings → Cursor Settings → Tools & Integrations**
3. Find the MCP servers section
4. Add the following configuration to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"statsig": {
"url": "https://api.statsig.com/v1/mcp"
}
}
}
```
Cursor will automatically handle OAuth authentication when you first use the Statsig MCP. You'll be prompted to:
1. Sign in to your Statsig account
2. Authorize the MCP server to access your Statsig project
3. Restart Cursor to apply the changes
4. Verify the connection by navigating to **Settings → Cursor Settings → Tools & Integrations**, where Statsig MCP server should be listed and active
The authentication will be saved for future sessions.
While we recommend setting up Statsig MCP via OAuth, you can also authenticate with your Console API key. [Click here](cursor://anysphere.cursor-deeplink/mcp/install?name=statsig\&config=eyJjb21tYW5kIjoibnB4IG1jcC1yZW1vdGUgaHR0cHM6Ly9hcGkuc3RhdHNpZy5jb20vdjEvbWNwIC0taGVhZGVyIHN0YXRzaWctYXBpLWtleToke0FVVEhfVE9LRU59IiwiZW52Ijp7IkFVVEhfVE9LRU4iOiJpbnNlcnQteW91ci1hcGkta2V5LWhlcmUifX0%3D) to quick install, or manually configure:
1. Open Cursor settings
2. Navigate to **Settings → Cursor Settings → Tools & Integrations**
3. Find the MCP servers sections
4. Add the below configuration to `~/.cursor/mcp.json`
```json theme={null}
{
"mcpServers": {
"statsig": {
"command": "npx mcp-remote https://api.statsig.com/v1/mcp --header statsig-api-key:${AUTH_TOKEN}",
"env": {
"AUTH_TOKEN": "console-YOUR-CONSOLE-API-KEY"
}
}
}
}
```
Replace `console-YOUR-CONSOLE-API-KEY` with your actual Statsig Console API key, which you can retrieve [here](https://console.statsig.com/api_keys). Ensure your API key has the right permissions — read-only keys can view data, while write keys can make changes to your project!
## Using Statsig MCP with Cursor
Once configured, you can use Statsig MCP commands in Cursor's chat interface:
* **Query Experiments**: "What experiments are currently running?"
* **Manage Gates**: "List all my feature flags"
* **Get Details**: "Show me the configuration for gate 'new-feature'"
* **Create Entities**: "Create a new experiment called 'checkout-test'"
## Troubleshooting
If the MCP server doesn't appear:
* Make sure you've restarted Cursor after adding the configuration
* Check that the `mcp.json` file is in the correct location: `~/.cursor/mcp.json`
* Verify your Statsig account has the necessary permissions
## Next Steps
* Learn about [MCP capabilities](/integrations/mcp#current-mcp-capabilities)
* Explore [use cases](/integrations/mcp#use-cases) for Statsig MCP
* See examples of [stale gate cleanup](/integrations/mcp#example-prompt-for-stale-gate-cleanup)
# Statsig MCP with Other MCP-Compatible Clients
Source: https://docs.statsig.com/integrations/mcp/manual-setup
Manually configure the Statsig MCP server for any MCP-compatible tool, including authentication, scopes, transport options, and recommended client settings.
## Overview
If your tool doesn't have a specific setup guide, you can manually configure the Statsig MCP server. This guide covers the general configuration steps that work with any MCP-compatible client.
## Prerequisites
* A Statsig account (sign up at [console.statsig.com](https://console.statsig.com))
* An MCP-compatible tool or client
* Access to your tool's configuration files
## Configuration
Add the following configuration to your MCP client's configuration file:
```json theme={null}
{
"mcpServers": {
"statsig": {
"url": "https://api.statsig.com/v1/mcp"
}
}
}
```
This installs the Statsig MCP Server with OAuth. When you first use the MCP server:
1. Your tool will prompt you to authenticate
2. You'll be redirected to Statsig's OAuth page
3. Sign in and authorize the MCP server
4. The authentication token will be stored automatically
MCP OAuth only supports Personal Console API Keys. Ensure your Statsig org
owner has enabled Personal Console API Keys creation for your role
[here](https://console.statsig.com/settings?tab=organization)
While we recommend setting up Statsig MCP via OAuth, you can also authenticate with your Console API key. Add the below configuration to your MCP client's configuration file:
```json theme={null}
{
"mcpServers": {
"statsig": {
"command": "npx mcp-remote https://api.statsig.com/v1/mcp --header statsig-api-key:${AUTH_TOKEN}",
"env": {
"AUTH_TOKEN": "console-YOUR-CONSOLE-API-KEY"
}
}
}
}
```
Replace `console-YOUR-CONSOLE-API-KEY` with your actual Statsig Console API key, which you can retrieve [here](https://console.statsig.com/api_keys). Ensure your API key has the right permissions — read-only keys can view data, while write keys can make changes to your project!
## Verification
After adding the configuration:
1. Restart your tool to apply the changes
2. Check your tool's MCP server list to verify Statsig appears
3. Try using a Statsig MCP command to test the connection
## Testing the Connection
You can test the connection by asking your tool to:
* **List experiments**: "Get list of experiments"
* **List gates**: "Get list of gates"
* **Get details**: "Get details for experiment \[experiment-id]"
## Next Steps
* Learn about [MCP capabilities](/integrations/mcp#current-mcp-capabilities)
* Explore [use cases](/integrations/mcp#use-cases) for Statsig MCP
* Check tool-specific guides: [Cursor](/integrations/mcp/cursor), [Claude Code](/integrations/mcp/claude-code), [Codex CLI](/integrations/mcp/codex)
# Overview
Source: https://docs.statsig.com/integrations/mcp/overview
Connect the Statsig MCP server to Codex, Cursor, and Claude Code so AI assistants can explore experiments, feature gates, and metrics in your project.
## MCP configuration guides
Set up Statsig MCP using Codex Desktop App, CLI, or IDE extension.
Talk to your Statsig projects from within ChatGPT.
Configure Statsig MCP in Cursor IDE.
Set up Statsig MCP in Claude Code.
Manual configuration for any MCP-compatible tool.
## Current MCP capabilities
Tool
Description
Get\_Audit\_Logs
List audit logs in the project. Filter by:
idsortKeysortOrdertagsstartDateendDate
Tool
Description
Create\_Dynamic\_Config
Create new config
Get\_Dynamic\_Config\_Details\_by\_ID
Retrieve detailed config information
Get\_List\_of\_Dynamic\_Configs
List all dynamic config objects in the project. Filter by:
Update\_Dynamic\_Config\_Entirely
Replace entire dynamic config with new targeting and values
Tool
Description
Create\_Experiment
Create new experiment
Get\_Experiment\_Details\_by\_ID
Get experiment details
Get\_Experiment\_Overall\_Results
Retrieve experiment results/pulse data for a specific experiment.
Analyze by:
date
cuped: whether or not to apply CUPED
confidence: Confidence threshold used for result
calculations
Get\_Experiment\_Metric\_
Retrieve metric results for one experiment metric with dimensional
breakdowns. Analyze by:
date
cuped: whether or not to apply CUPED
confidence: Confidence threshold used for result
calculations
Get\_List\_of\_Experiments
List all experiments in the project. Filter by:
status: Supported values include
active, setup,decision\_made
, abandoned,archived,
experiment\_stopped,assignment\_stopped
creatorName
tags
stale
Update\_Experiment\_Entirely
Replace entire experiment configuration (any excluded data will be
removed)
Tool
Description
Create\_Gate
Create new gate/flag
Get\_Gate\_Details\_by\_ID
Get complete gate configuration details
Get\_Gate\_Results
Retrieve pulse/results for a specific gate rule.
cuped: Whether or not to apply CUPED. Defaults trueconfidence: CI percentage, defaults 95
Get\_List\_of\_Gates
List all gates/flags. Filter by:
type (e.g., temporary, permanent, stale, tempmlate)creatorNametags
Update\_Gate\_Entirely
Replace entire gate setup with new rules and settings (any excluded data will be removed)
Tool
Description
Create\_Layer
Create a new layer
Get\_Layer\_Details\_by\_ID
Retrieve layer details, including parameters and metadata
Get\_List\_of\_Layers
List all layers in the project
Update\_Layer\_Entirely
Replace the full layer configuration
Tool
Description
Get\_List\_of\_Metric\_Sources
List all metric sources in the project
Get\_List\_of\_Metrics
List all metrics in the project. Filter by:
showHiddenMetricstagsfilters (supports `any of` and `all of`)
Get\_Metric\_Definition\_by\_ID
Get the full definition for a metric, including its type, source, and configuration details
Tool
Description
Create\_Segment
Create a new segment. Supports id\_list,
rule\_based, analysis\_list, and
user\_store\_id\_list segment types
Get\_List\_of\_Segments
List all segments in the project
Get\_Segment\_Details\_by\_ID
Retrieve segment details
Update\_Segment
Update an existing segment. Specifically:
Update rules for conditional segment types
Add IDs to user stores and ID lists
Need other functions? We're happy to consider additions by request, reach out in Slack.
## Use Cases
The Statsig MCP server now supports both `GET` and `POST` requests. This means tools can not only read data (like stale gates) but also make updates, if your API key has write permissions. We've found the Statsig MCP server especially useful for:
* Repetitive tasks like cleaning up stale gates
* Summarizing console information in your IDE workflows
* Bulk creating or deleting gates, and making the necessary changes in your code
### Example prompt for stale gate cleanup
```
You are an expert, diligent Software engineer with the sole goal of reducing the amount of tech debt in the code base. This code base, making use of best practices, leverages feature gates liberally using Statsig. As gates complete their lifecycle in Statsig, they may end up "stale" which means that they're enabled, but no longer checked. Your job is to find these gates, and refactor the codebase to no longer check the gate (instead, changing the check to a constant value).
You should follow coding best practices:
- You should not simply replace gate calls with "True" or "False" but instead carefully trace the logic through to where it is used and change the behavior that way - adjusting the code in minor ways to make the default behavior what the value is that the gate was returning
- You should always strive to write minimal code - readable but terse, never longer than it needs to be
- You should never write comments or debug statements.
You should use the statsig-local MCP to list feature gates, then look for gates that are marked as stale. You should then grep the codebase for that feature flag name, and do a minimal rewrite of the code to no longer use Statsig, removing the checkGate call or similar. When you use the MCP use the get /console/v1/gates endpoint and parameters type="STALE" and limit =10. You should select only one gate to do this with, before stopping. If you cannot find the gate after a grep, try the next one you found using the MCP. Once you successfully remove a gate, return.
```
# OpenAI
Source: https://docs.statsig.com/integrations/openai
Integrate Statsig with OpenAI to log AI requests, capture metrics, and run experiments on prompts, models, and parameters across your applications.
## Context
When using a pre-trained large language model, several inputs influence user experience, including the prompts used, the "inference parameters" given to the model, often including parameters like temperature, length penalties and repetition penalties, and even the exact model selected. Tools like Statsig can streamline the process of assigning users to various experiments, such as modifying these inputs, and can automatically identify when changes have a statistically significant impact on user experience metrics. This enables efficient iteration and optimization of user experience by tweaking model choices, prompts, and inference parameters. In this case we show how you can log both implicit indicators of user feedback (like response time) and more explicit ones, like self-reported satisfaction.
## Introduction
The included Python code offers an example of the simple but powerful interaction between OpenAI's GPT and Statsig to experiment with model inputs and log user events. This example uses OpenAI's ChatCompletion feature to answer questions, plus a Statsig integration to experiment with model versions and log user feedback to the changes.
This example assumes you have a funded OpenAI account, plus a Statsig experiment that varies the model selected between "gpt-3.5-turbo" and "gpt-4". For more info on setting up a Statsig experiment, see the [experiments](/experiments-plus) page.
## Code Breakdown
### Initial Configuration
Of course, you'll need to install both the Statsig and OpenAI Python packages before starting:
```bash theme={null}
pip3 install openai, statsig
```
After that, we can begin coding in a python file:
```python theme={null}
import openai
from statsig import statsig, StatsigEvent, StatsigUser
import time
openai.api_key = "your_openai_key" # Replace with your own key
statsig.initialize("your_statsig_secret") # Replace with your Statsig secret
user = StatsigUser("user-id") #This is a placeholder ID - in a normal experiment Statsig recommends using a user's actual unique ID for consistency in targeting. See https://docs.statsig.com/concepts/user
```
### The ask\_question Function
The following code all occurs in one function titled ask\_question (see the [final code](#final-code))
1. Get User Input
```python theme={null}
#ask the user for a question to query GPT with
question = input("\nWhat is your question? ")
```
First, we prompt the user with the question they'd like to ask ChatGPT
2. Query OpenAI's GPT
```python theme={null}
#track the start time so we can check response time later
start_time = time.time()
completion = openai.ChatCompletion.create(
model=statsig.get_experiment(user, "statsig_openai_integration").get("model", 'gpt-4'),
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": question}
]
)
```
Next, we request a completion that queries the GPT model specified by the Statsig experiment (either gpt-3.5-turbo or gpt-4). We also start a timer so we can track the response time in our events later on.
3. Display Response & Log Implicit Feedback
```python theme={null}
#log "implicit" indicators to Statsig
c = completion.choices[0]
stats = completion.usage #completion object has the number of tokens used - which is that what GPT usage is charged on.
statsig.log_event(StatsigEvent(user, "chat_completion", value=c.finish_reason, metadata={"response_time": time.time() - start_time, "completion_tokens": stats["completion_tokens"], "prompt_tokens": stats["prompt_tokens"], "total_tokens": stats["total_tokens"]}))
#print the message back to the user
print(f"\nAnswer: {c.message['content']}")
```
With the response from OpenAI we have our first set of useful information to log to Statsig - like the response time and tokens used. We log this information with Statsig's SDK, storing them in the metadata of the request.
4. Collect User Feedback & Log to Statsig
```python theme={null}
#track explicit feedback: if the user is satisfied with the answer
satisfaction = input("\nDid this answer your question? (y/n): ")
# Log "explicit" indicators to Statsig
if satisfaction == 'y':
statsig.log_event(StatsigEvent(user, "satisfaction"))
elif satisfaction == 'n':
statsig.log_event(StatsigEvent(user, "dissatisfaction"))
```
Next, we log a more explicit indicator of feedback, the user's self-reported satisfaction or dissatisfaction. The satisfaction metric can provide a strong indicator of the model's overall power.
And we're done - we can run this Python program with the following code, now outside of our ask\_question function.
```python theme={null}
if __name__ == "__main__":
while input("Would you like to ask a question? (y/n): ").lower() == 'y':
ask_question()
```
### Tips for Using Statsig with AI
1. Experimentation: You can also test other model parameters like temperature, top\_p, or initial prompts.
2. Log Useful Data: Consider logging other interesting user interactions or feedback.
3. Analyze and Iterate: After collecting enough data, analyze the results on the Statsig dashboard.
4. User Identification: Consider integrating a mechanism to uniquely identify each user/session.
Always ensure you're in compliance with user privacy regulations and that you have user consent where necessary.
### Useful Links
* [OpenAI Documentation](https://platform.openai.com/docs/api-reference/chat/create)
## Final code
```python theme={null}
import openai
from statsig import statsig, StatsigEvent, StatsigUser
import time
openai.api_key = "your_openai_key"
statsig.initialize("your_statsig_secret")
user = StatsigUser("user-id") #This is a placeholder ID - in a normal experiment Statsig recommends using a user's actual unique ID for consistency in targeting. See https://docs.statsig.com/concepts/user
def ask_question():
#ask the user for a question to query GPT with
question = input("\nWhat is your question? ")
#track the start time so we can check response time later
start_time = time.time()
#query GPT with the OpenAI Python library for chat completions
completion = openai.ChatCompletion.create(
model=statsig.get_experiment(user, "statsig_openai_collab").get("model", 'gpt-4'), #experiment is setup to return either "gpt-3.5-turbo" or "gpt-4".
#other than varying the model selected, other attributes could be varied like "temperature", "top_p", "presence_penalty" and more.
#See the "Create chat completions" section of the OpenAI documentation for more: https://platform.openai.com/docs/api-reference/chat/create
messages=[
{"role": "system", "content": "You are a helpful assistant."}, #Initial prompts are another candidate for experimentation
{"role": "user", "content": question}
]
)
#log "implicit" indicators to Statsig
c = completion.choices[0] #we've only requested one choice, so selecting the first
stats = completion.usage #completion object has the number of tokens used - which is that what GPT usage is charged on.
statsig.log_event(StatsigEvent(user, "chat_completion", value=c.finish_reason, metadata={"response_time": time.time() - start_time, "completion_tokens": stats["completion_tokens"], "prompt_tokens": stats["prompt_tokens"], "total_tokens": stats["total_tokens"]}))
#print the message back to the user
print(f"\nAnswer: {c.message['content']}")
#track explicit feedback: if the user is satisfied with the answer
satisfaction = input("\nDid this answer your question? (y/n): ")
#log "explicit" indicators to Statsig
if satisfaction == 'y':
statsig.log_event(StatsigEvent(user, "satisfaction"))
elif satisfaction == 'n':
statsig.log_event(StatsigEvent(user, "dissatisfaction"))
if __name__ == "__main__":
#Let the user abandon the question-asking process when they are done
while input("Would you like to ask a question? (y/n): ").lower() == 'y':
ask_question()
```
# Pulumi
Source: https://docs.statsig.com/integrations/pulumi
Manage Statsig feature gates, experiments, and dynamic configs as code with Pulumi, including provider setup and resource definition examples.
The [Statsig Pulumi Provider](https://www.pulumi.com/registry/packages/statsig/) allows you to configure your gates and experiments using Pulumi Infrastructure as Code. The provider synchronizes with Statsig via the Console API. If there is something you need to perform that isn't supported by the Pulumi Provider, checkout the [Console API](/console-api/introduction).
## Installation
The Statsig provider is available as a package in the following Pulumi languages:
* **JavaScript/TypeScript**: [`@statsig/pulumi-statsig`](https://www.npmjs.com/package/@statsig/pulumi-statsig)
* **Python**: [`pulumi-statsig`](https://pypi.org/project/pulumi-statsig/)
* **Go**: [`github.com/statsig-io/pulumi-statsig/sdk/go/statsig`](https://github.com/statsig-io/pulumi-statsig)
* **.NET**: [`Statsig.Pulumi`](https://www.nuget.org/packages/Statsig.Pulumi)
## Configuration
The provider needs to be configured with the proper credentials before it can be used. Configure your `Pulumi.yaml` file with your Console API key:
```yaml theme={null}
# Pulumi.yaml provider configuration file
name: configuration-example
runtime: nodejs # or python, go, dotnet
config:
statsig:consoleApiKey:
value: 'YOUR_CONSOLE_API_KEY'
```
### Configuration Reference
* `consoleApiKey` (String) - The Statsig Console API key retrieved from Statsig console.
## Example Usage
### TypeScript
```typescript theme={null}
import * as pulumi from "@pulumi/pulumi";
import * as statsig from "@statsig/pulumi-statsig";
// Create a Feature Gate
const gate = new statsig.Gate("my-gate", {});
```
### Python
```python theme={null}
import pulumi
import pulumi_statsig as statsig
# Create a Feature Gate
gate = statsig.Gate("my-gate")
```
### Go
```go theme={null}
package main
import (
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
"github.com/statsig-io/pulumi-statsig/sdk/go/statsig"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
// Create a Feature Gate
_, err := statsig.NewGate(ctx, "my-gate", nil)
if err != nil {
return err
}
return nil
})
}
```
### C\#
```csharp theme={null}
using Pulumi;
using Statsig = Statsig.Pulumi;
return await Deployment.RunAsync(() =>
{
// Create a Feature Gate
var gate = new Statsig.Gate("my-gate");
});
```
## Supported Features
We currently support the following Statsig configurations:
* Gates
* Experiments
Coming Soon:
* Dynamic Configs
* Segments
If you need more from our Pulumi Provider, please feel free to ask in the [Statsig Slack channel](https://statsig.com/slack).
# Serverless
Source: https://docs.statsig.com/integrations/serverless
Use Statsig integrations with serverless platforms like AWS Lambda, Vercel, and Cloudflare Workers to evaluate flags and log events at the edge.
The serverless SDK is a lightweight JavaScript SDK optimized for serverless environments while being compatible for any other platform/environment. This SDK harnesses the functionalities that all Statsig server SDK's offer.
```bash theme={null}
npm install @statsig/serverless-client
```
```bash theme={null}
import {StatsigServerlessClient} from '@statsig/serverless-client'
```
```javascript theme={null}
const client = new StatsigServerlessClient(process.env.STATSIG_KEY)
```
The client instantiation takes two arguments:
* `sdkKey : string` This is your Statsig client API key. It is available from the [Project Settings](https://console.statsig.com/api_keys) page in the Statsig Console. This is used to authenticate your requests.
* `options : StatsigOptions` See [here for more options](/client/javascript-sdk#statsig-options).
The following line initializes the client by loading feature gate and experiment configurations over network
```javascript theme={null}
const init = await client.initializeAsync();
```
```javascript theme={null}
const GateResult = client.checkGate('pass_gate', user);
```
This is a gate check in code.
The `checkGate` method takes two arguments:
* `name : string` The name of the Statsig gate that you are checking.
* `user : StatsigUser` The Statsig user object for whom the gate is being checked. For more information on the user object, see [here](/sdks/user#introduction-to-the-statsiguser-object).
Refer to the [Javascript on-device evaluation SDK documentation](/client/jsOnDeviceEvaluationSDK) for how to check other entities like experiments and dynamic configs.
```javascript theme={null}
client.logEvent('gate_check', { userID: randomUserId });
```
This is an event log in code.
The `logEvent` method takes two parameters:
* `eventOrName : string | StatsigEvent` This is the name and details of the event you are logging.
* `user : StatsigUser` The Statsig user object for whom the event is being logged.
For more information on event logging, see [here](/client/jsOnDeviceEvaluationSDK#logging-an-event).
```javascript theme={null}
client.flush();
```
This flushes all events from the SDK to Statsig. **Without this, you will not be able to get diagnostic information in the Statsig Console, nor any event data you logged**.
### Putting it all together
```javascript index.js theme={null}
import { StatsigServerlessClient } from '@statsig/serverless-client';
export default async function handler(request) {
const client = new StatsigServerlessClient(process.env.STATSIG_KEY);
let init = await client.initializeAsync();
const user = { userID: Math.random().toString().substring(2, 5) };
const passed = client.checkGate('pass_gate', user);
client.logEvent('serverless_event', user, passed.toString());
client.flush();
return new Response(
JSON.stringify({ passed, user }),
);
}
```
### Bootstrapping
You can use the serverless SDK to bootstrap your client SDK.
```javascript theme={null}
// Get client initialize response for a user
const values = statsig.getClientInitializeResponse(user, options);
// Pass values to a client SDK to initialize without a network request
```
For more information on bootstrapping including options and full code example, see [here](/server-core/node-core#client-sdk-bootstrapping-|-ssr)
### Bring your own CDN
The Statsig Serverless SDK also supports the bring-your-own-CDN model. You can now store your Statsig config specs anywhere, and initialize your client directly from that source. This use case has been tested and optimized for usage with AWS Lambda/Lambda\@Edge and S3 but is compatible with any other data source. Ensure the URL you provide returns the Statsig config specs for your project.
```javascript theme={null}
let init = await client.initializeViaURL("https://my-statsig-config.s3.us-east-1.amazonaws.com/my_dcs.json")
```
After initializing, use the SDK as usual.
# Slack Notifications
Source: https://docs.statsig.com/integrations/slack
Configure the Statsig Slack integration to deliver project, team, and personal notifications for experiments, feature gates, and metric alerts.
Depending on your organization’s Slack settings, you may need help from a Slack Admin to complete setup.
***
Statsig's Slack integration seamlessly connects your experimentation platform with your team's communication hub. By enabling this integration, you can receive real-time updates and alerts directly in your Slack workspace. Stay informed about critical changes to your feature gates, experiments, and dynamic configs without constantly monitoring the Statsig console or the Statsig operational health [status page](https://status.statsig.com).
## Setting Up Slack
**Step 1:** From your Statsig Console, go to **Statsig Settings** -> **[Integrations](https://console.statsig.com/integrations)**.
**Step 2:** Select Slack and click **+ Add Connection**.
**Step 3:** Allow the Statsig app to connect to your Slack workspace and Slack channel where you would like to receive Statsig's notifications.
***
## Product Notifications
**Step 4:** Filter to the relevant Team, Tags, or Target Apps.
**Step 5:** Choose the notifications about product-level activities and status changes you want to subscribe to.
* You may only create an experiment with the status "setup" or "active".
* You can only transition to "decision\_made" from "active".
A full experiment example is included in the open source Github repo [https://github.com/statsig-io/terraform-provider-statsig/blob/main/examples/resources/statsig\_experiment/resource.tf](https://github.com/statsig-io/terraform-provider-statsig/blob/main/examples/resources/statsig_experiment/resource.tf).
# Managing Gates With Terraform
Source: https://docs.statsig.com/integrations/terraform/terraform_gate
Define Statsig feature gates as Terraform resources, including rules, conditions, and rollout percentages, for fully reproducible feature flag setups.
You can create a .tf file (Terraform File) to configure your Statsig feature gates. All features of [console/v1/gates](/console-api/gates) are supported. The layout is very similar to the JSON body of a /gates request.
Requiring the Statsig provider. (You will need to change the version).
```go theme={null}
terraform {
required_providers {
statsig = {
version = "x.x.x"
source = "statsig-io/statsig"
}
}
}
```
## Basic Example
Creating a basic gate resource
```go theme={null}
resource "statsig_gate" "my_gate" {
name = "my_gate"
description = "A short description of what this Gate is used for."
is_enabled = true
id_type = "userID"
rules {
name = "Public"
pass_percentage = 100
conditions {
type = "public"
}
}
}
```
## Conditions
All Console API conditions are supported but the syntax needs a little tweaking.
* **type** | string | The [type](/console-api/rules#all-conditions) of condition it is.
* **operator** | string | What form of evaluation should be run against the **target\_value**.
* **target\_value** | \[string] | The value or values you wish to evaluate. Note: This must be an array, and elements should be of string type. (You can put quotes on numbers. 31 -> "31")
* **field** | string | Only for custom\_field condition type. The name of the field you wish to pull for evaluation from the "custom" object on a user.
```go theme={null}
conditions {
type = "custom_field"
target_value = ["31"]
operator = "gt"
field = "age"
}
```
See the full list of conditions [here](/console-api/rules#all-conditions).
A full gate example is included in the open source Github repo [https://github.com/statsig-io/terraform-provider-statsig/blob/main/examples/resources/statsig\_gate/resource.tf](https://github.com/statsig-io/terraform-provider-statsig/blob/main/examples/resources/statsig_gate/resource.tf)
# Datadog Triggers
Source: https://docs.statsig.com/integrations/triggers/datadog
Configure Datadog triggers in Statsig to react to Datadog monitor events with automated rollback, killswitch, or notification actions on feature flags.
### Overview
Triggers are a way to make changes to your Statsig project from a 3rd party source. You can create a trigger with a specific action like "Disable a feature gate". This will generate a URL that will perform that action when hit.
Triggers can be used with Datadog to toggle a gate on or off depending on the performance of a metric. An example use case would be to create a trigger that disables a gate and hook it up to a Datadog monitor so that if metric regression is detected, you can automatically turn off the feature.
### Trigger Types
Currently, the only supported type of triggers are gate triggers.
### Creating a Trigger
1. On Statsig console, navigate to the [integrations](https://console.statsig.com/integrations) tab.
2. Find and open **Datadog** -> **Triggers**.
3. Specify the target gate and action, then click **Create**
#### Configure Integration
1. Head over to the [Vercel Marketplace](https://vercel.com/integrations/statsig) and install the Statsig integration.
2. You will be prompted to create a new Statsig account or link an existing Statsig account.
* Click **Accept and Create**
* Enable Edge Config Syncing to have statsig automatically push configs into Vercel's Edge Config
* Select your project and edge config
* Click **Save**
Your Statsig Integration is now complete! You can go to the **storage** tab to confirm your Statsig config specs have propagated to your Edge Config.
#### Install the Statsig SDK
```bash theme={null}
npm install @statsig/vercel-edge
```
#### import the Vercel helper
```bash theme={null}
import {handleWithStatsig} from '@statsig/vercel-edge
```
#### Use the SDK
```Javascript theme={null}
export default handleWithStatsig(handler, params)
```
The helper method takes two arguments:
* `handler` This is your Vercel function code
* `params`
| Parameter | Optional | Type | Description |
| ---------------- | -------- | ---------------- | ----------------------------------------------------------------- |
| `configKey` | No | `string` | The Key associated with your Statsig specs in your Edge Config |
| `envStatsigKey` | No | `string` | Your Statsig Client API Key |
| `statsigOptions` | Yes | `StatsigOptions` | See StatsigOptions [here](/client/javascript-sdk#statsig-options) |
For best practice:
* Store `configKey` and `envStatsigKey` as environment variables in your Vercel project settings
### Example Usage
```javascript api/index.js theme={null}
import { handleWithStatsig } from "@statsig/vercel-edge";
export const config = {runtime: 'edge'};
async function myHandler(request, client){
const user = { userID: Math.random().toString().substring(2, 5) }; //Generates a random user id
const passed = client.checkGate('test_vercel_edgeconfig', user);
client.logEvent('vercel_wrapper', user, passed.toString());
return new Response(
JSON.stringify({ passed, user })
);
export default handleWithStatsig(myHandler,{
configKey : process.env.EDGE_CONFIG_KEY,
statsigSdkKey: process.env.STATSIG_KEY
})
```
The `handler` parameter is **your Vercel function code** .This is the same code you would normally export directly in your API route (for example, `myHandler` in the snippet above).\
Instead of exporting it, you pass it into `handleWithStatsig`, which takes care of the Statsig setup and cleanup for you.
**Here’s what happens behind the scenes:**
1. The Statsig SDK initializes a client using the config specs stored in your Edge Config.
2. Your function code (the handler) runs as usual.
3. Any events you log are automatically flushed back to Statsig when execution finishes.
**Your Vercel function behaves exactly the same, but you no longer need to manually handle Statsig initialization or event flushing.**
**That's it!** The helper automatically:
* Initializes the Statsig Client with config specs from your Edge Config
* Executes your Vercel function code (Your business logic + Statsig usage)
* Flushes all events after your handler completes execution
* Cleans up resources
## Advanced Implementation
**Use the advanced/manual setup if:**
* You need fine-grained control over initialization timing
* You need fine-grained control over event flushing timing
* You need to customize error handling behavior
### Prerequisites
* Completed the [Statsig Vercel integration setup](#configure-integration)
```bash theme={null}
npm install @statsig/vercel-edge
```
```bash theme={null}
import {StatsigVercelClient} from '@statsig/vercel-edge'
```
```javascript theme={null}
const client = new StatsigVercelClient(process.env.STATSIG_KEY)
```
The client instantiation takes two arguments:
* `sdkKey : string` This is your Statsig client API key. It is available from the [Project Settings](https://console.statsig.com/api_keys) page in the Statsig Console. This is used to authenticate your requests.
* `options : StatsigOptions` See here, for more [options](/client/javascript-sdk#statsig-options).
For best practice:
* Store `sdkKey` as an environment variable in your Vercel project settings
The following line initializes the client by loading feature gate and experiment configurations directly from your Vercel Edge Config.
```javascript theme={null}
const init = await client.initializeFromEdgeConfig();
```
The client initialization takes one argument:
* `ConfigKey : string` The Key associated with your Statsig specs in your Edge Config
```javascript theme={null}
const GateResult = client.checkGate('pass_gate', user);
```
This is a gate check in code.
The `checkGate` method takes two arguments:
* `name : string` The name of the Statsig gate that you are checking.
* `user : StatsigUser` The Statsig user object for whom the gate is being checked. For more information on the user object, see [here](/sdks/user#introduction-to-the-statsiguser-object).
Refer to the [Javascript on device evaluation sdk documentation](/client/jsOnDeviceEvaluationSDK) for how to check other entities like experiments and dynamic configs.
```javascript theme={null}
client.logEvent('gate_check', { userID: randomUserId });
```
This is an event log in code.
The `logEvent` method takes two parameters:
* `eventOrName : string | StatsigEvent` This is the name and details of the event you are logging.
* `user : StatsigUser` The Statsig user object for whom the event is being logged.
For more information on event logging, see [here](/client/jsOnDeviceEvaluationSDK#logging-an-event).
```javascript theme={null}
waitUntil(statsig.flush());
```
This flushes all events from the SDK to Statsig. **Without this, you will not be able to get diagnostic information in the Statsig Console, nor any event data you logged**.
### Putting it all together
```javascript api/index.js theme={null}
import { StatsigVercelClient } from '@statsig/vercel-edge';
import { waitUntil } from '@vercel/functions';
export const config = {
runtime: 'edge',
};
export default async function handler(request) {
const client = new StatsigVercelClient(process.env.STATSIG_KEY);
let init = await client.initializeFromEdgeConfig(process.env.EDGE_CONFIG_KEY);
const user = { userID: Math.random().toString().substring(2, 5) };
const passed = client.checkGate('pass_gate', user);
client.logEvent('vercel_event', user, passed.toString());
waitUntil(client.flush())
return new Response(
JSON.stringify({ passed, user }),
);
}
```
## Other Considerations
### Polling for updates v5.13.0+
The SDK cannot poll for updates across requests since Vercel Edge Functions do not allow for timers outside of the request handler.
To optimize for edge use cases, we do not provide an api to recognize updates to your config specs. However, when a change is made to your project definition on the Statsig console, the changes will be propagated to your Edge Config and will be reflected the next time you initialize the Statsig client.
### Flushing events v4.16.0+
The SDK enqueues logged events and flushes them in batches. In order to ensure events are properly flushed, we recommend calling flush using `waitUntil()` from `@vercel/functions`. This will keep the request handler alive until events are flushed without blocking the response.
```
waitUntil(client.flush());
```
### Size Limits
Vercel Edge Config has maximum size limits that may prevent Statsig from pushing configs into your Edge Config. See [here](https://vercel.com/docs/concepts/edge-network/edge-config/edge-config-limits) for the latest Vercel Edge Config limits.
### Unsupported Features
Statsig ID Lists are not currently synced into Vercel Edge Config. If you rely on large (>1000) ID lists, you will not be able to check them in your Vercel edge functions. This is why we set `initStrategyForIDLists: 'none'` in the SDK initialization.
If you want to check on the evaluations you are getting, you can go to the gate you created for this example and look at the evaluations in the Diagnostics tab.
{
await initStatsig(env);
// ideally, use a logged in userid. In this example, I have the RayID from cloudflare
const rayID = request.headers.get('cf-ray') || '';
const user = {
userID: rayID,
};
const promptExp = Statsig.getExperimentSync(
user,
"workers_ai_experiment", // Name of your experiment in Statsig Console
);
// fetch the prompt and model to use for this ray ID
// providing default values in case of failure to initialize statsig from the kv store
const prompt = promptExp.get("prompt", "What is the origin of the phrase Hello, World");
const model = promptExp.get("model", "@cf/meta/llama-3.1-8b-instruct");
const start = performance.now();
const response = await env.AI.run(model, {
prompt,
});
const end = performance.now();
const aiInferenceMs = end - start;
logUsageToStatsig(user, model, response, aiInferenceMs);
ctx.waitUntil(Statsig.flush(1000));
return new Response(JSON.stringify(response.response));
},
} satisfies ExportedHandler;
/**
* Logs AI model usage and performance metrics to Statsig.
* @param user The StatsigUser object.
* @param model The name of the AI model used.
* @param response The response object from the AI model (expected to contain a 'usage' field).
* @param aiInferenceMs The time taken for AI inference in milliseconds.
*/
function logUsageToStatsig(user: StatsigUser, model: string, response: any, aiInferenceMs?: number) {
const metadata = {
...(response?.usage || {}),
ai_inference_ms: aiInferenceMs,
};
Statsig.logEvent(user, "cloudflare_ai", model, metadata);
}
/**
* Initializes the Statsig SDK.
* Make sure you have the right bindings configured for the KV, and a secret for the Statsig API key
* Refer to https://docs.statsig.com/integrations/cloudflare for more details on integrating Statsig with Cloudflare workers
* @param env The Workers environment variables.
*/
async function initStatsig(env: Env) {
const dataAdapter = new CloudflareKVDataAdapter(env.STATSIG_KV, 'statsig-YOUR_STATSIG_PROJECT_ID'); // Replace with your actual project ID
await Statsig.initialize(
env.STATSIG_SERVER_API_KEY, // Your Statsig secret key
{
dataAdapter: dataAdapter,
postLogsRetryLimit: 0,
initStrategyForIDLists: 'none',
initStrategyForIP3Country: 'none',
disableIdListsSync: true,
disableRulesetsSync: true, // Optimizations for fast initialization in Cloudflare Workers
},
);
}
```
**Explanation:**
1. **`initStatsig(env)`**: This function initializes the Statsig SDK using the `CloudflareKVDataAdapter` to fetch configurations from Cloudflare KV, ensuring low-latency access to your experiment setups. Make sure to replace `'statsig-YOUR_STATSIG_PROJECT_ID'` with your actual Statsig project ID and configure `STATSIG_SERVER_API_KEY` and `STATSIG_KV` as environment variables in your Worker.
2. **`Statsig.getExperimentSync(...)`**: This is the core of the experimentation. It retrieves the assigned experiment variant for the current user (based on `rayID`) for the `workers_ai_experiment` experiment. The `get()` method then safely retrieves the `prompt` and `model` parameters defined in your Statsig experiment, falling back to default values if the experiment or parameter is not found.
3. **`env.AI.run(model, { prompt })`**: This executes the AI model provided by Cloudflare Workers AI with the dynamically chosen `model` and `prompt`.
4. **Latency Measurement**: `performance.now()` is used to capture the start and end times of the AI inference, allowing you to track the `ai_inference_ms` metric.
5. **`logUsageToStatsig(...)`**: This function logs a custom event (`cloudflare_ai`) to Statsig. It includes the `model` used as the event value and attaches metadata such as `ai_inference_ms` and any `usage` information (e.g., token counts) returned by the AI model. This data is crucial for analyzing model performance and cost.
6. **`ctx.waitUntil(Statsig.flush(1000))`**: This ensures that all logged events are asynchronously sent to Statsig before the Worker's execution context is terminated, without blocking the response to the user.
### Other Use Cases enabled by this Integration
* **Prompt Tuning:** An e-commerce app running on Workers AI tries two different prompt styles for product descriptions. Statsig tracks cart conversion and time on site, revealing which prompt yields higher sales.
* **Model Selection:** A developer tests GPT-3.5 vs. GPT-4 within Cloudflare Workers AI. Statsig shows which model, combined with specific temperature or frequency penalty values, generates more accurate or user-satisfying results.
* **Response Latency vs. Quality:** By varying max token length and frequency penalties within an experiment, Statsig helps optimize for speed without sacrificing accuracy, crucial for user-facing chat applications.
* **Cost Optimization:** Monitor `prompt_tokens` and `completion_tokens` by model and prompt variant to identify the most cost-effective AI configurations.
# Metrics Overview
Source: https://docs.statsig.com/metrics/101
Learn the fundamentals of setting up essential product metrics in Statsig, including events, user counts, retention, and how metrics power experiments.
**Warehouse Native users**: You're viewing the Cloud docs for this page. Metrics and experiments behave differently in Warehouse Native. Read more in [Data & Semantic Layer in Warehouse Native](/statsig-warehouse-native/configuration/data-and-semantic-layer).
This 101-level user guide steps through the basic concepts to help you set up essential product metrics in your Statsig Project.
1. [How Metrics Work on Statsig](/metrics/how-metrics-work)
2. [Raw Events](/metrics/raw-events)
* [Types of Raw Events](/metrics/raw-events#types-of-raw-events)
* [Unit Identifiers](/metrics/raw-events#unit-identifiers) required for raw events
* [ID Mapping Considerations](/experiments-plus/create-new#id-mapping-capabilities) for cross-ID analysis
* [Ingesting Raw Events](/metrics/raw-events#ingesting-raw-events)
* [Seeing Raw Events in the Statsig Console](/metrics/raw-events#raw-events-in-console)
3. [Auto-generated Events](/metrics/raw-event-metrics)
* [Event Count](/metrics/raw-event-metrics#event-count-metric) and [Event DAU](/metrics/raw-event-metrics#event-dau-metric) metrics
* [User Accounting](/metrics/raw-event-metrics#user-accounting-metrics)
4. [Custom Metrics](/metrics/custom-metrics)
5. [Importing Precomputed Metrics](/metrics/precomputed-metrics)
6. [Pulse Metrics](/metrics/pulse)
**Ask for Help**: Hop on to the [Statsig Slack channel](https://statsig.com/slack) if you have any questions or want to validate the best path to import your metrics.
# Metrics 201 - Creating Custom Metrics
Source: https://docs.statsig.com/metrics/201
Create custom metrics, organize them with tags, and customize DAU definitions in Statsig as your product analytics project grows beyond the basics.
In this 201-level user guide, you'll learn to create your own metrics and organize them as your project grows. You'll also be able to customize the definition of your daily active users (DAU).
1. [Creating Custom Metrics](/metrics/create) for your product in the Statsig console
2. [Creating Metric Tags](/metrics/create-metric-tags) to organize the metrics in your Statsig Project
3. [Customizing the DAU Definition](/metrics/user) that Statsig uses to compute [User Accounting](/metrics/raw-event-metrics#user-accounting-metrics) metrics.
# Metrics 301 - Real-time Analytics
Source: https://docs.statsig.com/metrics/301
Advanced guide to Statsig product analytics covering real-time event analysis, multi-step user funnels, user flow visualization, and behavioral cohorts.
This 301-level user guide shows you:
1. How to use [Events Explorer](/product-analytics/overview) to analyze sampled real-time events emitted by your application
2. How to create [Create User Funnels](/metrics/create-user-funnels)
3. How to create [Create User Flows](/metrics/create-user-flows)
Watch this space for more real-time and out-of-box product analytics!
**What's on the roadmap?** Join us on the [Statsig Slack channel](https://statsig.com/slack) to ask for previews of Statsig's upcoming features or to submit a request. Most of our roadmap is built based on requests from customers!
# Archiving and Deleting Metrics
Source: https://docs.statsig.com/metrics/archiving-metrics
Manage the end-of-life for Statsig metrics through archiving and deletion options to keep your metrics catalog clean without breaking historical references.
Statsig offers two ways to manage the end-of-life for your metrics.
* **Archiving a metric**: the metric will no longer be computed, but its history will be retained for your record. Use this for when a metric is no longer relevant, but you still wish to maintain the history of it. Use case example: you can archive older versions of a metric that continues to evolve so you have a record of how the metric has evolved over time.
* **Deleting a metric**: the metric will be removed from Statsig completely, including its history. Use this for when you've made a mistake, logged or imported an irrelevant metric, or created a more accurate version of a metric. Use case examples include incorrect definition, incorrect name, duplicate metric that you don't want to confuse others with.
## Archiving Metrics
### Archiving a Metric
There are two ways to archive a metric:
1. In your Metric Catalog, select the metric(s) you want to archive to see a toolbar of options appear to **Archive**, **Compare**, or **Tag**. Select the **Archive** icon.
**Beta Feature**: Sketch-based count distinct metrics are in beta. Please reach out to learn more and join our beta testing!
## For context, what are sketches?
Sketches are a probabilistic summary of a large dataset that lets us answer certain queries "approximately" but very quickly and using little memory. It does this all while using very little memory (often a fixed-size or sublinear footprint, like O(log n) or even constant space regardless of dataset size).
## Core Principles of HLL++
1. **Hashing and Leading Zeros**
* Each input is hashed uniformly into a 64-bit integer.
* The position of the first 1-bit in the hash (the "rank") provides an estimate of how many distinct items precede that hash in sorted order.
2. **Register Array**
* The algorithm allocates *m* registers, where *m* = 2^p and *p* is the precision parameter.
* Each hashed value maps to one register. The register stores the maximum rank seen so far for values mapped to it.
3. **Sparse and Dense Modes**
* **Sparse mode** is used when the number of distinct items is below 2^(p+5). It keeps an exact list of non-zero registers in a compact form. This yields near-zero error for small cardinalities.
* **Dense mode** is used when the count exceeds the sparse limit. The sketch is represented as a fixed array of *m* registers, each one byte in size. Error increases slightly but remains tightly bounded.
4. **Estimation and Bias Correction**
* The raw estimate is computed as the harmonic mean of 2^(–register\_value) across all registers, multiplied by a constant factor (alpha\_m).
* BigQuery applies empirical bias corrections and the HIP (historic inverse probability) estimator to reduce variance and worst-case error.
## Precision, Memory, and Error Relationship
The precision parameter *p* controls the number of registers *m* and thus the sketch's size and accuracy:
| Precision p | Registers m = 2^p | Memory per Sketch | Approximate Relative Standard Error (1 sigma) |
| ----------- | ----------------- | ----------------- | --------------------------------------------- |
| 10 | 1,024 | \~1 KB | 0.83 / sqrt(1,024) ≈ 2.6 % |
| 12 | 4,096 | \~4 KB | 0.83 / sqrt(4,096) ≈ 1.3 % |
| 13 | 8,192 | \~8 KB | 0.83 / sqrt(8,192) ≈ 0.92 % |
| 15 | 32,768 | \~32 KB | 0.83 / sqrt(32,768) ≈ 0.46 % |
* Memory used grows linearly with *m*.
* Error decreases as the inverse square root of *m*.
* To halve the error, we must quadruple the number of registers.
**Examples of thresholds and steady‑state for common precisions:**
* **p = 10** (*m* = 1,024 registers, \~1 KB):
* Sparse limit: 2^(10+5) = 32,768 distincts (error ≈ 0%).
* Plateau begins at \~5·m = 5,120 distincts.
* Steady‑state error: 0.83/√1,024 ≈ 2.6%.
* **p = 12** (*m* = 4,096 registers, \~4 KB):
* Sparse limit: 2^(12+5) = 131,072 distincts.
* Plateau begins at \~5·m = 20,480 distincts.
* Steady‑state error: 0.83/√4,096 ≈ 1.3%.
* **p = 15** (*m* = 32,768 registers, \~32 KB):
* Sparse limit: 2^(15+5) = 1,048,576 distincts.
* Plateau begins at \~5·m = 163,840 distincts.
* Steady‑state error: 0.83/√32,768 ≈ 0.46%.
## Error Behavior Over Cardinality
The relative error of an HLL++ sketch evolves through three phases:
* **Exact Counting Phase**
* Cardinality ≤ 2^(p+5). The sketch operates in sparse mode with error close to 0%.
* **Bias Ramp Phase**
* Cardinality between 2^(p+5) and approximately 5·m. The sketch is in dense mode. Systematic bias increases gradually from near 0 up to the maximum bound.
* **Steady-State Phase**
* Cardinality ≥ 5·m. Relative error stabilizes at the theoretical bound of 0.83 / sqrt(m). Once in this phase, adding more distinct items does not change the sketch's register distribution shape—so the error remains effectively constant. In other words, after enough uniques, the sketch "plateaus," and error fluctuations are limited to the estimator's minimal random variance around that fixed bound.
### Example for p = 15 (m = 32,768)
* **Exact in sparse mode (≤ 1,048,576 items)** - For up to 2^(p+5) = 2^20 = 1,048,576 distinct elements, HLL++ uses a compact "sparse" representation that records individual hashes directly—resulting in an exact count (0% error).
* **Transition to dense mode & rising error** - Beyond 1,048,576 distinct elements, it switches to the full register array of size m = 2^p = 32,768. In this *dense* regime, the Relative Standard Error (RSE) gradually increases from 0% to its theoretical limit.
* **Asymptotic error plateau (≈ 0.46%)** - Once in dense mode, the RSE quickly converges to RSE ≈ 0.83/√m = 0.83/√32,768 ≈ 0.46%, and remains at approximately 0.46% regardless of further increases in distinct count.
## Merging Sketches Over Time or Partitions
To compute distinct counts across multiple segments (for example, daily sketches), we merge sketches by taking the element-wise maximum of their registers. This operation is associative and idempotent. Merged sketches preserve the same error bound as individual sketches and do not add additional error.
## Mathematical Formulation
1. **Raw Estimate**
* *M\[i]* is the value of register *i*.
* *alpha\_m* is a bias correction constant dependent on *m*.
This is the core HyperLogLog "raw" estimator for the number of distinct elements in a multiset. You take each register value M\_i, compute $2^{-M_i}$, sum those values, invert that sum, and multiply by m^2 (where m is the number of registers) to get a harmonic-mean-based estimate. This is then scaled by the bias-correction constant α\_m. In effect, this formula transforms the observed distribution of leading-zero counts into an approximate count of unique items.
2. **HIP Estimator**
* Maintains a running sum of inverse probabilities for each new distinct element.
* Produces lower variance and a smaller worst-case error constant (0.83 instead of 1.04).
3. **Relative Standard Error (RSE)**
RSE ≈ 0.83/√m
## Best Practices and Limitations
* Choose precision *p* based on the maximum cardinality we expect and the error tolerance. (This will be done for you so you don't have to worry about it)
* Once a sketch is created with precision *p*, we cannot increase its precision later. We can only merge or downsample to lower precision.
* Long keys or complex objects increase CPU and memory in sparse mode but do not affect dense mode size.
* Plan for a noise floor equal to the sketch's relative error when designing experiments or setting thresholds.
* Please reach out if you believe you require higher precision.
## Conclusion and Recommendations
HLL++ sketches provide efficient, bounded- error approximations for `count_distinct` queries. They trade a small, predictable error for large savings in memory and compute.
* Memory scales as O(m) rather than O(n).
* Error scales as O(1/√m).
* Merging sketches is exact for unions, with no extra error.
Select the smallest precision *p* that meets your accuracy requirements to minimize storage and computation costs.
## Choosing Precision for Your Cardinality
When you know the maximum number of unique items (cardinality) ahead of time, pick a precision *p* so that **5 · 2^p** exceeds that cardinality. This ensures the sketch is in its steady‑state phase, where the relative error remains at the bound of 0.83/√(2^p).
* **Up to 10,000 uniques**
* *p* = 12 (m = 4,096 registers) → memory \~4 KB
* Steady state from \~20,480 distincts (5·m) onward
* Relative error ≈ 0.83/√4,096 ≈ 1.3 %
* **Up to 50,000 uniques**
* *p* = 13 (m = 8,192 registers) → memory \~8 KB
* Steady state from \~40,960 distincts onward
* Relative error ≈ 0.83/√8,192 ≈ 0.92 %
* **Up to 100,000 uniques**
* *p* = 15 (m = 32,768 registers) → memory \~32 KB
* Steady state from \~163,840 distincts onward
* Relative error ≈ 0.83/√32,768 ≈ 0.46 %
* **Up to 500,000 uniques**
* *p* = 16 (m = 65,536 registers) → memory \~64 KB
* Steady state from \~327,680 distincts onward
* Relative error ≈ 0.83/√65,536 ≈ 0.32 %
* **Up to 1,000,000 uniques**
* *p* = 17 (m = 131,072 registers) → memory \~128 KB
* Steady state from \~655,360 distincts onward
* Relative error ≈ 0.83/√131,072 ≈ 0.23 %
* **General rule**
1. Compute *m* = 2^p
2. Ensure **5·m ≥ expected cardinality**
3. Verify memory footprint (*m* bytes) fits your budget
4. Confirm relative error (0.83/√m) meets your accuracy target
## Conclusion
count\_distinct gives you a simple, consistent way to measure breadth at scale. Define once, use everywhere, and merge across time and partitions with stable behavior. You get decision-ready answers to “How many unique X?” without custom ETL or one-off SQL.
# Creating Custom Metrics
Source: https://docs.statsig.com/metrics/create
Create custom Statsig metrics from raw events using metric types such as event count, user count, sum, ratio, and funnel for experiment analysis.
Custom metrics are computed by Statsig from your raw events. To create custom metrics, navigate to **Metrics** from the left-hand navigation panel, then to the **Metrics Catalog** tab. Tap on the **Create** button.
**A Word of Caution**: In experimentation, ratio metrics are a frequent source of misleading information. It's possible to see an increase in **click through rate** alongside a net *decrease* in total clicks (the opposite may also happen). This situation can occur if the number of unique users viewing a button (denominator) decreases. As a best practice, Statsig recommends tracking the numerator and denominator as independent metrics when monitoring ratio indicator. Ratio metrics are often subject to statistical noise and can be tricky to use for obtaining a statistically significant result. In addition, for the numerator in ratios, we exclude units which don't have a denominator value.
### 5. Funnel Metrics
You can create a custom funnel metric, from either the Custom Metrics Creation wizard in the Metrics Catalog or via the **Charts** tab.
**Important Note**: Statsig handles funnel metrics differently between our Cloud and Warehouse Native platforms. Funnel metrics using our Cloud platform are *always* unordered, meaning that funnel steps can be completed in any order, and they have a time window of *one day*. This means that for the metric to record a completion, all steps must be triggered by a user within 24 hours. In contrast, funnel metrics on Warehouse Native have the option to be set with strict ordering and custom time windows.
### Components of Funnel Metrics
Funnel metrics have a few components:
1. **Lineage**: Surfaces the events used to generate the funnel
2. **Metric Value**: Metric value represents the overall funnel conversion rate, or the percentage of users who complete a funnel (trigger the end event) relative to all users who start the funnel (trigger the starting event)
3. **Conversion rate between stages**: This set of metrics track the percentage of users who triggered an event N relative to all users that triggered event N-1 in the funnel
Sketch-based count distinct metrics are currently in beta, please reach out to Statsig support if you would like this enabled.
* **What it is:** A high-performance way to estimate the number of distinct values using compact sketch data structures. Example use cases include trying to determine unique songs per user or unique products purchased by user.
* **Benefit:** Delivers much faster computation and uses significantly less memory compared to full exact distinct counting, especially at high cardinality.
### Custom Metrics & Dimensions
For Custom Metrics that are composed of a single event (event count/ event dau, aggregation, etc.), the dimensions of the source event will be automatically pulled through into the Custom Metric and be exposed as dimensions of that Custom Metric. However, if your Custom Metric is composed of 2+ different events, any associated dimension(s) of the source input events will *not* be pulled through as dimensions of the Custom Metric and are also not queryable today via the "Explore" tab in Pulse Results.
# Creating Metric Tags
Source: https://docs.statsig.com/metrics/create-metric-tags
Organize and group Statsig metrics using tags to create reusable collections for easier experiment scorecard setup, monitoring, and team-level views.
# Tagging Metrics
To create a metric tag, click on **Metrics** in the left hand navigation menu, and click on the [Metrics Catalog](https://console.statsig.com/4TLCtqzctSqusYcQljJLJE/metrics/metrics_catalog) tab.
Sketch-based count distinct metrics are in beta. Please reach out to Statsig support to join our beta.
It's worth noting that the "average" in aggregation is the average of event value (average revenue per purchase per user), instead of the average of exposed units (average revenue per user). The latter is defined by sum.
See **Metrics 201** topic, [Creating Custom Metrics](/metrics/create), to learn how to create custom metrics for your product.
# Deprecating Event_dau Metric
Source: https://docs.statsig.com/metrics/deprecate-event-dau
Important changes to auto-generated event_dau metrics in Statsig and how to migrate to user count metrics to maintain DAU tracking for your custom events.
### Deprecation Details
From Wednesday, October 16, 2024, we will stop auto-generating new event\_dau metrics for incoming events into Statsig. We will continue to auto-generate an event\_count metric for each logged event as we do today. **Note: This change will only affect Statsig Cloud customers, Warehouse Native customers will not be impacted.**
* Any existing event\_dau metrics that have been used in a gate, experiment, dashboard, other Custom Metrics will NOT be affected by this change.
* Existing event\_dau metrics that have been archived or never been used in another config will NO longer exist. See ‘Next Steps’ if you want to retain these metrics.
* Going forward, new event\_dau metrics will need to be created manually as a Custom Metric. See [this guide](/metrics/custom-dau) to learn how to create a DAU metric.
If you have any questions or concerns, please don’t hesitate to reach out!
### Motivation for This Change
Historically, we have auto generated an event\_count and event\_dau metric for every incoming event into Statsig. After working closely with hundreds of customers, we have seen that auto generating two metrics for every event causes confusion and clutter inside projects. The proposed change will lead to cleaner Metrics Catalog and faster Console performance, while still retaining your ability to create event\_dau metrics for the events you care about most.
### Next steps
If you wish to keep any unused event\_dau metrics going forward, you can earmark those metrics by performing any of the actions below:
* Adding a Tag (RECOMMENDED)
* Adding a description
* Referencing in a gate/experiment/dashboard
These actions will mark your unused metric as active, signaling us that you don’t want them to be deprecated.
# Running Analysis Across Unit Types, AKA Cluster Experiments
Source: https://docs.statsig.com/metrics/different-id
Run Statsig experiment analysis when the assignment unit differs from the analysis unit, including how to configure cross-ID mappings and interpret results.
There are two common scenarios where the experiment assignment unit differs from the analysis unit:
1. Measuring session-level metrics for a user-level experiment. Ratio metrics are commonly used to solve this (this doc).
2. Measuring logged-in metrics (eg. revenue) on a logged-out experiment. There are two solutions:
a. Running the experiment at the [device-level](/guides/first-device-level-experiment), with device-level metrics collected even after the user is logged-in.
b. Using [ID resolution](/statsig-warehouse-native/features/id-resolution).
We will explain how to set up the first scenario with Warehouse Native in this doc.
**Warehouse Native users**: You're viewing the Cloud docs for this page. Metrics and experiments behave differently in Warehouse Native. Read more in [About Warehouse Native](/statsig-warehouse-native/introduction#how-warehouse-native-works).
A metric in Statsig is a numeric value for each user on a given day. This value can be aggregated across the entire user base or a subset, such as the test or control group of an experiment.
For example, say one user made two purchases on September 1st, and another made only one. These values can be aggregated across multiple users to calculate the total number of purchases across all users on September 1st.
By default, Statsig computes metrics from logged raw events in the production environment.
When testing experiments in lower environments (such as development or staging) with **Enable for Environments**, you can track cumulative exposures and metric results collected from those environments. This allows you to validate your experiment setup before launching to production but production data is prioritized for final Pulse result analyses.
## Two Sources of Statsig Metrics
There are two fundamental sources of metrics in Statsig:
1. **Raw Events**
* Statsig [auto-generates certain metrics](/metrics/metrics-from-events) such as **event\_count** and user accounting metrics from these events
* You can also define [custom metrics](/metrics/create) using your logged raw events
2. **Precomputed Metrics** - You can provide these pre-computed values to Statsig
Statsig's Stats Engine joins these metrics with your exposure events from feature gates and experiments to compute experiment results and analytics.
**How are events and metrics billed?** Each event (or a row when importing from your data warehouse) is billed once, regardless of how many experiments the event is used in.
# Ingesting Metrics
Source: https://docs.statsig.com/metrics/ingest
Import precomputed metrics from Snowflake, BigQuery, Redshift, and other data warehouses into Statsig using built-in connector integrations and scheduled syncs.
Statsig can ingest your precomputed product and business metrics using our data warehouse connector (Metrics Imports). Integrations like [Snowflake](/integrations/data-imports/snowflake), [BigQuery](/integrations/data-imports/bigquery) and [Redshift](/integrations/data-imports/redshift) are supported.
Statsig does not automatically process these metrics until you mark them as ready, as it's possible you might land data out of order. Once you are finished loading data for a period, you mark the data as ready by hitting the `mark_data_ready` API:
```
curl --location --request POST ‘https://api.statsig.com/v1/mark_data_ready’ \
--header ‘statsig-api-key: {your statsig server secret}’ \
--header ‘Content-Type: application/json’ \
--data-raw ‘{
“timestamp”: 1647975283,
“type”: “metrics”
}
```
The timestamp provided should be:
* A unix timestamp
* Represents the latest point in time for which all metrics before have been uploaded.
* Any future calls to this API with an earlier timestamp will be invalid.
* We don’t guarantee correct behavior if metrics are provided with an earlier timestamp after this API is called.
Statsig processes metrics as a full day in the PST timezone; we will wait until a full day is marked as ready before processing that day.
## Debugging Precomputed Metrics
All precomputed metrics generate Metric Detail View pages. However, these Detail View pages take a few hours to generate post-ingestion. The fastest way to start seeing and debugging your precomputed metrics is via the **Metrics Logstream** on the **Metrics Catalog** tab within **Metrics**.
” \
--header “Content-Type: application/json” \
--request POST \
--data “{"isTest": true, “metrics": [{"user_id": "1237", "metric_name": "test_metric", "id_type": "user_id", "metric_value": 90}, {"user_id": "4568", "metric_name": "ratio", "id_type": "stable_id", "numerator": 3, "denominator": 15}]}”
```
Add metric source filter Outlier Management Variance Reduction Cohorts and Delayed Data **Tip**: Customers can trip up on ensuring that their precomputed metrics have the right ID type. Pay extra attention to this column!
Finally, the **Metrics Stream** only appears if you're actively ingesting precomputed metrics. If you're not seeing it appear at the bottom of your **Metrics Catalog**, Statsig likely is not receiving your precomputed metrics due to a connection issue or an invalid schema.
# Pulse Metrics
Source: https://docs.statsig.com/metrics/pulse
How different Statsig metric types are computed and interpreted in Pulse experiment results, including confidence intervals, lift, and significance flags.
Experiments with Statsig use **Pulse** to compute and communicate results. The metric type is important in computing and interpreting the final result.
Most metric types are aggregated across all users in the group; however, some metric types that use ratios are only aggregated across [participating users](/experiments/interpreting-results/participating-units) (users that have non-null value for that metric). We'll walk through the various types of metrics available in experiments and how to interpret their pulse results.
## Pulse Statistics by Metric Type
| Metric Type | Total | Mean | Units |
| ----------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| event\_count | Sum of events (99.9% winsorization applied) | Average events per user (99.9% winsorization applied) | All users |
| event\_dau | Sum of event DAU (distinct user-day pairs) | Average event\_dau value per user per day. Note that we call this "Event Participation Rate" as this can be interpreted as the probability a user is DAU for that event. | All users |
| sum | Total sum of values (99.9% winsorization) | Average value per user (99.9% winsorization) | All users |
| mean | Overall mean value | Overall mean value | [Participating users](/experiments/interpreting-results/participating-units) |
| event\_user | Count of distinct users that have had the event. | Average metric value per user per day. Depending on Rollup Mode, can be a one-time event or daily participation rate. | All users |
| ratio | Not shown | Overall ratio: sum(numerator values)/sum(denominator values) | [Participating users](/experiments/interpreting-results/participating-units) |
| funnel | Not shown | Overall ratio: sum(numerator values)/sum(denominator values) | [Participating users](/experiments/interpreting-results/participating-units) |
| user: dau, wau, mau\_28day | Not shown | Average metric value per user per day. The probability that a user is xAU | All users |
| user: new\_dau, new\_wau, new\_mau\_28day | Count of distinct users that are new xAU at some point in the experiment | Fraction of users that are new xAU | All users |
| user: retention metrics | Overall average retention rate | Overall average retention rate | [Participating users](/experiments/interpreting-results/participating-units) |
| user: L7, L14, L28 | Not shown | Average L-ness value per user per day | All users |
| count\_distinct | Total number of unique values | Average number of unique values per user | All users |
**Some example metric breakdowns in Pulse:**
**event\_dau Legacy Support**: event\_dau metrics are now in legacy support only and are no longer created for new events. Existing event\_dau metrics will continue to be available for any of your new experiments and will continue to be computed daily. For all new events, you should create an event\_user metric to measure daily active users.
From [Metrics 101](/metrics/101) and [Auto-generated Metrics](/metrics/raw-event-metrics),
* [**event\_count**](/metrics/raw-event-metrics#event-count-metric) measures the volume of the activity based on count of events triggered
* [**event\_dau**](/metrics/raw-event-metrics#event-dau-metric) measures unique daily users who triggered a given event
For example, the table below shows the **event\_count** and **event\_dau** metrics for two event types,*Page Views* and *Add to Cart*, for three users over three days.
**Event Count and Event DAU in Custom Metrics**: When creating a custom ratio metric, use event\_count to include all events (counting all events triggered by the same user). Use event\_user (or event\_dau, if available) to count unique active users on a given day (all events triggered by the same user are counted as one).
## Winsorization
To reduce the impact of outliers, Statsig caps *event\_count* and *sum* metric types at the 99.9th percentile (by default). This mitigates the risk of bots and extreme values significantly swaying experiment results.
The winsorization 99.9th percentile is computed using all non-zero and non-null values of the metric, and then all values of exceeding this limit are replaced with it.
Warehouse Native (WHN) allows for more customization of winsorization by metric and by percentile.
## Frequently Asked Questions
**1. Is it possible for a ratio metric to move in the opposite direction than both the numerator and denominator metrics?**
Yes, it is possible for the ratio to rise while both the numerator and denominator metrics decline. For example, this happens when the denominator is falls more than the numerator. As a best practice, Statsig recommends tracking the numerator and denominator as independent metrics when monitoring ratio metric. Ratio metrics are often subject to statistical noise and can be tricky to use for obtaining a statistically significant result.
**2. For ratio metrics, how does Statsig determine *participating users*?**
Ratio metrics are computed only for users that have a non-zero value in the denominator, i.e. the user must have triggered the denominator event on a given day to be included in the daily ratio. Users that don't trigger the denominator event during an experiment are not included in the test vs. control comparison of a ratio metric.
**3. What is the difference in metrics between One-Time Event vs Daily Participation Rate?**
The distinction between these in only relevant in the context of an experiment.
Daily participation rate counts the number of *days* a user has that event, divided by the number of *days* the user has been in the experiment.
One time event is a binary metric that checks whether the user has that event *at least once* during their time in the experiment.
# Auto-generated Metrics
Source: https://docs.statsig.com/metrics/raw-event-metrics
How Statsig automatically generates event_count metrics from each custom event you log so you can monitor activity and use them in experiment scorecards.
# Auto-generated Metrics
Metrics are critical for monitoring the health and usage of your product as well as the impact of new features and experiments.
Statsig automatically generates an "event\_count" metric for each uniquely named **custom event** that you log. Auto-generated metrics are created from production environment events, and any newly logged custom event should have an event\_count metric created within 24 hours of logging their first events.
When testing experiments in lower environments (such as development or staging) with **Enable for Environments**, you can track cumulative exposures and metric results collected from those environments. This allows you to validate your experiment setup before launching to production but production data is prioritized for final Pulse result analyses.
This auto-generated metric consists of three elements:
1. **Roll-up Window** - Statsig computes metrics from custom events aggregated over a 24-hour day, with the hours depending on your company's setting. These hours do not change with daylight saving time. This prevents some days from having 23 and 25 hours which can cause a +/-4% change to some metrics on a biannual basis.
2. **Unit Identifier** - While you can record custom events with and without a unique user identifier, Statsig requires a unit identifier (usually a user\_id) to track a user across multiple events and sessions to support Experiments, Pulse (experiment results), and Autotune. If you don't have access to a user\_id when logging a custom event, create a temporary identifier to track users at a session or device-level.
3. **Metric Value** - Statsig automatically computes values for **event\_count**, which measures the number of times an event is triggered.
Up until October 16, 2024, Statsig also auto-computed values for an **event\_dau** metric that measures the number of unique users that triggered the event. While Statsig no longer auto-compute an **event\_dau** metric for every logged event, you can create your own metrics that function like **event\_dau** via [Custom Metrics](/metrics/custom-dau). Please see the [event\_dau deprecation details](/metrics/deprecate-event-dau) for more information.
| Metric | Automatic | Dimensions | Possible Values | Description | Example |
| -------------------------------------------------- | --------- | ---------- | --------------- | -------------------------------------------------------------------------- | ------------------------------ |
| event\_count | Yes | Yes | 0, 1, 2,... | Counts the number of events triggered on a given day | Number of page views |
| event\_dau (Legacy support as of October 16, 2024) | Yes | Yes | 0, 1 | Marks each user as 1 or 0 based on whether they triggered the event or not | Unique users who viewed a page |
When you click on an event type in the **Events** tab, you will see a detailed view of the event, including any metrics linked to that event. Click on these metrics to visit the detail pages for these metrics.
Auto-generated **User Accounting Metrics** are not supported today for data warehouse ingestions.
## Metrics Catalog
The **Metrics Catalog** tab allows you to quickly search and tag your metrics. Tags enable organizing your metrics and creating collections of metrics that are associated in some way. For example, you could tag a set of metrics focused on a product area, business function, or business objective. You can also create a loose collection of guardrail metrics that teams can add to every experiment to ensure they are causing no unexpected effects in other parts of the business. Once you create a tagged collection of metrics, you can easily pull up this set of metrics when viewing your experiment results and zoom into the context that you want to focus on.
See deprecation notice above.
Like **event\_count**, Statsig formerly created an **event\_dau** metric that measures the number of unique users who trigger a specific event on a given day. Each user can have a value of 1 or 0 corresponding to active or inactive, based on whether they trigger an event or not, on a given day. This metric counts the number of users who are marked as active ("1") or not ("0").
It's important to note that an **event\_dau** metric produces a single value per user per day. When the metric is aggregated for users across the duration of an experiment, it is known as the "Event Participation Rate" as this can be interpreted as the probability a unit is DAU for that event. As such, **event\_dau** metrics are always between 0 and 1 for a user, since they are computed as "# Days with the Event" / "# Days Being Considered".
**Tip**: Sometimes you might want a metric similar to **event\_dau** but not normalized by a number of days. If you're looking for a metric that measures if the user has an event over the entire duration of the experiment, try a custom metric set to metric type "Unit Count" with "One-Time Event" rollup mode.
This metric works well in experimentation as it minimizes outliers, has tighter confidence intervals, and enables a simple measure to describe a user's breadth of activity across different events.
Statsig computes the **event\_dau** for each unit ID that you define in your Statsig Project. For example, given User IDs, **event\_dau** counts the number of distinct users that triggered the event. Given Stable IDs, *event\_dau* counts the number of distinct devices using your application.
You will find an **event\_dau** metric for each event type that you record with Statsig. The name of the metric matches the name of the raw event and its metric type is marked as **event\_dau**.
When processing events, event names that contain this regex/character set are dropped `"\\[\]{}<>#=;&$%|\u0000\n\r`
## Raw Events in Console
As you ingest custom events, you'll see these listed in the **Metrics** section under the **Events** tab in the Statsig console.
Rollout Alerts do not alert at the **topline metric value** level, but rather at **the experiment/feature gate level**. This means that even if you have an experiment allocated to 10% of your users, but the metric change within that 10% allocation breaches the set threshold, you will be alerted. All alerts you receive will be in the context of a specific experiment or feature gate and to debug/resolve the alert you will be directed to the offending experiment or gate in question.
## Setting up a Rollout Alert
To set up a metric alert, go to the **Metrics** tab —> **Metrics Catalog** and search for the desired metric.
**Warehouse Native Users**: You're currently viewing a feature designed for Statsig Cloud users. Warehouse Native customers typically have multiple datasets that uniquely affect how they define active users. Read about [Retention metrics in Warehouse Native](/statsig-warehouse-native/metrics/retention).
## Notation and Conventions
* It's common to denote the first day a (new) user was active as Day Zero (D0), and the subsequent days as D1, D2, D3... etc.
* A weekly active user is someone who has been active within the last 7 days (0-6 days). This includes users who were active on each of the 7 days, and users who have only been active on a single day. The same definition applies to a monthly active user.
* A user with a single session that spans midnight with qualifying events at 11:59p and 12:01a will qualify a user as being a daily active user on both days.
* We reserve the right to limit tracking to 100M unique IDs per unit type for 1 year.
## Default User Accounting Metrics in Statsig
### General User Metrics
| **Metric Name** | **Type** | **Description** |
| -------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `daily_active_user` | Count | Users who were active on a given calendar day (DAU). |
| `weekly_active_user` | Count | Users who were active at least once in the past 7 days (WAU). |
| `monthly_active_user` | Count | Users who were active at least once in the past 28 days (MAU). |
| `new_dau` | Count | Users who became active for the first time on a specific day. |
| `new_wau` | Count | Users who became active for the first time within the last 7 days. |
| `new_mau_28d` | Count | Users who became active for the first time within the last 28 days. |
| `daily_user_stickiness` | Stickiness (Rolling) | Fraction of the prior day's users who are active on the next day. Rolling day-to-day repeat engagement (**not** DAU/MAU or DAU/WAU). |
| `weekly_user_stickiness` | Stickiness (Rolling) | Fraction of the previous week's users who have been active within the last 7 days. This metric tracks rolling week-over-week repeat engagement (**not** WAU/MAU). The previous week is defined as 8-14 days before the metric date. |
| `monthly_user_stickiness` | Stickiness (Rolling) | Fraction of the previous month's users who have been active within the last 28 days. This metric tracks rolling month-over-month repeat engagement (**not** DAU/MAU). The previous month is defined as 29-56 days before the metric date. |
| `d1_retention_rate` | Retention (Rolling) | % of new users from 1 day ago who were active at least once today. Rolling Day 2 window retention. |
| `WAU @ D14 Retention Rate` | Retention (Rolling) | % of new users from 13 days ago who were active at least once in days 8–14. Rolling Week 2 window retention. |
| `MAU @ D56 Retention Rate` | Retention (Rolling) | % of new users from 56 days ago who were active at least once during days 29–56. Rolling Month 2 retention. |
| `L7` | L-ness | Average number of days a user was active in the last 7 days (value range: 0–7). |
| `L14` | L-ness | Average number of days a user was active in the last 14 days (value range: 0–14). |
| `L28` | L-ness | Average number of days a user was active in the last 28 days (value range: 0–28). |
These user metrics can be very useful in understanding the long-term behavior of your users. However, several of these metrics do not behave well as daily experimentation metrics. This is because metrics like L7 are highly correlated across days. For example, a user who is L7 = 7 on a given day can either be L7 = 6 or L7 = 7 the following day. This is not a true daily independent variable. Metrics like this can be more likely to trigger false positive and false negative results. This generally applies to stickiness and L-ness metrics.
## Customizing the DAU Definition
You can customize the definition of DAU within the Statsig Console and specify or exclude a set of Statsig and custom events. You can find this in the Project Settings. If you have privileges, you can edit this.
This is an Enterprise feature, please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
Verified metrics are a way to identify metrics that are curated by your company and known to be trustworthy. When users set up experiments and search for metrics, they'll see a verified icon next to verified metrics.
Group analytics is not a paid add-on at Statsig and is included at no-extra cost for all tiers.
### Step 4: Define the Conversion Window
Once you have defined your funnel, you can limit your analysis to Users (or other Unit IDs) that converted within a specified time frame. Users who start the funnel but do not convert within this time frame will be count as dropped off.
### Step 5: Drilldown
To better understand how conversion varies between different groups of users, you leverage the **Group By** feature to split out funnels by properties, experiment groups, or feature flag groups. To this, click the **"+"** to the right of "Group By" and select the property, experiment, or feature flag you would like to split out the funnel conversion analysis by.
## Advanced Funnel Analysis
### Ordered or Unordered Funnels
In general, the power of funnels lies in understanding whether or not users completed a specific set of events in a specific order. This is the most common scenario, and you can achieve this by toggling "Ordered" on. This is the default.
Ordered funnels require that a user completes the selected events in the specified order to be counted as converted. The user may still perform other events between the specified events, including events in the funnel, and still be counted as converted. For example, if an ordered funnel is defined with events A, B, C, and D, the following sequence will count as converted: A→B→B→A→C→D.
Sometimes, you just want to know whether a user has completed all a given set of events, regardless of the order they completed them in. You can achieve this by toggling "Ordered" off in the advanced settings. Unordered funnels only require that the user completes the specified events within the given time range to be counted as converted.
### Unique Users (or Unit ID) vs Total Conversions
You can choose whether your funnel analysis is defined by the total number of conversion that occur, or the number of unique users who convert. The default is Unique Users.
### Daily Aggregation
When toggled on, this calculates funnel conversions per calendar day. A given unit with funnel conversions on multiple days is counted as multiple conversions. This is toggled on by default.
## Interpreting your User Funnel
### Conversion rate vs. Number of Conversions
At the top right of the funnel chart, you'll see the Conversion Rate vs. Conversions selector. This selector allows you to switch between viewing the y-axis of your funnel as a conversion rate or the number of conversions. This feature is particularly powerful when used in conjunction with a group by. Toggling between conversion rate and number of conversions, you can see both the relative and absolute scales in conversions across different user groups.
### Conversion Summary and Table
Under each funnel step, you'll see a quick summary that helps demystify your funnel data. Specifically, these metrics tell you:
* The percentage and number of units that have converted relative to the first step of the funnel
* The percentage and number of units that have dropped off, again this number is relative to the first step of the funnel
* The average time it takes for each user to convert
Next, in the conversion table, you'll find the percentage and number of units that have converted relative to the first step of the funnel and relative to the previous step. Again, this feature is particularly useful when grouping by a certain property in which you want to compare conversions between user groups.
Conversion Drivers require a Pro plan subscription or Enterprise plan with the Advanced Analytics package.
# Lifecycle
Source: https://docs.statsig.com/product-analytics/lifecycle
Use Statsig lifecycle analysis to understand how users start, return, remain, and churn over time so you can target the right cohorts for growth experiments.
## Overview
Lifecycle charts in Metrics Explorer help you understand how usage changes over time by classifying your unique units (for example user\_id) within each time interval based on whether they used an event recently, returned after a gap, continued to use it, or churned.
Topline Alerts are in a limited beta. Please reach out if you would like these enabled for your Project.
Topline Alerts are available in Statsig Cloud and Statsig Warehouse Native with support available for three types of Topline Alerts:
| Alert Condition Type | When to Use | Example |
| -------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- |
| **Threshold** | Use when you want to stay above or below a fixed number. | “Alert me when P90 latency spikes above 15 seconds.” |
| **Change** | Use when the absolute size of the change matters. | “Alert me when hourly P90 latency increases by 10 seconds.” |
| **Change (%)** | Use when the relative size of the change matters more than raw numbers. | “Alert me when hourly P90 latency increases by 50%.” |
## Creating a Topline Alert
Go to Analytics → Topline Alerts in the product menu.
Click +Create and give the new alert a name.
Pick the data you want to monitor.
On Statsig Warehouse Native: Select a Metric Source, filter, and group by your desired dimensions.On Statsig Cloud: Select the event, aggregation, filters, and group-by conditions for this alert.
We're setting up an alert to monitor P90 latency for mex\_query events, filtering out internal employee queries and grouping by the hadGroupBy dimension.
The preview shows how your metric is trending with the current setup. Confirm values look correct, or open the metric in Metrics Explorer for deeper analysis.
The preview updates along with each change. Define the:
Condition type (threshold, change, change %)
Directionality
Alert and Warn valuesEvaluation window
On Warehouse Native: Define the evaluation frequency, lookback, and max delay—they directly influence warehouse compute costs.
Notifications go to email, the Statsig Console, and Slack (if connected). Project-wide defaults live in Settings.
Draft a clear, actionable message subscribers receive when the alert fires.
Add subscribers.
Set alert priority.
Configure re-notification rules if alerts should resend while conditions hold.
Once saved, triggered alerts appear at the top of the page. From here you can:
View samples of the event.
Open the trend in Metrics Explorer .
Mute the alert temporarily if it is noisy or already under investigation.
## Diagnostics
Head to the Diagnostics tab to review alert history, inspect samples, jump into Metrics Explorer, or mute noisy alerts.
Release Pipeline is currently only supported in Statsig's [Server Core SDKs](https://www.statsig.com/blog/introducing-statsig-server-core-v0-1-0). Legacy SDKs will continue to work but will not get the full features of release pipelines.
Follow these tutorials to begin implementing Release Pipelines:
* [Create and Manage Release Pipelines](/release-pipeline/create-and-manage)
* [Trigger a Release Pipeline](/release-pipeline/trigger)
* [Manage an Ongoing Release Pipeline](/release-pipeline/actions)
## Current Limitations
* Experiments are not supported in release pipeline
* Resalt/Disable/Delete/Archive/Launch actions won’t trigger a release pipeline
* [Scheduled rollouts](/feature-flags/scheduled-rollouts) are not supported to work in conjunction with release pipeline
# Trigger a Release Pipeline
Source: https://docs.statsig.com/release-pipeline/trigger
Attach Statsig Release Pipelines to feature gates and triggers to start controlled rollouts automatically when conditions or approvals are met.
A Release Pipeline is activated when you make changes to a feature gate or dynamic config that has a pipeline attached to it.
## Attaching a Pipeline
Before triggering a release, you must first attach a pipeline to your feature gate or dynamic config. The Statsig console offers two methods for attaching a Release Pipeline.
### During Feature Creation
You can select a Release Pipeline directly in the creation modal when setting up a new feature gate or dynamic config:
After initialization, both Client and Server SDKs evaluate experiments/gates *without a network request*, and typically in less than 1ms. Checks in the Statsig SDKs are designed to be very efficient.
## Conceptual Differences:
* Data Privacy: The *Server* SDK is presumed to be a secure, multi-user environment, so Server SDKs have access to the full ruleset describing each experiment and gate. Client SDKs fetch only the value for a single user, avoiding exposing the definition of your configurations.
| | Server | Client |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Privacy | Your servers are presumed to be a secure, multi-user environment, so Server SDKs have access to the definition of all configurations in your project | All evaluations are precomputed on Statsig servers and sent down to you client applications. Names are obfuscated, but a savvy user may be able to glean information from the raw response |
| Evaluation Performance | Evaluations are done real-time, without a network request. Very complex configurations can take longer to compute, but in practice, this is rarely an issue. | As all evaluation is precomputed, gate and experiment checks are effectively a dictionary lookup with some computation used for creating and flushing exposure events |
| Initialization Performance | The SDK will make an upfront request for configuration files, then continually poll for any changes to your configurations, updating its internal state when a change is detected | Client SDKs download configurations when you initialize, before which, the SDK may not have usable values. The values aren't updated mid-session unless you explicitly call updateUser. Additional options are available for performant initialization, see [Initializing](/client/concepts/initialize) |
| Users | Server SDKs are designed to run against multiple users, and all SDK methods require a user object for evaluation/logging | Client SDKs are designed to be run with one user at a time. All evaluations are loaded once up front during initialization, and every event logged uses that user object |
| Infrastructure | Server SDKs require you to host your own backend services | Client SDKs run entirely on the client and utilize Statsig's servers |
## Usage Differences:
| | Server | Client |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Initializing | Requires only a secret key, downloads the entire ruleset and syncs it in the background | Requires a client key and a user object. Before/during initialization, the SDK will attempt to fallback to cached values. |
| Checking an Experiment | Requires a user object which is evaluated locally (without a network request) against a ruleset persisted in memory | Does not require a user object, uses a dictionary lookup for values fetched during initialize() |
| User Identifiers | Pass any and all useful user identifiers | Pass any useful identifiers, the SDK also generates a "StableID", Statsig's anonymous ID you can use to experiment on a user per-device |
| Logging Events | Requires a user object | Does not require a user object. Note, there is some risk of adblocking log events on client SDKs, which can be minimized by setting up a [Custom Proxy](../custom_proxy) |
| Flushing Events | Batched and flushed by the SDK every 60 seconds | Batched and flushed by the SDK every 10 seconds |
| Updating Configurations | Poll Statsig servers for updates every 10 seconds by default (configurable), Streaming possible with some Server SDKs and the [Statsig Forward Proxy](/server/concepts/forward_proxy) | Configuration persists until next `initialize` or `updateUser` call, recommended to call `initialize` at the start of each user session |
## Difference in initialize/update logic:
**Client SDKs:**
* Configuration persists until next `initialize` or `updateUser` call
* Recommended to call `initialize` at the start of each user session
Enable **Show non-production logs** in the diagnostics view to surface checks coming from test keys and development builds.
### Logging Levels and Expected Information
Statsig SDKs emit runtime logs across four verbosity levels:
* `Debug` – deep tracing meant for onboarding or issue triage.
* Missing gate/config warnings when a definition is unavailable.
* Step-by-step messages that follow SDK initialization and evaluations.
* `Info` – healthy lifecycle events for day-to-day operation.
* Initialization summaries with source and SDK version details.
* Notifications when the configuration store is populated.
* `Warning` – recoverable issues that might affect functionality.
* Non-critical errors automatically handled by the SDK.
* gRPC reconnection attempts or similar transient network events.
* `Error` – critical failures that block expected behavior.
* Initialization timeouts or outright failures.
* Fallback notices that indicate gRPC is unavailable or misconfigured.
## Evaluation Details
Click any exposure in the log stream to drill into the precise rule, user attributes, evaluation reason, SDK metadata, and server timestamps. That detail is often enough to pinpoint why a user received a specific value.
#### Data Source
| Source | Description | Type | Debugging Suggestions |
| ------------------------------------------------ | ----------------------------------------------------------------- | ------- | ------------------------------------------------------------ |
| `Network` | Values fetched during initialization from Statsig servers. | Normal | — |
| `Bootstrap` | Supplied during bootstrap (often from a server SDK). | Normal | — |
| `Prefetch` | Loaded via the `prefetchUsers` API (JS only). | Normal | — |
| `NetworkNotModified` | Network request succeeded but cached values were already current. | Normal | — |
| `Sticky` (legacy) | Persisted from a sticky evaluation. | Normal | — |
| `LocalOverride` (legacy) | Set locally via override APIs. | Normal | — |
| `Cache` | Served from local cache because network values were unavailable. | Warning | Ensure `initialize()` has completed before checks run. |
| `InvalidBootstrap` / `BootstrapPartialUserMatch` | Bootstrap values were generated for a different user profile. | Error | See [Fixing InvalidBootstrap](#invalid-bootstrap). |
| `BootstrapStableIDMismatch` | StableID differed between bootstrap and runtime user. | Error | See [BootstrapStableIDMismatch](#bootstrapstableidmismatch). |
| `Error` | A generic evaluation failure that was logged to Statsig. | Error | Ask for help in [Slack](https://statsig.com/slack). |
| `Error:NoClient` (JS) | No Statsig client was found in context. | Error | Wrap checks in `` or equivalent. |
| `Unrecognized` (legacy) | The definition was missing from the initialize payload. | Error | Confirm the config exists and the correct API key is used. |
| `NoValues` | Initialization ran but failed to retrieve values. | Error | Verify client key and network connectivity. |
| `Loading` | Initialization is still in progress. | Error | Await `initializeAsync()` or guard checks until ready. |
| `Uninitialized` | Initialization never started. | Error | Call `initializeAsync()`/`initializeSync()` explicitly. |
| `UAParserNotLoaded` | UA parsing was disabled while targeting relies on it. | Error | Remove UA-based targeting or re-enable parsing. |
| `CountryLookupNotLoaded` | Country lookups were disabled while targeting relies on them. | Error | Avoid IP-based targeting or re-enable lookups. |
#### Reason (new SDKs only)
| Reason | Description | Type | Debugging Suggestions |
| --------------- | ----------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `Recognized` | The definition was present and matched the current values. | Normal | — |
| `Sticky` | Result persisted because `keepDeviceValue` was set. | Normal | — |
| `LocalOverride` | Value came from a developer override. | Normal | — |
| `Unrecognized` | Definition missing from the payload. | Error | Confirm targeting and [Target Apps](/sdk-keys/target-apps). |
| `Filtered` | Definition filtered from `/initialize` because the default value was `false`. | Error | Check [client bootstrapping](/client/concepts/initialize#bootstrapping-overview) or targeting. |
#### Data Source
| Source | Description | Type | Debugging Suggestions |
| ------------------------ | ------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `Network` | Configurations loaded from Statsig servers at initialization. | Normal | — |
| `Bootstrap` | Server SDK bootstrapped with precomputed values. | Normal | — |
| `DataAdapter` | Values retrieved from a data adapter or external store. | Normal | Review your [data adapter setup](/server/concepts/data_store#dataadapter-or-datastore). |
| `LocalOverride` (legacy) | Value supplied via server-side override APIs. | Normal | — |
| `StatsigNetwork` | Proxy/streaming fell back to Statsig APIs directly. | Fallback | Revisit your [proxy configuration](/server/concepts/forward_proxy/). |
| `Uninitialized` | SDK has not completed initialization. | Error | Ensure initialization succeeds before evaluations. |
| `Unrecognized` (legacy) | Definition missing from the cached payload. | Error | Confirm configuration exists and the API key is correct. |
#### Reason (new SDKs only)
| Reason | Description | Type | Debugging Suggestions |
| --------------- | ------------------------------------------------ | ------ | -------------------------------------------------------- |
| `LocalOverride` | Result supplied by a developer override. | Normal | — |
| *None* | Successful evaluation with the expected payload. | Normal | — |
| `Unrecognized` | Definition missing from the payload. | Error | Confirm configuration exists and the API key is correct. |
| `Unsupported` | SDK lacks support for a condition/operator. | Error | Upgrade to the latest SDK version. |
| `Error` | Generic evaluation failure captured by the SDK. | Error | Ask for help in [Slack](https://statsig.com/slack). |
### Evaluation Times
Evaluation timestamps reveal whether an SDK is serving fresh definitions. An up-to-date LCUT (Last Config Updated Time) indicates the SDK has the latest changes. If LCUT lags far behind, users may be seeing stale values—either because a browser tab stayed open or because a server integration is unable to sync.
| Time Field | Description | SDKs |
| ------------ | ----------------------------------------------------------- | ---------------------------------------- |
| `LCUT` | Time of the most recent config change reflected in the SDK. | JavaScript (incl. React & RN), iOS, Dart |
| `receivedAt` | Timestamp when the client obtained the current values. | JavaScript (incl. React & RN), iOS, Dart |
| Time Field | Description | SDKs |
| ---------------- | ------------------------------------------------------- | --------------------------- |
| `initTime` | LCUT captured when the server SDK initialized. | All server SDKs except Rust |
| `configSyncTime` | Latest LCUT received from the network or data adapter. | All server SDKs except Rust |
| `serverTime` | Current server clock time when the evaluation was made. | All server SDKs except Rust |
### Mocking Statsig / Local Mode
Use the following tools to validate code paths without hitting the network:
* **Local mode:** Set `localMode` to `true` so the SDK skips network calls and returns default values—ideal for tests and offline environments.
* **Override APIs:** Call `overrideGate` and `overrideConfig` to force specific values for an individual user or globally.
Combine both techniques to exercise each branch of your application safely before shipping.
### Client SDK Debugger
Inspect the exact values a client SDK is using by opening the Client SDK Debugger. It exposes the active user object and every gate/config tied to that client.
* **JavaScript / React:** Use the [Chrome extension](https://github.com/statsig-io/statsig-sdk-debugger-chrome-extension).
* **iOS:** Call `Statsig.openDebugView()` in [v1.26.0](https://github.com/statsig-io/statsig-kit/releases/tag/v1.26.0) or later.
* **Android:** Call `Statsig.openDebugView()` in [v4.29.0](https://github.com/statsig-io/android-sdk/releases/tag/4.29.0) or later.
Accounts that sign in to the Statsig console via Google SSO are currently unsupported by the Chrome extension.
| Landing | Gates List | Gate Details | Experiment Details |
| ------------------------------------------ | ---------------------------------------- | ------------------------------------------ | ------------------------------------------------ |
|
Python SDK v0.45.0+ introduces tunables that help handle high event volume without drops.
The SDK batches events and retries failures in the background. When throughput spikes, adjust these options to reduce the chance of dropped events:
* **`eventQueueSize`** – Number of events flushed per batch. Larger batches increase throughput but use more memory; keep the value under \~3000 to avoid oversized payloads.
* **`retryQueueSize`** – Number of batches kept for retrying. The default is 10; raise it to retain more data at the cost of memory.
Tune both settings to match your traffic profile and keep pipelines healthy.
# SDK Overview
Source: https://docs.statsig.com/sdks/getting-started
Get started with a Statsig SDK by choosing your platform, installing the package, initializing with your API key, and evaluating your first gate.
Statsig's SDKs are the in-code tool you'll use to show experiment variants, flag your features, and log your key business metrics. Statsig's SDKs:
* **Abstract the complexity away:** we handle caching, retry mechanisms, networking, etc.
* **Encourage best practice:** built around parameters & language-specific best practice
* **Broad deployment support:** 30+ SDKs across clients, servers, the edge, and more.
***
## When Will I Use the Statsig SDKs?
### 1. **Targeting & Assignment**
Decide in-code who sees new features and experiment variants. Target based on any **user attributes** (e.g., location, device type) or **environment-level attributes**, letting you fine-tune rollouts and experiment enrollment.
### 2. **Logging Events**
Log your key business metrics to power experiment & product analytics. Your events are piped into Statsig without any extra effort. For web-based platforms (e.g., JavaScript, React), Statsig also supports **[Autocaptured Events](/webanalytics/overview)**.
***
## Choosing the Right SDK: Client vs. Server
Statsig offers both **client-side** and **server-side** SDKs, each suited to different use cases:
* **Client-Side SDKs**: Designed for user-facing applications where events are logged directly from the browser or mobile app. These SDKs work in real-time, providing instant feedback on user behavior.
* **Server-Side SDKs**: Ideal for backend services, allowing you to control experiments, feature flags, and log server-side events. Server-side SDKs offer more control, especially for use cases involving system-level actions or business logic.
For a detailed comparison, refer to the [Client vs Server SDK Overview](/sdks/client-vs-server).
Additionally, for frameworks like **Next.js** that bridge client and server-side logic, we offer guides like the [Next.js SDK](/client/Next) to help you integrate.
***
## Explore SDKs
Statsig offers SDKs for a wide variety of platforms to suit any codebase or deployment preference:
### Client SDKs
Browser JavaScript
Client-Side React
Bare React Native SDK
Next.js SSR, SSG & Client-Side
Angular bindings for Javascript SDK
iOS, MacOS, tvOS SDK
Android Kotlin/Java SDK
Client SDK for .NET framework
Roku Brightscript SDK
Unity game engine SDK
Flutter/Dart Mobile App SDK
C++ client-side SDK
### Server Side SDKs
Node.js server SDK
Java server SDK
Python server SDK
Go server SDK
Ruby server SDK
.NET server SDK
PHP server SDK
Rust server SDK
C++ server SDK
***
## Next Steps: Installing Your SDK
1. **Select Your SDK**: Choose the client or server SDK that fits your platform from the lists above.
2. **Follow the Installation Guide**: Each SDK has an installation guide that walks you through the setup, ensuring a smooth integration with your app.
3. **Start Experimenting**: Once integrated, you can begin setting up feature flags, running experiments, and logging events for analysis.
If you run into any questions or need help with installation, feel free to reach out via our [Slack Community](https://statsig.com/slack).
# How Evaluation Works
Source: https://docs.statsig.com/sdks/how-evaluation-works
How Statsig SDKs evaluate feature gates, experiments, and dynamic configs, including rule ordering, conditions, and exposure logging behavior.
## Evaluation's importance
The essential function of the Statsig SDKs is reliable, consistent, incredibly performant allocation of users to the correct bucket in your experiment or feature gate. Understanding how we accomplish this can help you answer questions like:
* Why do I have to pass every user attribute, every time?
* Why do I have to wait for initialization to complete?
* When do you decide each users' bucket?
## How Evaluation Works
Evaluation in Statsig is deterministic. Given the same user object and the same state of the experiment or feature gate, Statsig always returns the same result, even when evaluated on different platforms (client or server). Here's how it works:
1. **Salt Creation**: Each experiment or feature gate rule generates a unique salt.
2. **Hashing**: The user identifier (e.g., userId, organizationId) is passed through a SHA256 hashing function, combined with the salt, which produces a large integer.
3. **Bucket Assignment**: The large integer is then subjected to a modulus operation with 10000 (or 1000 for layers), assigning the user to a bucket.
4. **Bucket Determination**: The result defines the specific bucket out of 10000 (or 1000 for layers) where the user is placed.
This process ensures a randomized but deterministic bucketing of users across different experiments or feature gates. The unique salt per-experiment or feature gate rule ensures that the same user can be assigned to different buckets in different experiments. This also means that if you rollout a feature gate rule to 50% - then back to 0% - then back to 50%, the same 50% of users will be re-exposed, **so long as you reuse the same rule** - and not create a new one. See [here](/faq/#when-i-change-the-rollout-percentage-of-a-rule-on-a-feature-gate-will-users-who-passed-continue-to-pass).
For more details, check our open-source SDKs [here](https://github.com/statsig-io/node-js-server-sdk/blob/main/src/Evaluator.ts).
This is not generally recommended, but for advanced use cases - e.g. a series of related experiments that needs to reuse the control and test buckets, we now expose the ability to copy and set the salts used for deterministic hashing. This is meant to be used with care and is only available to Project Administrators. It is available in the Overflow (...) menu in Experiments.
## Evaluation Order
When evaluating gates, experiments, and layers, the SDK iterates through a list of rules generated by the server. Rules are evaluated sequentially and the first matching rule determines the result. Overrides always take precedence because they appear first in the rule list.
Each step uses the hash-based bucketing described above. Layer allocation and group assignment use different salts, so a user's position in the layer is independent of their group assignment within the experiment.
### Experiments
When an experiment is evaluated (you call `getExperiment`), it follows this evaluation order:
1. **ID overrides** — Specific user/unit IDs mapped to a group
2. **Conditional overrides** — Segment or gate-based overrides, evaluated in order
3. **Layer holdouts** — If the experiment is in a layer, layer-level holdout gates are checked
4. **Holdout gates** — Experiment-level holdout gates; users in a holdout receive default values
5. **Experiment exclusion** — Mutual exclusion segments that prevent users from being in multiple experiments
6. **Start status** — If the experiment is not started, users receive default values (with optional non-production environment exceptions)
7. **Layer allocation** — For experiments in a layer, the user's bucket (based on the layer's universe salt) must fall within the experiment's allocated segments. This is checked **before** targeting.
8. **Targeting gate** — Users who fail the targeting gate receive default values. This is checked **after** layer allocation.
9. **Group assignment** — The user's bucket (based on the experiment salt) determines which group they fall into. Groups are cumulative ranges across 1000 buckets.
### Layers
When a layer is evaluated (you call `getLayer`), it follows this evaluation order:
1. **Override rules** — ID overrides from all experiments in the layer
2. **Layer holdout gates** — Holdout gates attached to the layer
3. **Experiment allocation** — Each experiment in the layer has a `configDelegate` rule. The user's bucket determines which experiment they are delegated to.
4. **Delegated experiment evaluation** — Once delegated, the experiment's own evaluation runs (start status, targeting gate, group bucketing as described above)
If no experiment allocation rule matches, the user receives the layer's default values.
### Holdouts
Holdout gates evaluate in this order:
1. **Experiment exclusion** — Exclusion segments (if applicable)
2. **ID overrides** — Specific user/unit IDs
3. **Population targeting gate** — If the holdout has a targeting gate, users who fail it are not held out
4. **Holdout percentage** — The pass percentage on the holdout rule determines the holdout rate
### Gates
When a feature gate is evaluated (you call `checkGate`), it follows this evaluation order:
1. **ID overrides** — Specific user/unit IDs mapped to pass/fail
2. **Conditional overrides** — Segment or gate-based overrides
3. **Holdout rules** — If the gate has holdouts attached
4. **Rules** — The gate's targeting rules, evaluated in the order they appear in the console. Each rule has its own conditions and pass percentage.
## When Evaluation Happens
Evaluation happens when the gate or experiment is checked on Server SDKs. To be able to do this, Server SDKs hold the entire ruleset of your project in memory - a representation of each gate or experiment in JSON. On client SDKs, we evaluate all of the gates/experiments when you call initialize - on our servers.
All of the above logic holds true for both SDKs. In both, the user's assignment bucket is not sent to Statsig until you call the getExperiment/checkGate method in the SDK.
## What this means:
* **Performant Evaluation:** no evaluations require a network request, and we focus on evaluation performance, meaning that checks take \<1ms after evaluation.
* **The SDKs don't "remember" user attributes, or previous evaluations:** we rely on you to pass all of the necessary user attributes consistently - and we promise if you do, we'll provide the same value.
A common assumption is that Statsig tracks of a list of all ids and what group they were assigned to for experiments/gates. While our data pipelines track users exposed to each variant to compute experiment results, we do not cache previous evaluations and maintain distributed evaluation state across client and server SDKs. That won't scale - we've even talked to customers doing this in the past, and were paying more for Redis to maintain that state than they ended up paying for Statsig.
* **Server SDKs can handle multiple users:** because they hold the ruleset in memory, Server SDKs can evaluate any user. Without a network request. This means you'll have to pass a user object into the getExperiment method on Server SDKs, whereas on client SDKs you pass it into initialize().
* **We ensure each user receives the same bucket:** our ID-based hashing assignment guarantees consistency. If you make a change in console that could affect user bucketing on an experiment, we'll provide warning.
## Evaluation of null/empty unitIDs
Note, we do not apply any filtering/ business logic before we assign an individual userID. This means that even a null or empty unitID will be bucketed depending on the salt.
# Identify Users
Source: https://docs.statsig.com/sdks/identify-users
How to identify users in Statsig SDKs using user IDs, custom IDs, and user properties so feature gates and experiments evaluate consistently.
## Why identify users?
When you run an experiment, rollout a feature, or log events, Statsig needs to know who the user is to determine:
* Targeting: whether a feature gate should pass or fail for a given user
* Experiment bucketing: which group a user belongs to
* Analytics: How many unique users triggered an event
This is achieved by passing a User Object to Statsig SDKs. User Object is also needed for experiment analysis - users are allocated to the test or control group by an ID, and the Statsig stats engine uses the same ID on the users' events to determine the difference in metrics between test and control.
## Basic User Object
Start by defining a basic user object:
```jsx Basic User Object theme={null}
{
"userID": "u_123", // required for most setups
"email": "user@example.com" // optional
}
```
Later, you can layer in more details when you need finer targeting. To learn more about enriching User Object with more attributes, scroll down to [Enriched Attributes](#enriched-attributes).
## Identifying users in Client SDKs
In client SDKs, the SDK is "initialized" for a single User Object at any one time. If you try to call a method like checkGate or getExperiment before your SDK is initialized, you won't get expected results - and you'll see warnings in the Statsig Console when you look at the diagnostics tab of any gate or experiment. Initialization requires a network request, which you fire by calling the `initialize()` method, or in React, `useClientAsyncInit()`.
This means that in client apps with asynchronous logic, you'll want to wait for initialization to complete before you check a gate. For example, in React:
```jsx React Example theme={null}
export function App() {
const { client, isLoading } = useClientAsyncInit(
YOUR_CLIENT_KEY,
user={ userID: "u_123"} // user object
);
if (isLoading) {
return Loading...
;
}
return (
);
}
```
This also means that if you initialize with a certain user object, and the user object changes (e.g., the user logs in and now has a `userID`) then you'll need to call the `updateUser` method, which calls to the Statsig Server to refresh the values. For example, in React:
```jsx Update User theme={null}
const { user, updateUserSync } = useStatsigUser();
return
Current User: { user.userID }
updateUserSync({userID: 'some-other-user'})}>
Update User
;
```
If you don't update the user before checking gates or experiments, they'll evaluate using the previous user object you initialized with, which can lead to unexpected behavior.
Any attribute added to the user object is targetable in the Statsig console - if you'd like to target users based on their `email`, `companyID`, or other attributes - add them to your User object.
## Identifying users in Server SDKs
In Server SDKs, you pass a User Object with each evaluation or event call such as logEvent, checkGate or getFeatureGate. The Server SDK holds the necessary rules in memory to enable correct evaluation. Every time you call one of these methods - you should pass all of the attributes needed to evaluate your gate or experiment. The Statsig SDKs don't "remember" or enrich previous attributes seen.
Example (Node.js)
```jsx Node.js Example theme={null}
import { Statsig } from "statsig-node";
await Statsig.initialize("");
const user = { userID: "u_123", custom: { plan: "premium" } };
const gate = await Statsig.checkGate(user, "beta_feature");
if (gate) {
console.log("Gate passed");
}
```
## Enriched attributes
Statsig attempts to enrich the user object with useful attributes to give you more targeting power. Examples of what Statsig can enrich for you:
* `stableID`: an anonymous identifier which identifies a unique device on client SDKs
* `country`: derived from IP or device locale
* `appVersion`: pulled from mobile SDKs
* `browser` / `OS`: captured from user agent
* and more...
To learn about all available fields — including `custom` attributes, `customIDs`, and `privateAttributes` — see the [StatsigUser object](/concepts/user) docs.
# Get started with the Statsig SDK
Source: https://docs.statsig.com/sdks/quickstart
Get data flowing into Statsig with only a few lines of code using a Statsig SDK to log events, evaluate feature gates, and run your first experiment.
If you're looking for a more detailed guide, check out the [SDK Overview](/sdks/getting-started) or read about choosing between [client or server SDKs](/sdks/client-vs-server).
```bash theme={null}
npm install @statsig/react-bindings
```
Next, update your app's default function (Usually App.tsx or Layout.tsx) so that the StatsigProvider wraps around all child components.
```tsx theme={null}
import { StatsigProvider } from "@statsig/react-bindings"; // [!code ++]
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
Loading...}> // [!code ++]
{children}
// [!code ++]
);
}
```
This example assumes you're using client-side React, if you're Server-Side Rendering, you'd be better served by our [Next.js docs](/client/Next).
Create a client API key in the [Statsig console Settings](https://console.statsig.com/api_keys). Copy and paste it to replace `` in the code snippet from the previous step.
First, create a gate on the [Feature Gates page](https://console.statsig.com/gates) in console, then check it in-code:
```jsx theme={null}
const { client } = useStatsigClient();
return (
Gate is {client.checkGate('check_user') ? 'passing' : 'failing'}.
);
```
First, create an Experiment on the [Experiments page](https://console.statsig.com/experiments) in console
```jsx theme={null}
const { client } = useStatsigClient();
const experiment = client.getExperiment('my_experiment_name');
return (
Headline Parameter: {experiment.get('my_experiment_parameter_name', 'fallback_value')}.
);
```
You can use Events to power metrics in your experiment or gates. Events don't need to be set up in console first, just add to your code:
```jsx theme={null}
const { client } = useStatsigClient();
return client.logEvent("button_click")}>Click Me
```
## Next steps
Congratulations! You've successfully set up the Statsig SDK in React. Continue on to the tutorials, or jump in to the full [Next.js](/client/Next) or [React](/client/React) SDK libraries.
In the `` section of your website, paste the following code snippet:
```html theme={null}
```
Create a client API key in the [Statsig console Settings](https://console.statsig.com/api_keys). Copy and paste it to replace `` in the code snippet from the previous step.
First, create a gate on the [Feature Gates page](https://console.statsig.com/gates) in console, then check it in-code:
```jsx theme={null}
window.Statsig.instance().checkGate("my_feature_gate_name");
```
You'll want to wait for the SDK to initialize before checking a gate to ensure it has fresh values, one way to accomplish this is waiting for the ["values\_updated"](/client/javascript-sdk#client-event-emitter) event.
First, create an Experiment on the [Experiments page](https://console.statsig.com/experiments) in console
```jsx theme={null}
window.Statsig.instance().getExperiment("my_experiment_name").get('my_experiment_parameter_name');
```
You'll want to wait for the SDK to initialize before getting an experiment to ensure it has fresh values, one way to accomplish this is waiting for the ["values\_updated"](/client/javascript-sdk#client-event-emitter) event.
You can use Events to power metrics in your experiment or gates. Events don't need to be set up in console first, just add to your code:
```jsx theme={null}
window.Statsig.instance().logEvent("my_checkout_event_name", "event_value_item_1234", {"event_metadata": "my_metadata"})
```
## Next steps
Congratulations! You've set up the Statsig JavaScript snippet. You can now start:
* Start [recording events](/webanalytics/overview)
* Watch [session replays](/session-replay/overview)
* Run [experiments](/experiments/overview)
* Use [feature flags](/feature-flags/overview)
See the [Javascript SDK reference](/client/javascript-sdk) for more info.
```shell theme={null}
pip install statsig-python-core
```
```python theme={null}
from statsig_python_core import Statsig, StatsigOptions
options = StatsigOptions()
options.environment = "development"
statsig = Statsig("", options)
statsig.initialize().wait()
statsig.shutdown().wait()
```
Create a server secret key in the [Statsig console Settings](https://console.statsig.com/api_keys). Copy and paste it to replace `` in the code snippet from the previous step.
First, create a gate on the [Feature Gates page](https://console.statsig.com/gates) in console, then check it in-code:
```python theme={null}
user_object = StatsigUser(user_id="123", email="testuser@statsig.com") //add any number of other attributes
gate_value = statsig.check_gate(user_object, "my_feature_gate_name"):
```
First, create an Experiment on the [Experiments page](https://console.statsig.com/experiments) in console
```python theme={null}
user_object = StatsigUser(user_id="123", email="testuser@statsig.com"
my_experiment_object = statsig.get_experiment(user_object, "my_experiment_name")
my_experiment_parameter_value = my_experiment_object.get_string('my_experiment_parameter_name')
```
You can use Events to power metrics in your experiment or gates. Events don't need to be set up in console first, just add to your code:
```python theme={null}
user_object = StatsigUser(user_id="123", email="testuser@statsig.com"
statsig.log_event(
user=user_object,
event_name="my_checkout_event_name",
value="SKU_12345"
)
```
## Next steps
Congratulations! You've set up the Statsig SDK in Python. Continue on to our tutorials, or jump in to the full [Python SDK Reference.](/server-core/python-core)
```bash theme={null}
npm i @statsig/statsig-node-core
```
```jsx theme={null}
// Basic initialization
const statsig = new Statsig("");
await statsig.initialize();
// or with StatsigOptions
const options: StatsigOptions = { environment: "staging" };
const statsigWithOptions = new Statsig("secret-key", options);
await statsigWithOptions.initialize();
```
Create a server secret key in the [Statsig console Settings](https://console.statsig.com/api_keys). Copy and paste it to replace `` in the code snippet from the previous step.
First, create a gate on the [Feature Gates page](https://console.statsig.com/gates) in console, then check it in-code:
```js theme={null}
const userObject = new StatsigUser({ userID: "123", email="testuser@statsig.com" });
const is_gate_enabled = statsig.checkGate(userObject, "my_feature_gate_name"):
```
First, create an Experiment on the [Experiments page](https://console.statsig.com/experiments) in console
```js theme={null}
const userObject = new StatsigUser({ userID: "123", email="testuser@statsig.com" });
const myExperimentObject = statsig.getExperiment(userObject, "my_experiment_name")
const myExperimentParameterValue = myExperimentObject.getValue('my_experiment_parameter_name')
```
You can use Events to power metrics in your experiment or gates. Events don't need to be set up in console first, just add to your code:
```js theme={null}
userObject = StatsigUser(user_id="123", email="testuser@statsig.com"
statsig.logEvent(
userObject,
"my_checkout_event_name",
"SKU_12345" //value for the event
);
```
## Next steps
Congratulations! You've successfully set up the Statsig SDK in Node.js. Continue on to the tutorials, or jump in to the full [Node.js](/server-core/node-core) SDK library.
## Explore SDKs
Statsig offers SDKs for a wide variety of platforms to suit any codebase or deployment preference:
### Client SDKs
Browser JavaScript
Client-Side React
Bare React Native SDK
Next.js SSR, SSG & Client-Side
Angular bindings for Javascript SDK
iOS, MacOS, tvOS SDK
Android Kotlin/Java SDK
Client SDK for .NET framework
Roku Brightscript SDK
Unity game engine SDK
Flutter/Dart Mobile App SDK
C++ client-side SDK
### Server Side SDKs
Node.js server SDK
Java server SDK
Python server SDK
Go server SDK
Ruby server SDK
.NET server SDK
PHP server SDK
Rust server SDK
C++ server SDK
### Integrations
Webflow integration
Shopify integration
Segment data connector
Rudderstack connector
Hightouch integration
mParticle connector
Framer integration
Slack notifications
View more integrations
# SDK Support Policy
Source: https://docs.statsig.com/sdks/support
Statsig SDK support reference, including supported runtimes, version policies, deprecation timelines, and how to file SDK issues with the team.
To ensure the security, performance, and reliability of our SDKs, we only provide official support for SDK versions that are less than **one year old** from their release date, unless otherwise specified (some updates may require a different timeline or migration path).
## Supported Versions
* We provide support (bug reports, issue investigation, and compatibility assistance) for SDK versions released **within the past 12 months**.
* Versions older than one year are considered **unsupported**. While they may continue to function, we do not guarantee their behavior or compatibility with our backend services.
* We strongly recommend upgrading to the latest version to benefit from new features, performance improvements, and critical fixes.
## Versioning and Releases
* All SDKs follow [Semantic Versioning (SemVer)](https://semver.org/), using the format `MAJOR.MINOR.PATCH`, **unless otherwise specified**.
* **MAJOR**: breaking changes
* **MINOR**: backwards-compatible new features
* **PATCH**: backwards-compatible bug fixes
* Release notes are published in the GitHub Releases section of each SDK’s repository. These notes contain details on changes, improvements, and upgrade instructions.
## Open Source and Community Contributions
* All SDKs are open source and licensed under the [ISC License](https://opensource.org/licenses/ISC), allowing developers to freely use, modify, and distribute them.
* We welcome and encourage community contributions.
## Need Help?
For help with upgrading, reviewing release notes, or contributing, please refer to the SDK’s GitHub repository or reach out in Slack .
# Target Apps
Source: https://docs.statsig.com/sdks/target-apps
Use target apps in Statsig SDKs to scope feature gates, experiments, and dynamic configs to specific applications inside a single project.
Target Apps are an Enterprise-only feature. Reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
## Motivation
There are two main attributes you can add to SDK Keys which restrict their access to certain configs or config definitions - Environments and Target Apps. A “Target App” is a user defined abstraction tied to entities in your Statsig Project which can be linked to one or more SDK Keys.
Target apps should be things like your "Android" or "iOS" apps, or could be more restricted to specific services like "Search" and "Feed" which may span both client and server usage.
Defining and using Target Apps is a best practice when using Statsig at large scale, and has two main benefits:
* Performance: removing unused entities from the payload to your Statsig SDK integration will speed up the initialization time and reduce the amount of data that is stored in any local caches or data stores
* Security: you may not want to expose certain gates/experiments/configs to the client side, or to the client key which is easily found in your client app. Specifying a target app for your client key and ONLY linking that to client specific gates/configs/experiments hides those from prying eyes
When using target apps, first consider if you should instead use separate projects for your Statsig integrations:
* If you need to share gates/experiments/metrics across apps or services, it is recommended to use a Target App as entities are restricted within a single Statsig project.
* If your services or apps always have distinct gates/experiments/metrics, using a separate Statsig project might be a better solution.
If you have an existing Statsig project with multiple SDK integrations, Statsig will help you to bootstrap your Target Apps by suggesting existing entities to tag which have historically recorded checks from that specific SDK.
## Configuring Target Apps
### Project Setup
Start by going to **Settings** → [**Target Applications**](https://console.statsig.com/settings/apps).
When [bootstrapping](/client/concepts/initialize#2-bootstrap-initialization) a Client SDK from a Server SDK, you'll need the server SDK to have access to all of the gates/experiments/configs needed both for server and client. If you have separate target apps for client and server SDKs, you should apply both target apps to the server key you're using.
Then, to filter the boostrapping response to a specific target app, add a client key with that target app applied to the getClientInitializeResponse call.
### Debugging
To debug SDK evaluations which may be impacted by your Target App configuration, use the **Diagnostics** tab for any entity.
In this Feature Gate example, the Exposure Stream at the bottom will show the Target App associated with any checks if the SDK key used to check it has a Target App applied. If any exposures for that entity do not have a matching Target App, it will be flagged with a warning.
# User (StatsigUser) Object
Source: https://docs.statsig.com/sdks/user
Reference for the StatsigUser object used by SDKs, including fields like userID, email, country, custom properties, and private attributes.
## Introduction to the StatsigUser object
The user(StatsigUser) object is the sole input you provide to SDKs to target gates and assign users to experiments. If you'd like to target on an attribute, you'll need to add it to your user object, so assembling the data is an important part of SDK setup. **We recommend providing as much info as practical,** as every additional field can enrich your analyses and expand targeting possibilities. Statsig also infers some information about each user based on other traits (for example, we resolve IP Addresses into countries), read on for more details.
## Usage Example in Node:
```jsx Node.js Example theme={null}
//Create a user object
const user = new StatsigUser({ userID: "12345", email: "vincent@statsig.com"});
//Use it in getExperiment()
const my_experiment = statsig.getExperiment(user, "my_experiment_name") //<- any attribute you pass, you can target on
```
### I passed that attribute before - why do I need to pass it again?
If you want to see a specific user's historical attributes for analytics purposes, you can see that in the statsig console via [User Profiles](/product-analytics/users-tab).
However, you cannot use a user's historical attributes for targeting or gate/experiment evaluation at runtime. Statsig evaluates gates and experiment buckets based **only on the information you provide when you check something.** Statsig's promise of evaluating every gate or experiment in milliseconds is dependent on having all information available at request time, rather than querying previous data, or storing massive amounts of historical data in memory.
## User Attributes
All user attributes can be explicitly supplied, and some can be inferred from a user's device or connection. Supplying one will always override an inferred value.
| Key | Description | Example | Client SDK Support | Auto-infer |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------- |
| `userID` | ID representing a unique user. This ID will be used to guarantee consistency of targeting for Feature Gates and Experiments and will be used to evaluate experiment results. If `User ID` doesn't exist yet, leave this empty; a `Stable ID` persisted locally will be used for evaluations. | `your_user_id` | All | |
| `email` | Email of the user. | `marcos@statsig.com` | All | |
| `userAgent` | User agent of the browser. This will be decoded to determine the Browser and Operating System of the user's context. Will be inferred if not provided. | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.40 Safari/537.36` | Web | ✔ |
| `ip` | IP address of the user. Inferred from the request to /initialize if not provided | `192.168.1.101` | All | ✔ |
| `country` | 2-letter country code of the user. This can be supplied or inferred, and we can target based on the country code in both cases. When inferred, the country code follows ISO-3166. | `US` | All | ✔ |
| `locale` | Locale of the user. When using the Android or iOS SDK, this will be inferred if not provided. | `en_US` | Mobile | ✔ |
| `appVersion` | Version of the app the user is using. When using the Android or iOS SDK, this will be inferred if not provided. | `1.0.1` | Mobile | ✔ |
| `systemName` | When using our Android/iOS SDKs, this will be automatically assigned, but you can also provide an explicit operating system to override. | `Android` | All | ✔ |
| `systemVersion` | When using our Android/iOS SDKs, this will be automatically assigned, but you can also provide an explicit OS version to override. | `15.4` | All | ✔ |
| `browserName` | When using our Web SDK, this will be automatically assigned, but you can also provide an explicit Browser Name to override. | `Chrome` | Web | ✔ |
| `browserVersion` | When using our Web SDK, this will be automatically assigned, but you can also provide an explicit Browser Version to override. | `45.0` | Web | ✔ |
| `custom` | Dictionary that can contain key/value pairs that can be used for Feature Gate targeting. The content of this dictionary will be stored and available after targeting. | `{subscriber: "yes", ...}` | All | |
| `privateAttributes` | Dictionary that can contain key/value pairs that can be used for Feature Gate targeting. The content of this dictionary will **not** be stored after being used for targeting and will be removed from any `log_event` calls. | `{sensitive_field: "sensitive_information", ...}` | All | |
| `customIDs` | Dictionary that can contain key/value pairs used as the randomization unit ID for experiments that are set up using these IDs instead of the `User ID`. | `{account_id: "23456555", company_id: "company_xyz"}` | All | |
### How to override the Stable ID
Client SDKs generate a `stableID` for logged-out or device-level targeting. If you already manage your own durable device identifier, override the SDK-generated value before or during initialization so Statsig uses your identifier for Stable ID-based evaluations.
```tsx theme={null}
import { StatsigClient, StatsigUser } from '@statsig/js-client';
const user: StatsigUser = {
userID: 'a-user',
customIDs: {
stableID: 'my-custom-stable-id',
},
};
const client = new StatsigClient('client-sdk-key', user);
await client.initializeAsync();
```
```kotlin theme={null}
val options = StatsigOptions(overrideStableID = "my-custom-stable-id")
Statsig.initialize(app, "client-sdk-key", user, options = options)
```
```swift theme={null}
let options = StatsigOptions(overrideStableID: "my-custom-stable-id")
Statsig.initialize(sdkKey: "client-sdk-key", user: user, options: options)
```
When you override the Stable ID in a client SDK, that value is persisted locally and reused on later sessions unless local storage is cleared or the app is reinstalled.
All user attributes can be explicitly supplied, and some can be inferred from a provided IP Address or User Agent. Supplying one will always override an inferred value.
| Attributes | Description | Example | Auto Infer |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `userID` | ID representing a unique user. This ID will be used to guarantee consistency of targeting for Feature Gates and Experiments and will be used to evaluate experiment results. | `your_user_id` | |
| `email` | Email of the user | `marcos@statsig.com` | |
| `userAgent` | User agent of the browser. This will be decoded to determine the Browser and Operating System of the user's context | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.40 Safari/537.36` | |
| `ip` | IP address of the user | `192.168.1.101` | |
| `country` | 2 letter country code of the user | `US` | ✔, from IP |
| `locale` | Locale of the user | `en_US` | ✔, from IP |
| `appVersion` | Version of the app the user is using | `1.0.1` | |
| `custom` | Dictionary that can contain key/value pairs that can be used for Feature Gate targeting. The content of this dictionary will be stored and available after targeting | `{skill_level: "5", is_subscriber:"false" ...}` | |
| `privateAttributes` | Dictionary that can contain key/value pairs that can be used to evaluate feature gate conditions and segment conditions. The content of this dictionary will **not** be stored after used for targeting and will be removed from any log\_event calls | `{sensitive_field: "sensitive_information", ...}` | |
| `customIDs` | Dictionary that can contain key/value pairs used as the randomization unit ID for experiments that are set up using these IDs instead of the `User ID` | `{account_id: "23456555", company_id: "company_xyz"}` | |
### How to override "Operating System" and "Browser" explicitly
Operating system and Browser are two default targeting options on Statsig, and if you set the userAgent field, server SDKs will parse out the OS/Browser information to evaluate them. If you prefer to explicitly setup this, you can in two places: either top-level in the user object (which typing may not allow in languages), or in the "custom" object. You need to provide this information under the following keys:
* Operating System: os\_name
* OS Version: os\_version
* Browser Name: browser\_name
* Browser Version: browser\_version
As an example, you could set this either of these two ways in the user object:
```json Example theme={null}
{
"userID": "uuid",
"os_name": "Android", // top level
"custom": {
"os_name": "iOS"
}
}
```
If either of these fields is explicitly set, it will take precedence over inferring the value from the `userAgent` field.
### Have sensitive user PII data that should not be logged?
On the StatsigUser object, there is a field called privateAttributes, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in privateAttributes will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to privateAttributes on the user and that's it!
### Time-based conditions
All SDKs (both server and client-side) support unix timestamps in milliseconds to evaluate time based conditions (After time, before time). Without knowing all possible variations of DateTime formats, we have to normalize on something, so it's best to convert your DateTime field into a standard format for evaluation.
We have added support for ISO timestamps to some server SDKs.
* The `java-server` sdk, as of `v1.6.0` supports [DateTime fields in the format of `ISO_INSTANT`](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT)
* The `go` sdk, as of `v1.12.1` supports [DateTime fields in the format of `RFC3339`](https://pkg.go.dev/time#pkg-constants)
* The `python` sdk supports the usage of epoch time in seconds. using `time.time()` may include sub-second components so you should use round the value to an integer
We have added support for ISO timestamps to server SDKs supported by server core (Java, Python, PHP, Rust, Node).
* [DateTime fields in the format of `ISO_INSTANT`](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT)
* [DateTime fields in the format of `RFC3339`](https://pkg.go.dev/time#pkg-constants)
### Why is an ID always required for server SDKs?
In Server SDKs, a StatsigUser with a userID (or customID) is required for checkGate, getConfig, and getExperiment. In short, it's *always* better to pass the user ID if it's available: users will get a stable experience, and any events will be attributed to the correct users so you can accurately measure downstream metrics.
Still don't want to pass an ID? Here are our suggestions for different use cases:
1. If you plan to only use one/off feature gates, or non-percent-based rules (like countries):
While you're still losing functionality, you can pass any non-empty identifier, hard coded string, or **a random ID less than 100 if you do not have the actual user ID.** Don't pass a purely random ID - as we won't be able to dedupe your events, you'll explode your event usage, and your Statsig bill.
2. If you want to rollout a feature partially, check for regressions, then roll out to everyone: You must pass an ID in your checkGate/getConfig/getExperiment calls, as well as any logEvent calls you make. Otherwise, we're not able to attribute the events you log to the correct users who saw or didn't see your new feature, or calculate metrics correctly to help you see any regressions.
3. If you want to run an A/B experiment to decide whether to ship a new feature: You should also **pass the persistent user IDs**, for the same reason mentioned in 2, above.
4. If you want to pass a userID for the above reasons, but don't have a logged in user (e.g. you are optimizing the login flow): Set a stable identifier (we provide one in client SDKs!) as a cookie or in local storage and use that with each call to Statsig.
We hope this is helpful. If you have a use case that is not covered in these scenarios, or have any question at all, feel free to join our [Slack community](https://statsig.com/slack) and drop a question/comment there!
### Pass all IDs when you have them
A common mistake is to accidentally expose users without a userID to a user-ID based experiment. All of them will be bucketed into one group (whichever the "null" userID goes to), polluting your results. If you run experiments on multiple ID types (or you might one day), it's best to pass every identifier available.
# Adding ID Lists
Source: https://docs.statsig.com/segments/add-id-list
Create and manage ID List segments in Statsig to target specific users by their identifiers, such as user IDs, emails, or custom IDs uploaded as a list.
## Adding ID Lists
### What is an ID List?
An ID List enables you to define a reusable audience segment using user identifiers like `userID`, `stableID`, or `organizationID`.
You can manage ID Lists by manually adding/removing IDs, uploading CSVs, or replacing the entire list.
### Creating an ID List Segment
1. Navigate to the **Segments** section in the [Statsig Console](https://console.statsig.com).
2. Click **Create New Segment**.
3. Toggle the segment type from **Conditional** to **ID List**.
Large ID Lists is currently in limited beta, please contact Statsig Support to enable. Note this is not available for Free/ Pro users at this time.
# Adding Rules
Source: https://docs.statsig.com/segments/add-rule
Create rules in Statsig segments that define which users are included based on user attributes, custom properties, country, app version, and more.
## Create a rule for a segment
A rule defines the criteria for which users are included in a segment. To add a rule to a segment,
* Log into the Statsig console at [https://console.statsig.com](https://console.statsig.com)
* On the left-hand navigation panel, select **Segments**
* Select the segment where you want to add a rule
* Click the **Add New Rule** button
* Select the criteria to target a set of users. For example, select Email and the Contains any of operator, and enter the email domain of your company to target only internal employees
Cpp Core on Github
Cpp Core Working Repo
## Setup the SDK
## Installation
All core logic are written in rust, and we don't require rust environment from you, so we pre-built all binaries (attached as assets with each release).
Our CMakeLists.txt file handle all the complexity for you.
If you encounter any installation or build issue, please reach back to us!
```CMake theme={null}
FetchContent_Declare(
Statsig
GIT_REPOSITORY https://github.com/statsig-io/statsig-cpp-core.git
GIT_TAG 0.12.2-rc.1
)
FetchContent_MakeAvailable(Statsig)
target_include_directories(CppApp PRIVATE ${statsig_SOURCE_DIR}/include)
target_include_directories(CppApp PRIVATE ${statsig_SOURCE_DIR}/src)
target_link_libraries(CppApp PRIVATE Statsig)
```
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
```cpp theme={null}
#include
statsig_cpp_core::StatsigOptionsBuilder optionsBuilder;
ptionsBuilder.environment = "development";
ptionsBuilder.specs_url = api_v2 + "/download_config_specs";
optionsBuilder.log_event_url = api + "/log_event";
optionsBuilder.id_lists_url = api + "/get_id_lists";
statsig_cpp_core::StatsigOptions options = optionsBuilder.build();
Statsig statsig("server-secret-key", options);
statsig.initializeBlocking().wait();
```
`initialize` will perform a network request. After `initializeBlocking` completes, virtually all SDK operations will be synchronous. The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```cpp theme={null}
if (statsig.checkGate(user, "a_gate")) {
// Gate is on, enable new feature
} else {
// Gate is off
}
```
You can also disable exposure logging for this evaluation:
```cpp theme={null}
FeatureGateEvaluationOptions options;
options.disable_exposure_logging = true;
bool gateValue = statsig.check_gate(user, "a_gate", options);
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```cpp theme={null}
// Get a dynamic config for a specific user
DynamicConfig config = statsig.getDynamicConfig(user, "a_config");
// Access config values (We will provide accessors)
std::string product_name = config.value.get("product_name", "Awesome Product v1");
double price = config.value.get("price", 10.0);
// Access evaluation details such as rule id
statsig_cpp_core::EvaluationDetails detail = config.details;
std::cout << config.rule_id << std::endl; // The ID of the rule that served this config
std::cout << config.id_type << std::endl; // The type of the evaluation (experiment, config, etc)
// Advanced Usage:
// You can disable exposure logging for this specific check
DynamicConfigEvaluationOptions options;
options.disable_exposure_logging = true;
config = statsig.getDynamicConfig(user, "a_config", options);
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```cpp theme={null}
// Get a experiment for a specific user
statsig_cpp_core::Experiment exp = statsig.getExpriment(user, "an_experiment");
// Access config values (We will provide accessors)
auto product_name = exp.value.get("product_name", "Awesome Product v1");
auto price = exp.value.get("price", 10.0);
// Access evaluation details such as rule id
statsig_cpp_core::EvaluationDetails detail = exp.details;
std::cout << exp.rule_id << std::endl; // The ID of the rule that served this config
std::cout << exp.id_type << std::endl; // The type of the evaluation (experiment, config, etc)
// Advanced Usage:
// You can disable exposure logging for this specific check
ExperimentEvaluationOptions options;
options.disable_exposure_logging = true;
config = statsig.getExperiment(user, "an_experiment", options);
```
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```cpp theme={null}
FeatureGate gate = statsig.getFeatureGate(user, "example_gate");
std::cout << gate.rule_id << std::endl;
std::cout << gate.value << std::endl;
```
The `get_feature_gate()` method returns a FeatureGate object that provides:
* `value`: The boolean gate value
* `rule_id`: The ID of the rule that served this gate
* `id_type`: The type of the evaluation
* `evaluation_details`: Additional metadata about the evaluation
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```cpp theme={null}
statsig.log_event(
user,
"add_to_cart",
{
{"price", "9.99"},
{"item_name", "diet_coke_48_pack"}
}
);
```
The `log_event` method supports multiple overloads:
* `log_event(user, event_name)`
* `log_event(user, event_name, string_value)`
* `log_event(user, event_name, string_value, metadata)`
We will add support for numerical value and metadata
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
```cpp theme={null}
statsig_cpp_core::UserBuilder builder;
builder.setUserID(j["userID"]);
builder.setCustomIDs(j["customIDs"]);
builder.setCountry(j["customIDs"]);
statsig_cpp_core::User user = builder.build();
// UserBuilder also supports deserialize from json
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
### Available Options
```cpp theme={null}
std::optional specs_url;
std::optional id_lists_url;
std::optional log_event_url;
std::optional output_log_level;
std::optional environment;
bool enable_id_lists = false;
bool disable_all_logging = false;
bool disable_country_lookup = false;
bool disable_network = false;
```
### Proxy and Custom Network Routing
The C++ Server Core SDK currently documents endpoint overrides rather than a dedicated outbound proxy config. Use `specs_url`, `log_event_url`, and `id_lists_url` to route Statsig network calls through your own endpoints or proxy layer.
### Example Usage
```cpp theme={null}
statsig_cpp_core::StatsigOptionsBuilder optionsBuilder;
optionsBuilder.environment = "development";
optionsBuilder.specs_url = api_v2 + "/download_config_specs";
optionsBuilder.log_event_url = api + "/log_event";
optionsBuilder.id_lists_url = api + "/get_id_lists";
statsig_cpp_core::StatsigOptions options = optionsBuilder.build();
```
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```cpp theme={null}
statsig.shutdownBlocking();
```
The `shutdown()` method will:
* Flush any pending events to Statsig servers
* Gracefully shutdown the SDK, cleaning up resources
* Wait for all operations to complete
It's recommended to call `shutdown()` before your application exits to ensure all events are sent.
## Reference
### API Methods
* `check_gate(user: StatsigUser, gate_name: str, options: Optional[FeatureGateEvaluationOptions] = None) -> bool`
* `get_dynamic_config(user: StatsigUser, config_name: str, options: Optional[DynamicConfigEvaluationOptions] = None) -> DynamicConfig`
* `get_experiment(user: StatsigUser, experiment_name: str, options: Optional[ExperimentEvaluationOptions] = None) -> DynamicConfig`
* `get_layer(user: StatsigUser, layer_name: str, options: Optional[LayerEvaluationOptions] = None) -> Layer`
* `get_feature_gate(user: StatsigUser, gate_name: str, options: Optional[FeatureGateEvaluationOptions] = None) -> FeatureGate`
* `log_event(user: StatsigUser, event_name: str, value: Optional[Union[str, float]] = None, metadata: Optional[Dict[str, str]] = None) -> None`
* `shutdown() -> AsyncResult[None]`
### Fields Needed Methods
The following methods return information about which user fields are needed for evaluation:
* `get_gate_fields_needed(gate_name: str) -> List[str]`
* `get_dynamic_config_fields_needed(config_name: str) -> List[str]`
* `get_experiment_fields_needed(experiment_name: str) -> List[str]`
* `get_layer_fields_needed(layer_name: str) -> List[str]`
These methods return a list of strings representing the user fields that are required to properly evaluate the specified gate, config, experiment, or layer.
# .NET Server SDK
Source: https://docs.statsig.com/server-core/dotnet-core
Statsig's next-generation .NET Server SDK built on the Server Core framework, with improved performance and a unified evaluation engine for C# backends.
.NET Core on Github ,
NuGet Package
## Setup the SDK
## Installation
```bash theme={null}
dotnet add package Statsig.Dotnet
```
Or add the package reference to your `.csproj` file:
```xml theme={null}
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
```csharp theme={null}
using Statsig;
var statsig = new Statsig.Statsig("server-secret-key");
await statsig.Initialize();
```
You can also provide custom options:
```csharp theme={null}
var options = new StatsigOptionsBuilder()
.SetSpecsSyncIntervalMs(10000)
.SetDisableAllLogging(false)
.Build();
var statsig = new Statsig("server-secret-key", options);
await statsig.Initialize();
```
For shared instance usage:
```csharp theme={null}
var sharedStatsig = Statsig.NewShared("server-secret-key", options);
await sharedStatsig.Initialize();
var statsig = Statsig.Shared();
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```csharp theme={null}
var user = new StatsigUserBuilder()
.SetUserID("user_123")
.SetEmail("user@example.com")
.Build();
var gateValue = statsig.CheckGate(user, "new_feature_gate");
if (gateValue)
{
// Gate is on, enable new feature
}
else
{
// Gate is off
}
```
You can also disable exposure logging for this evaluation:
```csharp theme={null}
var options = new EvaluationOptions(disableExposureLogging: true);
var gateValue = statsig.CheckGate(user, "new_feature_gate", options);
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```csharp theme={null}
var user = new StatsigUserBuilder()
.SetUserID("user_123")
.Build();
var config = statsig.GetDynamicConfig(user, "product_config");
var productName = config.Get("product_name", "Default Product");
var price = config.Get("price", 9.99);
var isEnabled = config.Get("enabled", false);
var features = config.Get>("features", new List());
Console.WriteLine($"Config Name: {config.Name}");
Console.WriteLine($"Group Name: {config.GroupName}");
Console.WriteLine($"Rule ID: {config.RuleID}");
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```csharp theme={null}
var user = new StatsigUserBuilder()
.SetUserID("user_123")
.Build();
var experiment = statsig.GetExperiment(user, "button_color_test");
var buttonColor = experiment.Get("color", "blue");
var fontSize = experiment.Get("font_size", 14);
var showBorder = experiment.Get("show_border", true);
Console.WriteLine($"Experiment Name: {experiment.Name}");
Console.WriteLine($"Group Name: {experiment.GroupName}");
Console.WriteLine($"Rule ID: {experiment.RuleID}");
Console.WriteLine($"Button Color: {buttonColor}");
```
```csharp theme={null}
var user = new StatsigUserBuilder()
.SetUserID("user_123")
.Build();
var layer = statsig.GetLayer(user, "user_prefs_layer");
var theme = layer.Get("theme", "light");
var language = layer.Get("language", "en");
var notifications = layer.Get("notifications_enabled", true);
Console.WriteLine($"Layer Name: {layer.Name}");
Console.WriteLine($"Allocated Experiment: {layer.AllocatedExperimentName}");
Console.WriteLine($"Group Name: {layer.GroupName}");
Console.WriteLine($"Rule ID: {layer.RuleID}");
```
Note: Layer parameter access automatically logs exposure events unless disabled with `EvaluationOptions`.
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```csharp theme={null}
var user = new StatsigUserBuilder()
.SetUserID("user_123")
.Build();
statsig.LogEvent(user, "button_clicked");
statsig.LogEvent(user, "purchase_completed", 29.99);
statsig.LogEvent(user, "page_view", "homepage", new Dictionary
{
["referrer"] = "google",
["campaign"] = "summer_sale"
});
statsig.LogEvent(user, "video_watched", 120, new Dictionary
{
["video_id"] = "abc123",
["quality"] = "1080p"
});
```
The `LogEvent` method supports multiple overloads:
* `LogEvent(user, eventName)`
* `LogEvent(user, eventName, stringValue, metadata)`
* `LogEvent(user, eventName, intValue, metadata)`
* `LogEvent(user, eventName, doubleValue, metadata)`
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```csharp theme={null}
var user = new StatsigUserBuilder()
.SetUserID("user_123")
.Build();
var gate = statsig.GetFeatureGate(user, "new_feature_gate");
Console.WriteLine($"Gate Name: {gate.Name}");
Console.WriteLine($"Gate Value: {gate.Value}");
Console.WriteLine($"Rule ID: {gate.RuleID}");
Console.WriteLine($"ID Type: {gate.IDType}");
if (gate.EvaluationDetails != null)
{
Console.WriteLine($"Config Sync Time: {gate.EvaluationDetails.ConfigSyncTime}");
Console.WriteLine($"Init Time: {gate.EvaluationDetails.InitTime}");
Console.WriteLine($"Reason: {gate.EvaluationDetails.Reason}");
}
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
```csharp theme={null}
# Get a Parameter Store by name
param_store = statsig.getParameterStore(user, "my_parameter_store")
```
### Retrieving Parameter Values
Parameter Store provides methods for retrieving values of different types with fallback defaults.
* **GetBool(string, default(bool))**: Pulls key value of type boolean
* **GetString(string, "")**: Pulls key value of type string
* **GetLong(string, default(long))**: Pulls key value of type long
* **GetDouble(string, default(double))**: Pulls key value of type double
* **GetList(string, new List\<>())**: Pulls key value of type list
* **GetDictionary(string, new Dictionary\())**: Pulls key value of type Dictionary
### Evaluation Options
You can disable exposure logging when retrieving a parameter store:
```csharp theme={null}
var store = statsig.GetParameterStore(user, name!, options);
if (store == null)
{
throw new Exception($"Parameter store {name} not found");
}
var x = store.GetBool(paramName, default(bool));
var y = store.GetString(paramName, "");
var z = store.GetDictionary(paramName, new Dictionary());
```
## Using Shared Instance
In some applications, you may want to create a single Statsig instance that can be accessed globally throughout your codebase. The shared instance functionality provides a singleton pattern for this purpose:
```csharp theme={null}
var sharedStatsig = Statsig.NewShared("server-secret-key");
await sharedStatsig.Initialize();
// Later, anywhere in your codebase
var statsig = Statsig.Shared();
// Use the shared instance
var result = statsig.CheckGate(user, "my_gate");
```
The shared instance is useful for:
* Singleton pattern usage across your application
* Dependency injection scenarios
* Avoiding multiple SDK instances
Remember to clean up the shared instance on shutdown:
```csharp theme={null}
var statsig = Statsig.Shared();
await statsig.FlushEvents();
await statsig.Shutdown();
Statsig.RemoveSharedInstance();
```
## Manual Exposures
By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or call get() on a parameter in a layer. However, there are times when you may want to log an exposure event manually. For example, if you're using a gate to control access to a feature, but you don't want to log an exposure until the user actually uses the feature, you can use manual exposures.
All of the main SDK functions (`CheckGate`, `GetDynamicConfig`, `GetExperiment`, `GetLayer`) accept an optional `EvaluationOptions` parameter. When `disableExposureLogging` is set to `true`, the SDK will not automatically log an exposure event. You can then manually log the exposure at a later time using the corresponding manual exposure logging method:
```csharp theme={null}
var result = statsig.CheckGate(user, "a_gate_name", new EvaluationOptions(disableExposureLogging: true));
```
```csharp theme={null}
statsig.ManuallyLogGateExposure(user, "a_gate_name");
```
```csharp theme={null}
var config = statsig.GetDynamicConfig(user, "a_dynamic_config_name", new EvaluationOptions(disableExposureLogging: true));
```
```csharp theme={null}
statsig.ManuallyLogDynamicConfigExposure(user, "a_dynamic_config_name");
```
```csharp theme={null}
var experiment = statsig.GetExperiment(user, "an_experiment_name", new EvaluationOptions(disableExposureLogging: true));
```
```csharp theme={null}
statsig.ManuallyLogExperimentExposure(user, "an_experiment_name");
```
```csharp theme={null}
var layer = statsig.GetLayer(user, "a_layer_name", new EvaluationOptions(disableExposureLogging: true));
var paramValue = layer.Get("a_param_name", "fallback_value");
```
```csharp theme={null}
statsig.ManuallyLogLayerParameterExposure(user, "a_layer_name", "a_param_name");
```
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
`StatsigUser` represents the user context for feature flag evaluation. Use `StatsigUserBuilder` to create user instances:
```csharp theme={null}
var user = new StatsigUserBuilder()
.SetUserID("user_123")
.SetEmail("user@example.com")
.SetIP("192.168.1.1")
.SetUserAgent("Mozilla/5.0...")
.SetCountry("US")
.SetLocale("en-US")
.SetAppVersion("1.2.3")
.SetCustomIDs(new Dictionary
{
["employee_id"] = "emp_456",
["team_id"] = "team_789"
})
.AddCustomID("department_id", "dept_123")
.SetCustomProperties(new Dictionary
{
["subscription_tier"] = "premium",
["account_age_days"] = 365,
["is_beta_user"] = true
})
.AddCustomProperty("last_login", DateTime.UtcNow)
.SetPrivateAttributes(new Dictionary
{
["internal_user_score"] = 0.85,
["risk_level"] = "low"
})
.AddPrivateAttribute("pii_hash", "abc123def456")
.Build();
```
## Builder Methods
* **SetUserID(string)**: Set the primary user ID
* **SetEmail(string)**: Set user email
* **SetIP(string)**: Set user IP address
* **SetUserAgent(string)**: Set browser user agent
* **SetCountry(string)**: Set user country
* **SetLocale(string)**: Set user locale
* **SetAppVersion(string)**: Set app version
* **SetCustomIDs(Dictionary\)**: Set all custom IDs
* **AddCustomID(string, string)**: Add a single custom ID
* **SetCustomProperties(Dictionary\)**: Set all custom properties
* **AddCustomProperty(string, object)**: Add a single custom property
* **SetPrivateAttributes(Dictionary\)**: Set all private attributes
* **AddPrivateAttribute(string, object)**: Add a single private attribute
* **Build()**: Create the StatsigUser instance
Remember to dispose of StatsigUser instances when done:
```csharp theme={null}
using var user = new StatsigUserBuilder()
.SetUserID("user_123")
.Build();
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
`StatsigOptions` can be configured using the `StatsigOptionsBuilder` pattern:
```csharp theme={null}
var options = new StatsigOptionsBuilder()
.SetSpecsURL("https://custom-api.statsig.com/v1/download_config_specs")
.SetLogEventURL("https://custom-api.statsig.com/v1/rgstr")
.SetEnvironment("production")
.SetSpecsSyncIntervalMs(30000)
.SetEventLoggingMaxQueueSize(1000)
.SetWaitForCountryLookupInit(true)
.SetWaitForUserAgentInit(true)
.SetDisableCountryLookup(false)
.SetDisableUserAgentParsing(false)
.SetDisableAllLogging(false)
.SetInitTimeoutMs(3000)
.SetFallbackToStatsigApi(false)
.SetEnableIDLists(true)
.SetIDListsURL("https://custom-api.statsig.com/v1/get_id_lists")
.SetIDListsSyncIntervalMs(60000)
.SetGlobalCustomFields(new Dictionary
{
["app_version"] = "1.2.3",
["build_number"] = "456"
})
.Build();
var statsig = new Statsig("server-secret-key", options);
```
## Available Options
* **SetSpecsURL(string)**: Override the default specs download endpoint
* **SetLogEventURL(string)**: Override the default event logging endpoint
* **SetEnvironment(string)**: Set the environment tier (e.g., "production", "staging")
* **SetSpecsSyncIntervalMs(int)**: How often to sync configuration specs (default: 10000ms)
* **SetEventLoggingMaxQueueSize(int)**: Maximum events to queue before flushing
* **SetWaitForCountryLookupInit(bool)**: Wait for country lookup initialization
* **SetWaitForUserAgentInit(bool)**: Wait for user agent parsing initialization
* **SetDisableCountryLookup(bool)**: Disable automatic country detection
* **SetDisableUserAgentParsing(bool)**: Disable user agent parsing
* **SetDisableAllLogging(bool)**: Disable all event logging
* **SetInitTimeoutMs(int)**: Maximum time in milliseconds to wait for SDK initialization (default: 3000ms)
* **SetFallbackToStatsigApi(bool)**: Fallback to Statsig API when custom adapters fail (default: false)
* **SetEnableIDLists(bool)**: Enable ID list targeting
* **SetIDListsURL(string)**: Override the default ID lists endpoint
* **SetIDListsSyncIntervalMs(int)**: How often to sync ID lists (default: 60000ms)
* **SetGlobalCustomFields(Dictionary\)**: Global custom fields for all events
* **SetSpecAdapterConfig(SpecAdapterConfig)**: Configure a custom spec source such as [Statsig Forward Proxy](/infrastructure/forward-proxy)
* **SetProxyConfig(ProxyConfig)**: Configuration for connecting through a proxy server
### Proxy and Custom Network Routing
The `.NET` Server Core SDK uses `SetProxyConfig(ProxyConfig)` for a standard outbound HTTP proxy. If you are routing config sync through [Statsig Forward Proxy](/infrastructure/forward-proxy) or another custom spec source, use `SetSpecAdapterConfig(SpecAdapterConfig)`. If you only need custom Statsig endpoints, use `SetSpecsURL`, `SetLogEventURL`, and `SetIDListsURL`.
```csharp theme={null}
var proxyConfig = new ProxyConfig
{
ProxyHost = "proxy.example.com",
ProxyPort = 8080,
ProxyAuth = "username:password", // Optional
ProxyProtocol = "http", // Optional: "http" or "https"
CaCertPath = "/etc/ssl/certs/corporate-ca.pem" // Optional
};
var options = new StatsigOptionsBuilder()
.SetProxyConfig(proxyConfig)
.Build();
var statsig = new Statsig("server-secret-key", options);
```
### ProxyConfig Properties
* **ProxyHost** (string): The hostname or IP address of the proxy server
* **ProxyPort** (int): The port number of the proxy server
* **ProxyAuth** (string, optional): Authentication credentials in the format "username:password"
* **ProxyProtocol** (string, optional): The protocol to use for the proxy connection ("http" or "https")
* **CaCertPath** (string, optional): Path to a PEM CA bundle for outbound TLS
### Statsig Forward Proxy Example
```csharp theme={null}
var specAdapterConfig = new SpecAdapterConfig(
adapterType: "network_grpc_websocket",
specsUrl: "http://forward-proxy.internal:50051"
);
var options = new StatsigOptionsBuilder()
.SetSpecAdapterConfig(specAdapterConfig)
.SetFallbackToStatsigApi(true)
.Build();
```
`EvaluationOptions` allows you to customize the behavior of feature flag evaluations:
```csharp theme={null}
var options = new EvaluationOptions(disableExposureLogging: true);
var gateValue = statsig.CheckGate(user, "feature_gate", options);
var config = statsig.GetDynamicConfig(user, "product_config", options);
var experiment = statsig.GetExperiment(user, "button_test", options);
var layer = statsig.GetLayer(user, "user_prefs_layer", options);
```
## Options
* **DisableExposureLogging**: When `true`, prevents automatic exposure event logging for this evaluation. Useful when you want to evaluate a feature flag without affecting analytics or experiment results.
## Use Cases
* **Internal Tools**: Check flag values for debugging without affecting user metrics
* **Conditional Logic**: Evaluate flags as part of complex logic where exposure should be logged manually later
When exposure logging is disabled, you can manually log exposures later using the manual exposure methods:
```csharp theme={null}
var options = new EvaluationOptions(disableExposureLogging: true);
var gateValue = statsig.CheckGate(user, "feature_gate", options);
if (shouldLogExposure)
{
statsig.ManuallyLogGateExposure(user, "feature_gate");
}
```
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```csharp theme={null}
await statsig.FlushEvents();
await statsig.Shutdown();
statsig.Dispose();
```
For shared instances:
```csharp theme={null}
var statsig = Statsig.Shared();
await statsig.FlushEvents();
await statsig.Shutdown();
Statsig.RemoveSharedInstance();
```
## Methods
* **FlushEvents()**: Immediately flush any pending events to Statsig servers
* **Shutdown()**: Gracefully shutdown the SDK, flushing events and cleaning up resources
* **Dispose()**: Release native resources (implements IDisposable)
It's recommended to call `FlushEvents()` before `Shutdown()` to ensure all events are sent, and always call `Dispose()` or use `using` statements to properly clean up resources.
## Client SDK Bootstrapping | SSR
If you are using the Statsig client SDK in a browser or mobile app, you can bootstrap the client SDK with the values from the server SDK to avoid a network request on the client. This is useful for server-side rendering (SSR) or when you want to reduce the number of network requests on the client.
```csharp theme={null}
var user = new StatsigUserBuilder()
.SetUserID("user_123")
.Build();
var initResponse = statsig.GetClientInitializeResponse(user);
var options = new ClientInitResponseOptions
{
HashAlgorithm = "sha256",
ClientSDKKey = "client-sdk-key",
IncludeLocalOverrides = false
};
var customInitResponse = statsig.GetClientInitializeResponse(user, options);
```
The `GetClientInitializeResponse` method returns a JSON string containing the initialization data needed by client-side SDKs. This enables server-side rendering and reduces client initialization time.
## ClientInitResponseOptions
* **HashAlgorithm**: Hash algorithm for response integrity (default: "djb2")
* **ClientSDKKey**: Client SDK key to include in response
* **IncludeLocalOverrides**: Whether to include local overrides in the response (default: false)
### Working with IP or UserAgent Values
The server SDK will not automatically use the `ip`, or `userAgent` for gate evaluation as Statsig servers would, since we don't have access to the request headers. If you'd like to use the attributes we derive from these properties, like Browser Name/Version, OS Name/Version & Country, you must manually set the `ip` and `userAgent` fields on the user object when calling `GetClientInitializeResponse`.
### Working with IDs
To ensure that the server SDK evaluates each config accurately, they need access to all user attributes that the client SDK leverages. We recommend passing all of these attributes to the server SDK - using tools like Cookies if needed to ensure they're attached on first requests. If the user objects on the client and server aren't identical, modern SDKs will throw an InvalidBootstrap warning.
Client SDKs also auto-generate a StableID, and it's important to manage the lifecycle of this ID to be sure that it is consistent on client and server side. Managing this with a cookie is often easiest, see [Keeping StableID Consistent](/client/javascript-sdk-stable-id#keeping-stableid-consistent). If StableID differs between Client and Server, you'll see a BootstrapStableIDMismatch warning, and checks with this warning won't contribute to your experiment analyses.
### getClientInitializeResponse and the legacy JS SDK
If you are migrating from the legacy JS Client, you will need to make some updates to how your server SDK generates values. The default hashing algorithm was changed from `sha256` to `djb2` for performance and size reasons.
## Local Overrides
Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console.
```csharp theme={null}
statsig.OverrideGate("test_gate", true);
statsig.OverrideDynamicConfig("test_config", new Dictionary
{
["color"] = "red",
["size"] = 42,
["enabled"] = true
});
statsig.OverrideExperiment("test_experiment", new Dictionary
{
["variant"] = "treatment",
["multiplier"] = 1.5
});
statsig.OverrideExperimentByGroupName("test_experiment", "treatment_group");
statsig.OverrideLayer("test_layer", new Dictionary
{
["theme"] = "dark",
["font_size"] = 16
});
statsig.OverrideParameterStore("testing123", new Dictionary()
{
["brush_color"] = "blue",
["monochromatic"] = true,
["weight"] = 42,
["gradient"] = 3.14,
["pen_sizes"] = [1, 2, 3, 4, 5],
["artwork"] = new Dictionary()
{
["nesting"] = "treatment"
}
});
```
You can also specify a user ID for targeted overrides:
```csharp theme={null}
statsig.OverrideGate("test_gate", true, "user_123");
statsig.OverrideDynamicConfig("test_config", new Dictionary
{
["special_feature"] = true
}, "user_123");
```
Local overrides are useful for:
* Testing specific configurations during development
* QA testing with known values
* Debugging feature flag behavior
* Integration testing with predictable results
Note: Overrides persist for the lifetime of the Statsig instance and affect all evaluations unless a specific user ID is provided.
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant.
```csharp theme={null}
using System.Collections.Generic;
using Statsig;
// Implement PersistentStorage to control how user stickiness is stored.
public class MyPersistentStorage : PersistentStorage
{
private readonly Dictionary> _store = new();
public override IDictionary Load(string key)
{
// Load persisted values for this user from your backing store.
return _store.TryGetValue(key, out var configs)
? new Dictionary(configs)
: new Dictionary();
}
public override void Save(string key, string configName, StickyValues data)
{
// Persist the sticky assignment (database, Redis, etc.).
if (!_store.TryGetValue(key, out var configs))
{
configs = new Dictionary();
_store[key] = configs;
}
configs[configName] = data;
}
public override void Delete(string key, string configName)
{
// Remove the persisted value for this config/user.
if (_store.TryGetValue(key, out var configs))
{
configs.Remove(configName);
}
}
}
```
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
Data stores allow you to customize how the SDK fetches and caches feature specifications, enabling advanced use cases like using Redis or other distributed caches.
```csharp Csharp theme={null}
using System.Threading.Tasks;
using Statsig;
public class MyDataStore : DataStore
{
public Task Initialize()
{
// Perform any initialization needed for your data store.
return Task.CompletedTask;
}
public Task Shutdown()
{
// Clean up resources.
return Task.CompletedTask;
}
public DataStoreResponse Get(string key)
{
// Retrieve data for the given key.
// This is called during SDK evaluation.
return Task.FromResult(null);
}
public void Set(string key, string value, long? time = null)
{
// Store data for the given key.
// Called when SDK receives updates from Statsig.
return Task.CompletedTask;
}
public bool SupportsPollingUpdatesFor(string key)
{
// Return true if your store supports polling updates for this key, false otherwise.
return Task.FromResult(false).CompletedTask;
}
}
// Use data store
var options = new StatsigOptionsBuilder()
.SetDataStore(new MyDataStore())
.Build();
var statsig = new Statsig("server-secret-key", options);
await statsig.Initialize();
```
## Performance Benefits
The .NET Core SDK leverages Statsig's high-performance Rust evaluation engine through FFI bindings, details:
* Native Rust evaluation engine handles all rule processing
* .NET wrapper provides familiar C# APIs and type safety
* Automatic memory management between .NET and Rust boundaries
* Thread-safe operations across the FFI boundary
## Async/Await Support
All network operations are fully async:
```csharp theme={null}
await statsig.Initialize();
await statsig.FlushEvents();
await statsig.Shutdown();
```
Evaluation methods are synchronous for optimal performance:
```csharp theme={null}
var result = statsig.CheckGate(user, "gate_name");
```
## Thread Safety
The Statsig instance is thread-safe and can be used concurrently across multiple threads. Consider using the shared instance(singleton) pattern for application-wide usage:
```csharp theme={null}
var sharedStatsig = Statsig.NewShared("server-secret-key");
await sharedStatsig.Initialize();
var statsig = Statsig.Shared();
```
# Elixir Server SDK
Source: https://docs.statsig.com/server-core/elixir-core
Statsig's next-generation Elixir Server SDK built on the Server Core framework, with improved performance and a unified evaluation engine for BEAM apps.
Elixir Core on Github ,
Hex Package
## Setup the SDK
To use the SDK, add the following to your `mix.exs`:
```elixir theme={null}
{:statsig_elixir, "~> 0.8.0"},
```
SDK is written using `rustler_precompiled`, which will download precompiled binary by default. But there is also an option to build Rust code within your project by cloning [statsig-server-core](https://github.com/statsig-io/statsig-server-core)
```bash theme={null}
cd statsig-server-core/statsig-elixir/
# set the environment variable
FORCE_STATSIG_NATIVE_BUILD="true" mix compile
```
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
Statsig.ex is using GenServer to manage the actual implementation of statsig instance (which is written in Rust). Which requires you add Statsig into your Supervision Tree.
```elixir theme={null}
# Initializing, with StatsigOptions
sdk_key = "secret-key******" # your secret key
statsig_options = %StatsigOptions{enable_id_lists: true}
# Add to your supervision tree
statsig_spec = %{id: Statsig, start: {Statsig, :start_link, [sdk_key, statsig_options]}}
children = [
# Other Apps
statsig_spec
]
res = Supervisor.start_link(children, opts)
# Or directly initialize the GenServer
{:ok,_} = Statsig.start_link(sdk_key, statsig_options)
Statsig.initialize()
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```elixir theme={null}
user = %StatsigUser{
user_id: "test_user_123"
}
{:ok, check_gate} = Statsig.check_gate("test_public", user)
# check_gate will be a boolean
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```elixir theme={null}
# Get a dynamic config for a specific user
user = %StatsigUser{
user_id: "test_user_123"
}
{:ok, config} = Statsig.get_dynamic_config("a_config", user)
# Access the values in the dynamic config:
param_value = DynamicConfig.get_param_value(config, "header_text")
# Disable exposure
options = %Statsig.DynamicConfigEvaluationOptions{
disable_exposure_logging = true
}
{:ok, config} = Statsig.get_dynamic_config("a_config", user, options)
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```elixir theme={null}
# Values via get_layer
user = %StatsigUser{
user_id: "test_user_123"
}
{:ok, layer} = Statsig.get_layer("user_promo_experiments", user)
{:ok, title_string_value} = Layer.get(layer, "title", "Welcome to Statsig!")
{:ok, discount_float_value} = Layer.get(layer, "discount", 0.1)
# Via get_experiment
{:ok, experiment} = Statsig.get_experiment("user_promo_experiment", user)
title_exp = Experiment.get_param_value(experiment, "new_user_promo_title")
# Disable exposure
options = %Statsig.ExperimentEvaluationOptions{
disable_exposure_logging = true
}
{:ok, experiment} = Statsig.get_experiment("user_promo_experiment", user, options)
```
If you are using layer to get value -- get param value. It will return primitive types: boolean, string, and numbers, for more complex type, SDK will return json serialized values.
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```elixir theme={null}
{:ok, feature_gate} = Statsig.get_feature_gate(user, "example_gate")
# access the value, or the name off of the feature_gate object
options = %Statsig.FeatureGateEvaluationOptions{
disable_exposure_logging = true
}
{:ok, feature_gate} = Statsig.get_feature_gate(user, "example_gate", options)
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
*Parameter stores are not yet available for this sdk. Need it now? Let us know in Slack.*
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```elixir theme={null}
Statsig.log_event(user, "test_event", 1, %{"metadata_1" => "value"})
```
### Sending Events to Log Explorer
You can forward logs to Logs Explorer for convenient analysis using the Forward Log Line Event API. This lets you include custom metadata and event values with each log.
Sending events to Log Explorer is not yet available for this sdk. Need it now? Let us know in Slack.
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
```elixir theme={null}
user = %Statsig.User{
user_id: "a-user-id",
email: "user@example.com",
ip: "192.168.1.1",
user_agent: "Mozilla/5.0...",
country: "US",
locale: "en_US",
app_version: "1.0.0",
custom: %{
# Custom fields
"plan" => "premium",
"age" => 25
},
custom_ids: %{
# Custom ID types
"stable_id" => "stable-id-123"
},
private_attributes: %{
# Private attributes not forwarded to integrations
"email" => "private@example.com"
}
}
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
The environment you're operating in (e.g., Production)
The type of logs you'd like exposed. (e.g., Debug)
How long it should take for initialization to time out.
How often events should flush to the Statsig servers.
Maximum number of events to queue before forcing a flush.
* Default is `2000`
* event\_logging\_max\_queue\_size \* event\_logging\_max\_pending\_batch\_queue\_size is the upper limit on how many events are queued
* See also `event_logging_max_pending_batch_queue_size`
Maximum number of event batches to hold in buffer to retry.
* Default is `100`.
* event\_logging\_max\_queue\_size \* event\_logging\_max\_pending\_batch\_queue\_size is the upper limit on how many events are queued
* eg: 2000 \* 100 means the SDK can process 200k event per second before events start getting dropped
* See also `event_logging_max_queue_size`.
The URL events should be logged to
How often specs should sync from the Statsig servers
The URL Statsig should download specs from
Advanced configuration for fetching specs from custom sources, including [Statsig Forward Proxy](/infrastructure/forward-proxy).
Enable ID list download. **Required to be `true` when using segments with more than 1000 IDs.** See [ID List segments](/segments/add-id-list) for more details.
The URL ID lists should be downloaded from
How often ID lists should be synced.
Block initialization call until country lookup is initialized
Block initialization call until user\_agent is initialized
When `true`, disables all event logging.
To improve memory usage, disable using country lookup.
Turn off all network requests including get\_dcs and log\_events
To improve memory usage, disable using user agent parsing.
***
```elixir theme={null}
# Initialize StatsigOptions with custom parameters
statsig_options = %StatsigOptions{
enable_id_lists: true
}
# Pass the options object into statsig.initialize()
{:ok, _} = Statsig.start_link(sdk_key, statsig_options)
Statsig.initialize()
```
### Proxy and Custom Network Routing
The Elixir Server Core SDK does not currently document a dedicated outbound HTTP proxy config. For custom network routing, use `spec_adapter_configs` for [Statsig Forward Proxy](/infrastructure/forward-proxy) or set `specs_url`, `log_event_url`, and `id_lists_url` directly.
```elixir theme={null}
statsig_options = %StatsigOptions{
spec_adapter_configs: [
%Statsig.SpecAdapterConfig{
adapter_type: "network_grpc_websocket",
specs_url: "http://forward-proxy.internal:50051",
authentication_mode: "none"
}
],
fallback_to_statsig_api: true
}
```
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```elixir theme={null}
Statsig.shutdown()
```
## Client SDK Bootstrapping | SSR
If you are using the Statsig client SDK in a browser or mobile app, you can bootstrap the client SDK with the values from the server SDK to avoid a network request on the client. This is useful for server-side rendering (SSR) or when you want to reduce the number of network requests on the client.
```elixir theme={null}
# Get client initialize response for a user
{:ok, response} = Statsig.get_client_init_response_as_string(user)
# Pass values to a client SDK to initialize without a network request
```
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant.
Not supported at this time.
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
Not supported at this time.
## Custom Output Logger
The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity.
Not supported at this time.
## Observability Client
The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the [Monitoring documentation](/sdk_monitoring).
Not supported at this time.
## FAQ
See the guide on [device level experiments](/guides/logging-events#device-level-events)
# Go Server Core SDK (Beta)
Source: https://docs.statsig.com/server-core/go-core
Statsig's next-generation Go Server SDK built on the Server Core framework, with improved performance and a unified evaluation engine for Go backends.
Go Core on Github
## Setup the SDK
via the `go get` CLI:
You can install the latest version of the SDK:
```
go get github.com/statsig-io/statsig-go-core@latest
```
Or, add a dependency on the most recent version of the SDK in go.mod:
```
require (
github.com/statsig-io/statsig-go-core v0.10.2-beta
)
```
See the [Releases tab in GitHub](https://github.com/statsig-io/statsig-server-core/releases) for the latest versions.
:::note
`go get` requires a Go module project with a go.mod file.
:::
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
```go expandable theme={null}
import (
"log"
statsig "github.com/statsig-io/statsig-go-core"
)
options, err := statsig.NewOptionsBuilder().
WithOutputLogLevel("DEBUG").
Build()
if err != nil {
log.Fatalf("failed to build options: %v", err)
}
s, err := statsig.NewStatsigWithOptions("secret-key", options)
if err != nil {
log.Fatalf("failed to create Statsig client: %v", err)
}
s.Initialize()
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
// Basic check
if s.CheckGate(user, "a_gate") {
// Gate is on, enable new feature
} else {
// Gate is off
}
// With options (e.g., disable automatic exposure logging)
options := &statsig.FeatureGateEvaluationOptions{DisableExposureLogging: true}
s.CheckGateWithOptions(user, "a_gate", options)
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
// You can disable exposure logging for this specific check
dynamicConfigOptions := &statsig.DynamicConfigEvaluationOptions{DisableExposureLogging: false}
dynamic_config := "a_config"
config := s.GetDynamicConfigWithOptions(user, dynamic_config, dynamicConfigOptions)
// Access the config values
str_val := config.GetString("str_val", "default_str_val") // returns String
int_val := config.GetNumber("number_val", 100) // returns float64
bool_val := config.GetBool("bool_val", false) // returns bool
interface_val := config.GetSlice("interface_val", []any{"default_interface_val"}) // returns []any
map_val := config.GetMap("map_val", map[string]any{"default": "value"}) // returns map[string]interface{}
// The config object also provides metadata about the evaluation
fmt.Println(config.RuleID) // The ID of the rule that served this config
fmt.Println(config.IDType) // The type of the evaluation (experiment, config, etc)
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
// Getting values with GetExperiment
experimentOptions := &statsig.ExperimentEvaluationOptions{DisableExposureLogging: false}
experiment := s.GetExperimentWithOptions(user, "a_test_experiment", experimentOptions)
str_val := experiment.GetString("str_val", "default_str_val") // returns String
int_val := experiment.GetNumber("number_val", 100) // returns float64
// Getting values with GetLayer
layerOptions := &statsig.LayerEvaluationOptions{DisableExposureLogging: false}
layer := s.GetLayerWithOptions(user, "a_test_experiment", layerOptions)
str_val := layer.GetString("str_val", "default_str_val") // returns String
int_val := layer.GetNumber("number_val", 100) // returns float64
```
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
options := &statsig.FeatureGateEvaluationOptions{DisableExposureLogging: false}
featureGate := s.GetFeatureGateWithOptions(user, "a_gate", options)
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
event := statsig.EventPayload{
EventName: "sample_event",
Value: "event",
Metadata: map[string]string{
"val_1": "log val 1",
},
}
s.LogEvent(user, event)
```
## Manual Exposures
By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or call get() on a parameter in a layer. However, there are times when you may want to log an exposure event manually. For example, if you're using a gate to control access to a feature, but you don't want to log an exposure until the user actually uses the feature, you can use manual exposures.
All of the main SDK functions (`CheckGate`, `GetDynamicConfig`, `GetExperiment`, `GetLayer`) accept an optional options parameter with `DisableExposureLogging` field. When this is set to `true`, the SDK will not automatically log an exposure event. You can then manually log the exposure at a later time using the corresponding manual exposure logging method:
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
options := &statsig.FeatureGateEvaluationOptions{DisableExposureLogging: true}
result := s.CheckGateWithOptions(user, "a_gate_name", options)
```
```go theme={null}
s.ManuallyLogFeatureGateExposure(user, "gate_name")
```
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
options := &statsig.DynamicConfigEvaluationOptions{DisableExposureLogging: true}
config := s.GetDynamicConfigWithOptions(user, "config_name", options)
```
```go theme={null}
s.ManuallyLogDynamicConfigExposure(user, "config_name")
```
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
options := &statsig.ExperimentEvaluationOptions{DisableExposureLogging: true}
experiment := s.GetExperimentWithOptions(user, "experiment_name", options)
```
```go theme={null}
s.ManuallyLogExperimentExposure(user, "experiment_name")
```
```go theme={null}
user, _ := statsig.NewUserBuilderWithUserID("a-user").Build()
options := &statsig.LayerEvaluationOptions{DisableExposureLogging: true}
layer := s.GetLayerWithOptions(user, "layer_name", options)
paramValue := layer.GetString("param_name", "fallback")
```
```go theme={null}
s.ManuallyLogLayerParamExposure(user, "layer_name", "param_name")
```
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
### Parameters
Custom URL for fetching feature specifications.
Custom URL for logging events.
Environment parameter for evaluation.
How often events are flushed to Statsig servers (in milliseconds).
Maximum number of events to queue before forcing a flush.
How often the SDK updates specifications from Statsig servers (in milliseconds).
Controls the verbosity of SDK logs.
Disables country lookup based on IP address. Set to `true` to improve performance if country-based targeting is not needed.
Disables user agent parsing. Set to `true` to improve performance if device/browser-based targeting is not needed.
When set to true, the SDK will wait for country lookup data (e.g., GeoIP or YAML files) to fully load during initialization. This may slow down by \~1 second startup but ensures that IP-to-country parsing is ready at evaluation time.
When set to true, the SDK will wait until user agent parsing data is fully loaded during initialization. This may slow down by \~1 second startup but ensures that parsing of the user's userAgent string into fields like browserName, browserVersion, systemName, systemVersion, and appVersion is ready before any evaluations.
Enables downloading ID lists; set to false to skip ID list syncing.
Custom URL for fetching ID lists.
How often the SDK syncs ID lists (in milliseconds).
When set to true, the SDK will not log any events or exposures.
When set to true, the SDK will not make any network requests.
JSON string of custom fields that should be appended to every evaluation.
Internal reference for a custom observability client created via the SDK.
Internal reference for a custom data store adapter created via the SDK.
Internal reference for a persistent storage adapter created via the SDK.
Maximum time in milliseconds to wait for SDK initialization to complete. If initialization takes longer than this timeout, the SDK will continue to operate but may return default values until initialization completes.
When set to true, the SDK will fallback to using the Statsig API directly if custom adapters (like local file adapters) fail to load configurations.
### Proxy and Custom Network Routing
The Go Server Core SDK currently documents endpoint overrides rather than a dedicated outbound proxy config. Use `WithSpecsUrl(...)`, `WithLogEventUrl(...)`, and `WithIdListsUrl(...)` to route Statsig network calls through your own endpoints or proxy layer.
***
### Example Options Usage
```go expandable theme={null}
import (
statsig "github.com/statsig-io/statsig-go-core"
)
// Initialize StatsigOptions with custom parameters
options, err := statsig.NewOptionsBuilder().
WithSpecsUrl("https://example.com/specsUrl").
WithLogEventUrl("https://example.com/logUrl").
WithEnvironment("production").
WithEventLoggingFlushIntervalMs(2000).
WithEventLoggingMaxQueueSize(5000).
WithSpecsSyncIntervalMs(1000).
WithOutputLogLevel("DEBUG").
WithDisableCountryLookup(true).
WithDisableUserAgentParsing(true).
WithWaitForCountryLookupInit(false).
WithEnableIdLists(true).
WithIdListsSyncIntervalMs(60000).
WithInitTimeoutMs(3000).
WithFallbackToStatsigApi(false).
Build()
if err != nil {
// handle options build error
}
// Pass the options object when initializing the Statsig client
s, err := statsig.NewStatsigWithOptions("secret-key", options)
if err != nil {
// handle init error
}
s.Initialize()
```
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```go theme={null}
// Method signature
func (s *Statsig) Shutdown() {}
// example usage
s, err := statsig.NewStatsig("secret-key")
s.Initialize()
s.Shutdown()
```
### Flush Events
```go theme={null}
// Method signature
func (s *Statsig) FlushEvents() {}
// example usage
s, err := statsig.NewStatsig("secret-key")
s.Initialize()
s.FlushEvents()
```
## FAQ
##### Installation FAQs
#### How do I fix undefined symbol errors/linker errors?
You may need to reset your environment variables to those found in the statsig.env or statsig.env.ps1 file which was generated during the post-install script. Running the command sets the environment variables for the current terminal session. Users may need to add in the variables to their .bashrc, .zshrc, or .ps1 file to load them automatically.
# Server Core Overview
Source: https://docs.statsig.com/server-core/index
Statsig Server Core is the second generation of Server SDKs with improved performance, a unified evaluation engine, and consistent APIs across languages.
## Statsig Server Core
Statsig Server Core is our second generation of Server SDKs: a full rewrite with a shared, performance-focused core library that enables superior across-the-board perf and feature maturity across our Server SDKs. Server Core SDKs include:
* **Faster evaluation:** A shared, performance-focused Rust evaluation engine, that evaluates 3-5x as our pure native code SDKs.
* **Superior non-eval performance:** more efficient network and CPU usage, plus other performance optimizations always arriving to each SDK.
* **Features new to Server SDKs:** Parameter Stores, Contextual Multi-Armed Bandits, and more.
* **Quality-of-life improvements from certain SDKs:** Observability Interface, streaming config changes (from the Statsig Forward Proxy) and more
### Availability across SDKs
Server Core SDKs are available on an opt-in basis, with native SDKs still available and supported in all languages. If you're just getting started with Statsig, we recommend choosing a Server Core SDK if its convenient for you, but we continue to support bug fixes in our [Legacy SDKs](/server-core/legacy-sdks), and will until we set end-of-support dates for these SDKs. At that time - we'll also provide guidance to make migration as easy as possible.
| SDK | Status | Package | Migration Guide |
| ---------------------------------- | -------------- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
| [Node](/server-core/node-core) | Stable | [npm](https://www.npmjs.com/package/@statsig/statsig-node-core) | [Link](/server-core/migration-guides/node) |
| [Python](/server-core/python-core) | Stable | [PyPI](https://pypi.org/project/statsig-python-core/) | [Link](/server-core/migration-guides/python) |
| [Java](/server-core/java-core) | Stable | [Maven Central](https://central.sonatype.com/artifact/com.statsig/javacore/overview) | [Link](server-core/migration-guides/java) |
| [PHP](/server-core/php-core) | Stable | [Packagist](https://packagist.org/packages/statsig/statsigsdk) | |
| [Rust](/server-core/rust-core) | Stable | [Crates.io](https://crates.io/crates/statsig-rust) | |
| [Elixir](/server-core/elixir-core) | Stable | | |
| [C++](/server-core/cpp-core) | Stable | | |
| [.NET](/server-core/dotnet-core) | Stable | [NuGet](https://www.nuget.org/packages/Statsig.Dotnet) | |
| Ruby | In Development | | |
| [Go](/server-core/go-core) | Beta | | |
### Technical differences
**Build process:** Statsig Server Core uses a core library written in Rust, with bindings written to other languages. In the vast majority of cases, this results in an unchanged development experience with superior performance, but given that the Rust code must compile into a binary usable in your development and deployment environments, some development snafus exist:
* **Choosing the right build:** In most cases, the SDK's package manager will automatically install the versions you need. The notable exception is in Java - where our SDK will print out the right build for you, if it's not included at runtime.
* **Managing lockfiles:** If your deployment and development environments require different builds (as is common), you'll want to include both versions in a lockfile like package-lock.json.
* **Untested environments:** Certain environments, like the edge, aren't friendly to this new build process - and for now, we recommend using our [native SDKs](/server-core/legacy-sdks) for the time being.
**New Configuration Spec:** Server Core uses a smaller "ruleset", or configuration spec. If you use the spec directly, your logic and parsing will have to change.
**Event Logging**
Server core SDKs, starting in v0.4.0+, have a new event logging architecture. This is designed to stream events freely to statsig servers during normal operation, and throttle/drop events SDK side during outages on the event logging endpoint to enable the service to spin up healthy before processing steady-state qps. We expose the following parameters to tune this implementation
```
- event_logging_max_queue_size: Controls batch size (default 2000). Note that exceeding the backend request size limit (10MB) will drop requests
- event_logging_max_pending_batch_queue_size: Controls max pending batches (default: 20). The tradeoff here is increased memory usage to buffer events when requests fail if you increase it, and losing additional events if you decrease it
- disable_all_logging: Completely disables event logging
```
```
+----------------+ +----------------+ +----------------+
| Event Sources | | Event Queue | | Flush Triggers |
|----------------| |----------------| |----------------|
| - Gate Checks |---->| - Pending | | - Scheduled |
| - Config Reads | | Events | | (Time-based) |
| - Custom Events| | - Batches |<----| - Manual |
+----------------+ +----------------+ | - Shutdown |
| +----------------+
v
+----------------+
| Flush Process |
|----------------|
| - Batch Events |
| - Send to API |
| - Process |
| Response |
+----------------+
/ \
/ \
v v
+---------------------------+---------------------------+
| On Request Failure | On Request Success |
|---------------------------|---------------------------|
| - Double interval | - Halve interval |
| (max: 60000ms) | (min: 1000ms) |
| - Retry errors | - No specific limit |
| up to 5 times | flush mechanism |
+---------------------------+---------------------------+
```
### Support
If you have trouble with a Server Core SDK - we'd love to hear your feedback. Reach out in our [Slack](https://statsig.com/slack) and we'll do our best to improve your experience!
# Java Server SDK
Source: https://docs.statsig.com/server-core/java-core
Statsig's next-generation Java and Kotlin Server SDK built on the Server Core framework, with improved performance and a unified evaluation engine for JVM.
Java Core on Github
Migrating from the Legacy Java SDK? See our [Migration Guide](/server-core/migration-guides/java).
## Setup the SDK
## Requirements
* Java 8 or higher (Java 8 support added in version 0.4.3)
* Compatible with all platforms listed in the Supported OS and Architecture Combinations section, including:
* macOS (x86\_64, arm64)
* Windows (x86\_64)
* Amazon Linux 2 and 2023 (x86\_64, arm64)
## Overview
The Statsig Java SDK can be installed in two ways:
**Recommended: Single JAR installation** (since version 0.4.0)
* Use the "uber" JAR which contains both the core library and popular platform-specific native libraries in a single package
* Simplifies dependency management and deployment across different environments
**Advanced: Two-part installation**
1. The platform-independent core library
2. An OS/architecture-specific native library for your specific platform
## Installation Steps
### Recommended: Using the Uber JAR (All-in-One)
Since version 0.4.0, Statsig provides an "uber" JAR that contains both the core library and native libraries for popular supported platforms in a single package. This is the recommended approach for most users.
```groovy Gradle theme={null}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.statsig:javacore:X.X.X:uber' // Uber JAR with all native libraries
}
```
```xml Maven theme={null}
com.statsig
javacore
X.X.X
uber
```
You can find the latest version on [Maven Central](https://central.sonatype.com/artifact/com.statsig/javacore).
The uber JAR includes native libraries for:
* Linux (x86\_64, arm64)
* macOS (x86\_64, arm64)
* Windows (x86\_64)
This approach eliminates the need to specify the exact platform and simplifies deployment across different environments.
### Advanced: Platform-Specific Installation
If you need more control over dependencies or want to minimize the JAR size for a specific platform, you can use the platform-specific installation approach.
```groovy Gradle theme={null}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.statsig:javacore:X.X.X' // Replace X.X.X with the latest version
}
```
```xml Maven theme={null}
com.statsig
javacore
X.X.X
```
You can find the latest version on [Maven Central](https://central.sonatype.com/artifact/com.statsig/javacore).
You need to add the appropriate OS/architecture-specific dependency. Choose one of the following methods:
**Method 1: Automatic Detection**
Run the following code to detect your system and get the appropriate dependency:
```java theme={null}
import com.statsig.*;
// All StatsigOptions are optional, feel free to adjust them as needed
StatsigOptions options = new StatsigOptions.Builder().build();
Statsig statsig = new Statsig("your-secret-key", options);
```
You'll receive output similar to:
```
For Linux with arm64 architecture, add the following to build.gradle:
implementation 'com.statsig:javacore::aarch64-unknown-linux-gnu'
For Linux with x86_64 architecture, add the following to build.gradle:
implementation 'com.statsig:javacore::x86_64-unknown-linux-gnu'
```
**Method 2: Manual Configuration**
```groovy Gradle theme={null}
dependencies {
implementation 'com.statsig:javacore:X.X.X' // Core SDK (from Step 1)
implementation 'com.statsig:javacore:X.X.X:YOUR-OS-ARCHITECTURE' // OS/architecture-specific dependency
}
```
```xml Maven theme={null}
com.statsig
javacore
X.X.X
com.statsig
javacore
X.X.X
YOUR-OS-ARCHITECTURE
```
Replace `YOUR-OS-ARCHITECTURE` with one of the supported combinations from the Supported OS and Architecture Combinations section.
**Docker Considerations for Alpine Linux**
When using Alpine Linux or other musl-based Docker containers, you need to install additional compatibility packages for the native libraries to work properly. Add the following to your Dockerfile:
```dockerfile theme={null}
RUN apk add --no-cache libgcc gcompat
```
The Statsig Java Core SDK automatically detects musl-based systems and will use the appropriate musl-compatible native libraries (e.g., `x86_64-unknown-linux-musl`, `aarch64-unknown-linux-musl`).
Docker base images where the Java Core SDK has been tested and verified:
| Docker Base Image | Description |
| ------------------------------------------- | -------------------------------------- |
| amazoncorretto:21 | Amazon Corretto 21 JDK |
| amazoncorretto:21-alpine-jdk | Amazon Corretto 21 JDK on Alpine Linux |
| amazonlinux:2 | Amazon Linux 2 |
| public.ecr.aws/amazonlinux/amazonlinux:2023 | Amazon Linux 2023 |
| azul/zulu-openjdk-alpine:21 | Azul Zulu OpenJDK 21 on Alpine Linux |
| azul/zulu-openjdk:21 | Azul Zulu OpenJDK 21 |
| eclipse-temurin:21-jdk | Eclipse Temurin 21 JDK |
| eclipse-temurin:21-jdk-alpine | Eclipse Temurin 21 JDK on Alpine Linux |
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
```java Java theme={null}
import com.statsig.*;
// All StatsigOptions are optional, feel free to adjust them as needed
StatsigOptions options = new StatsigOptions.Builder()
.setSpecsSyncIntervalMs(10000)
.setEventLoggingFlushIntervalMs(10000)
.setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
.build();
Statsig myStatsigServer = new Statsig(SECRET_KEY, options);
myStatsigServer.initialize().get();
```
```kotlin Kotlin theme={null}
import com.statsig.*
// All StatsigOptions are optional, feel free to adjust them as needed
val options = StatsigOptions.Builder()
.setSpecsSyncIntervalMs(10000)
.setEventLoggingFlushIntervalMs(10000)
.setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
.build()
val myStatsigServer = Statsig(SECRET_KEY, options)
myStatsigServer.initialize().get()
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Getting Started
### Quick Start Example
Create a new Gradle or Maven project with the following structure:
```
my-statsig-app/
├── build.gradle (or pom.xml)
└── src/main/java/ExampleApp.java
```
```groovy build.gradle theme={null}
plugins {
id 'java'
id 'application'
}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.statsig:javacore:X.X.X:uber'
}
application {
mainClass = 'ExampleApp'
}
```
```xml pom.xml theme={null}
4.0.0
com.example
my-statsig-app
1.0-SNAPSHOT
com.statsig
javacore
X.X.X
uber
org.codehaus.mojo
exec-maven-plugin
3.0.0
ExampleApp
```
Replace `X.X.X` with the latest version from [Maven Central](https://central.sonatype.com/artifact/com.statsig/javacore).
```java ExampleApp.java theme={null}
import com.statsig.*;
public class ExampleApp {
public static void main(String[] args) throws Exception {
// Initialize Statsig
StatsigOptions options = new StatsigOptions.Builder().build();
Statsig statsig = new Statsig("YOUR_SERVER_SECRET_KEY", options);
statsig.initialize().get();
try {
// Check a feature gate
boolean isEnabled = statsig.checkGate("user123", "my_feature_gate");
System.out.println("Feature gate is " + (isEnabled ? "enabled" : "disabled"));
// Get a config
DynamicConfig config = statsig.getConfig("user123", "my_config");
System.out.println("Config value: " + config.getString("some_parameter", "default_value"));
} finally {
// Always shutdown Statsig when done
statsig.shutdown();
}
}
}
```
```kotlin ExampleApp.kt theme={null}
import com.statsig.*
fun main() {
// Initialize Statsig
val options = StatsigOptions.Builder().build()
val statsig = Statsig("YOUR_SERVER_SECRET_KEY", options)
statsig.initialize().get()
try {
// Check a feature gate
val isEnabled = statsig.checkGate("user123", "my_feature_gate")
println("Feature gate is ${if (isEnabled) "enabled" else "disabled"}")
// Get a config
val config = statsig.getConfig("user123", "my_config")
println("Config value: ${config.getString("some_parameter", "default_value")}")
} finally {
// Always shutdown Statsig when done
statsig.shutdown().get()
}
}
```
Replace `YOUR_SERVER_SECRET_KEY` with your actual server secret key from the [Statsig Console](https://console.statsig.com/).
```bash Gradle theme={null}
./gradlew run
```
```bash Maven theme={null}
mvn compile exec:java
```
If everything is set up correctly, you should see output related to your feature gate and configuration.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```java Java theme={null}
String userID = "user_id";
boolean result = statsig.checkGate(userID, "my_feature_gate");
// with StatsigUser
StatsigUser user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build();
boolean gateResult = statsig.checkGate(user, "my_feature_gate");
```
```kotlin Kotlin theme={null}
val userID = "user_id"
val result = statsig.checkGate(userID, "my_feature_gate")
// with StatsigUser
val user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build()
val gateResult = statsig.checkGate(user, "my_feature_gate")
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```java Java theme={null}
String userID = "user_id";
DynamicConfig config = statsig.getConfig(userID, "my_config");
String name = config.getString("name", "");
int size = config.getInt("size", 10);
// with StatsigUser
StatsigUser user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build();
DynamicConfig dynamicConfig = statsig.getConfig(user, "my_config");
```
```kotlin Kotlin theme={null}
val userID = "user_id"
val config = statsig.getConfig(userID, "my_config")
val name = config.getString("name", "")
val size = config.getInt("size", 10)
// with StatsigUser
val user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build()
val dynamicConfig = statsig.getConfig(user, "my_config")
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```java Java theme={null}
String userID = "user_id";
// Getting an Experiment
Experiment experiment = statsig.getExperiment(userID, "my_experiment");
String expName = experiment.getString("experiment_param", "");
// Getting a Layer
Layer layer = statsig.getLayer(userID, "my_layer");
String layerValue = layer.getString("layer_param", "default");
// with StatsigUser
StatsigUser user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build();
Experiment experimentWithUser = statsig.getExperiment(user, "my_experiment");
Layer layerWithUser = statsig.getLayer(user, "my_layer");
```
```kotlin Kotlin theme={null}
val userID = "user_id"
// Getting an Experiment
val experiment = statsig.getExperiment(userID, "my_experiment")
val expName = experiment.getString("experiment_param", "")
// Getting a Layer
val layer = statsig.getLayer(userID, "my_layer")
val layerValue = layer.getString("layer_param", "default")
// with StatsigUser
val user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build()
val experimentWithUser = statsig.getExperiment(user, "my_experiment")
val layerWithUser = statsig.getLayer(user, "my_layer")
```
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```java Java theme={null}
String userID = "user_id";
FeatureGate gate = statsig.getFeatureGate(userID, "my_feature_gate");
System.out.println("Gate name: " + gate.name);
System.out.println("Gate value: " + gate.value);
System.out.println("Rule ID: " + gate.ruleID);
// with StatsigUser
StatsigUser user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build();
FeatureGate gateWithUser = statsig.getFeatureGate(user, "my_feature_gate");
```
```kotlin Kotlin theme={null}
val userID = "user_id"
val gate = statsig.getFeatureGate(userID, "my_feature_gate")
println("Gate name: ${gate.name}")
println("Gate value: ${gate.value}")
println("Rule ID: ${gate.ruleID}")
// with StatsigUser
val user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build()
val gateWithUser = statsig.getFeatureGate(user, "my_feature_gate")
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
```java Java theme={null}
String userID = "user_id";
ParameterStore store = statsig.getParameterStore(userID, "my_param_store");
String stringValue = store.getString("string_param", "default");
int intValue = store.getInt("int_param", 0);
boolean boolValue = store.getBoolean("bool_param", false);
double doubleValue = store.getDouble("double_param", 0.0);
// with StatsigUser
StatsigUser user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build();
ParameterStore storeWithUser = statsig.getParameterStore(user, "my_param_store");
```
```kotlin Kotlin theme={null}
val userID = "user_id"
val store = statsig.getParameterStore(userID, "my_param_store")
val stringValue = store.getString("string_param", "default")
val intValue = store.getInt("int_param", 0)
val boolValue = store.getBoolean("bool_param", false)
val doubleValue = store.getDouble("double_param", 0.0)
// with StatsigUser
val user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build()
val storeWithUser = statsig.getParameterStore(user, "my_param_store")
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```java Java theme={null}
import java.util.HashMap;
import java.util.Map;
String userID = "user_id";
String eventName = "my_custom_event";
// Simple event
statsig.logEvent(userID, eventName);
// Event with value
statsig.logEvent(userID, eventName, 10.5);
// Event with metadata
Map metadata = new HashMap<>();
metadata.put("key1", "value1");
metadata.put("key2", "value2");
statsig.logEvent(userID, eventName, metadata);
// Event with value and metadata
statsig.logEvent(userID, eventName, 10.5, metadata);
// with StatsigUser
StatsigUser user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build();
statsig.logEvent(user, eventName, 10.5, metadata);
```
```kotlin Kotlin theme={null}
val userID = "user_id"
val eventName = "my_custom_event"
// Simple event
statsig.logEvent(userID, eventName)
// Event with value
statsig.logEvent(userID, eventName, 10.5)
// Event with metadata
val metadata = mapOf(
"key1" to "value1",
"key2" to "value2"
)
statsig.logEvent(userID, eventName, metadata)
// Event with value and metadata
statsig.logEvent(userID, eventName, 10.5, metadata)
// with StatsigUser
val user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build()
statsig.logEvent(user, eventName, 10.5, metadata)
```
### Sending Events to Log Explorer
You can forward logs to Logs Explorer for convenient analysis using the Forward Log Line Event API. This lets you include custom metadata and event values with each log.
```java Java theme={null}
import java.util.HashMap;
import java.util.Map;
String userID = "user_id";
Map payload = new HashMap<>();
payload.put("log_level", "error");
payload.put("message", "Something went wrong");
payload.put("timestamp", System.currentTimeMillis());
statsig.forwardLogLineEvent(userID, payload);
// with StatsigUser
StatsigUser user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build();
statsig.forwardLogLineEvent(user, payload);
```
```kotlin Kotlin theme={null}
val userID = "user_id"
val payload = mapOf(
"log_level" to "error",
"message" to "Something went wrong",
"timestamp" to System.currentTimeMillis()
)
statsig.forwardLogLineEvent(userID, payload)
// with StatsigUser
val user = StatsigUser.builder()
.userID("user_id")
.email("my_user@example.com")
.build()
statsig.forwardLogLineEvent(user, payload)
```
## Using Shared Instance
In some applications, you may want to create a single Statsig instance that can be accessed globally throughout your codebase. The shared instance functionality provides a singleton pattern for this purpose:
```java Java theme={null}
import com.statsig.*;
// Create a shared instance that can be accessed globally
StatsigServer statsig = Statsig.newShared("secret-key");
statsig.initialize().get();
// Access the shared instance from anywhere in your code
StatsigServer sharedStatsig = Statsig.shared();
boolean isFeatureEnabled = sharedStatsig.checkGate(user, "feature_name");
// Check if a shared instance exists
if (Statsig.hasSharedInstance()) {
// Use the shared instance
}
// Remove the shared instance when no longer needed
Statsig.removeShared();
```
```kotlin Kotlin theme={null}
import com.statsig.*
// Create a shared instance that can be accessed globally
val statsig = Statsig.newShared("secret-key")
statsig.initialize().get()
// Access the shared instance from anywhere in your code
val sharedStatsig = Statsig.shared()
val isFeatureEnabled = sharedStatsig.checkGate(user, "feature_name")
// Check if a shared instance exists
if (Statsig.hasSharedInstance()) {
// Use the shared instance
}
// Remove the shared instance when no longer needed
Statsig.removeShared()
```
The shared instance functionality provides a singleton pattern where a single Statsig instance can be created and accessed globally throughout your application. This is useful for applications that need to access Statsig functionality from multiple parts of the codebase without having to pass around a Statsig instance.
* `Statsig.newShared(sdkKey, options)`: Creates a new shared instance of Statsig that can be accessed globally
* `Statsig.shared()`: Returns the shared instance
* `Statsig.hasSharedInstance()`: Checks if a shared instance exists (useful when you aren't sure if the shared instance is ready yet)
* `Statsig.removeShared()`: Removes the shared instance (useful when you want to switch to a new shared instance)
`hasSharedInstance()` and `removeShared()` are helpful in specific scenarios but aren't required in most use cases where the shared instance is set up near the top of your application.
Also note that only one shared instance can exist at a time. Attempting to create a second shared instance will result in an error.
## Manual Exposures
By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or call get() on a parameter in a layer. However, there are times when you may want to log an exposure event manually. For example, if you're using a gate to control access to a feature, but you don't want to log an exposure until the user actually uses the feature, you can use manual exposures.
Manual exposures allow you to control when exposure events are logged. This is useful when you want to delay exposure logging until certain conditions are met.
```java Java theme={null}
String userID = "user_id";
// Check gate without logging exposure
boolean result = statsig.checkGateWithExposureLoggingDisabled(userID, "my_feature_gate");
// Manually log the exposure when ready
statsig.manuallyLogGateExposure(userID, "my_feature_gate");
// Works with configs too
DynamicConfig config = statsig.getConfigWithExposureLoggingDisabled(userID, "my_config");
statsig.manuallyLogConfigExposure(userID, "my_config");
// And with experiments/layers
Experiment experiment = statsig.getExperimentWithExposureLoggingDisabled(userID, "my_experiment");
statsig.manuallyLogExperimentExposure(userID, "my_experiment");
Layer layer = statsig.getLayerWithExposureLoggingDisabled(userID, "my_layer");
statsig.manuallyLogLayerParameterExposure(userID, "my_layer", "parameter_name");
```
```kotlin Kotlin theme={null}
val userID = "user_id"
// Check gate without logging exposure
val result = statsig.checkGateWithExposureLoggingDisabled(userID, "my_feature_gate")
// Manually log the exposure when ready
statsig.manuallyLogGateExposure(userID, "my_feature_gate")
// Works with configs too
val config = statsig.getConfigWithExposureLoggingDisabled(userID, "my_config")
statsig.manuallyLogConfigExposure(userID, "my_config")
// And with experiments/layers
val experiment = statsig.getExperimentWithExposureLoggingDisabled(userID, "my_experiment")
statsig.manuallyLogExperimentExposure(userID, "my_experiment")
val layer = statsig.getLayerWithExposureLoggingDisabled(userID, "my_layer")
statsig.manuallyLogLayerParameterExposure(userID, "my_layer", "parameter_name")
```
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
The `StatsigUser` object represents a user in your application and contains fields used for feature evaluation.
```java Java theme={null}
import com.statsig.*;
import java.util.HashMap;
import java.util.Map;
// Build a user with various fields
Map customFields = new HashMap<>();
customFields.put("plan", "premium");
customFields.put("age", 25);
Map privateAttributes = new HashMap<>();
privateAttributes.put("internal_id", "123456");
StatsigUser user = StatsigUser.builder()
.userID("user_123")
.email("user@example.com")
.ip("192.168.1.1")
.userAgent("Mozilla/5.0...")
.country("US")
.locale("en_US")
.appVersion("1.2.3")
.custom(customFields)
.privateAttributes(privateAttributes)
.build();
// Use the user for evaluation
boolean result = statsig.checkGate(user, "my_feature_gate");
```
```kotlin Kotlin theme={null}
import com.statsig.*
// Build a user with various fields
val customFields = mapOf(
"plan" to "premium",
"age" to 25
)
val privateAttributes = mapOf(
"internal_id" to "123456"
)
val user = StatsigUser.builder()
.userID("user_123")
.email("user@example.com")
.ip("192.168.1.1")
.userAgent("Mozilla/5.0...")
.country("US")
.locale("en_US")
.appVersion("1.2.3")
.custom(customFields)
.privateAttributes(privateAttributes)
.build()
// Use the user for evaluation
val result = statsig.checkGate(user, "my_feature_gate")
```
## Private Attributes
Private attributes are fields that will be used for evaluation but will not be logged in events sent to Statsig servers.
```java Java theme={null}
Map privateAttributes = new HashMap<>();
privateAttributes.put("sensitive_field", "sensitive_value");
StatsigUser user = StatsigUser.builder()
.userID("user_123")
.privateAttributes(privateAttributes)
.build();
```
```kotlin Kotlin theme={null}
val privateAttributes = mapOf(
"sensitive_field" to "sensitive_value"
)
val user = StatsigUser.builder()
.userID("user_123")
.privateAttributes(privateAttributes)
.build()
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
Environment parameter for evaluation.
Custom URL for fetching feature specifications.
How often the SDK updates specifications from Statsig servers (in milliseconds).
Turn this on if you are proxying `download_config_specs` / `get_id_lists` and want to fall back to the default Statsig endpoint to increase reliability.
Custom URL for logging events.
If true, the SDK will not collect any logging within the session, including custom events and config check exposure events.
Required to be `true` when using segments with more than 1000 IDs.
If true, the SDK will not parse User-Agent strings into `browserName`, `browserVersion`, `systemName`, `systemVersion`, and `appVersion` when needed for evaluation.
If true, the SDK will not parse IP addresses (from `user.ip`) into country codes when needed for evaluation.
How often events are flushed to Statsig servers (in milliseconds).
Maximum number of events to queue before forcing a flush.
An adapter with custom storage behavior for config specs. Can also continuously fetch updates in place of the Statsig network.
Configuration for connecting through an outbound HTTP proxy.
Advanced configuration for fetching specs from multiple sources or protocols, including [Statsig Forward Proxy](/infrastructure/forward-proxy) over gRPC websocket streaming.
Each `SpecAdapterConfig` can set:
* `adapterType`: one of `SpecAdapterType.DATA_STORE`, `SpecAdapterType.NETWORK_HTTP`, or `SpecAdapterType.NETWORK_GRPC_WEBSOCKET`
* `specsUrl`: optional endpoint override for the adapter
* `initTimeoutMs`: optional initialization timeout in milliseconds
* `authenticationMode`: optional transport auth mode via `AuthenticationMode.NONE`, `AuthenticationMode.TLS`, or `AuthenticationMode.MTLS`
* `caCertPath`, `clientCertPath`, `clientKeyPath`, `domainName`: optional TLS and mTLS fields for gRPC websocket connections
Interface to use persistent storage within the SDK.
Set the logging level for the SDK. Options: `NONE`, `ERROR`, `WARN`, `INFO`, `DEBUG`.
Interface to integrate observability metrics exposed by the SDK.
***
```java Java theme={null}
// Example usage
StatsigOptions options = new StatsigOptions.Builder()
.setEnvironment("staging")
.setSpecsSyncIntervalMs(10000)
.setEventLoggingFlushIntervalMs(5000)
.setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
.build();
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();
```
```kotlin Kotlin theme={null}
// Example usage
val options = StatsigOptions.Builder()
.setEnvironment("staging")
.setSpecsSyncIntervalMs(10000)
.setEventLoggingFlushIntervalMs(5000)
.setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
.build()
val statsig = Statsig("secret-key", options)
statsig.initialize().get()
```
### Proxy and Custom Network Routing
Use `setProxyConfig(ProxyConfig)` if your service needs a standard outbound HTTP proxy for Statsig network calls. Use `setSpecAdapterConfigs(...)` if you are routing spec downloads through [Statsig Forward Proxy](/infrastructure/forward-proxy).
```java theme={null}
ProxyConfig proxyConfig = new ProxyConfig();
proxyConfig.setProxyHost("proxy.example.com");
proxyConfig.setProxyPort(8080);
proxyConfig.setProxyProtocol("https");
proxyConfig.setCaCertPath("/etc/ssl/certs/corporate-ca.pem"); // Optional
StatsigOptions options =
new StatsigOptions.Builder()
.setProxyConfig(proxyConfig)
.build();
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();
```
`ProxyConfig` supports `proxyHost`, `proxyPort`, `proxyAuth`, `proxyProtocol`, and `caCertPath`. Set `caCertPath` when your environment requires a custom PEM CA bundle for outbound TLS.
### Statsig Forward Proxy Example
```java theme={null}
import java.util.Collections;
SpecAdapterConfig forwardProxyConfig =
new SpecAdapterConfig()
.setAdapterType(SpecAdapterType.NETWORK_GRPC_WEBSOCKET)
.setSpecsUrl("http://forward-proxy.internal:50051")
.setAuthenticationMode(AuthenticationMode.NONE);
StatsigOptions options =
new StatsigOptions.Builder()
.setSpecAdapterConfigs(Collections.singletonList(forwardProxyConfig))
.setFallbackToStatsigApi(true)
.build();
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();
```
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```java Java theme={null}
// Shutdown flushes all pending events and stops background tasks
statsig.shutdown();
// Or with a timeout (blocks until shutdown completes or timeout)
statsig.shutdown().get(5, TimeUnit.SECONDS);
```
```kotlin Kotlin theme={null}
// Shutdown flushes all pending events and stops background tasks
statsig.shutdown()
// Or with a timeout (blocks until shutdown completes or timeout)
statsig.shutdown().get(5, TimeUnit.SECONDS)
```
## Local Overrides
Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console.
Local overrides allow you to override feature gate and config values for testing purposes.
```java Java theme={null}
import java.util.HashMap;
import java.util.Map;
// Override a gate
statsig.overrideGate("my_feature_gate", true);
// Override a config
Map configOverride = new HashMap<>();
configOverride.put("key", "value");
configOverride.put("number", 42);
statsig.overrideConfig("my_config", configOverride);
// Override an experiment
Map experimentOverride = new HashMap<>();
experimentOverride.put("variant", "test");
statsig.overrideExperiment("my_experiment", experimentOverride);
// Override an experiment to a particular groupname
statsig.overrideExperimentByGroupName("my_experiment", "a_group_name");
statsig.overrideExperimentByGroupName("my_experiment", "a_group_name", "user_123");
// Override a layer
Map layerOverride = new HashMap<>();
layerOverride.put("layer_param", "override_value");
statsig.overrideLayer("my_layer", layerOverride);
// Clear all overrides
statsig.clearAllOverrides();
// Clear specific override
statsig.clearGateOverride("my_feature_gate");
statsig.clearConfigOverride("my_config");
```
```kotlin Kotlin theme={null}
// Override a gate
statsig.overrideGate("my_feature_gate", true)
// Override a config
val configOverride = mapOf(
"key" to "value",
"number" to 42
)
statsig.overrideConfig("my_config", configOverride)
// Override an experiment
val experimentOverride = mapOf(
"variant" to "test"
)
statsig.overrideExperiment("my_experiment", experimentOverride)
// Override an experiment to a particular groupname
statsig.overrideExperimentByGroupName("my_experiment", "a_group_name")
statsig.overrideExperimentByGroupName("my_experiment", "a_group_name", "user_123")
// Override a layer
val layerOverride = mapOf(
"layer_param" to "override_value"
)
statsig.overrideLayer("my_layer", layerOverride)
// Clear all overrides
statsig.clearAllOverrides()
// Clear specific override
statsig.clearGateOverride("my_feature_gate")
statsig.clearConfigOverride("my_config")
```
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant.
Persistent storage allows the SDK to persist sticky experiment assignments for users, ensuring they see consistent experiment variants across sessions.
```java Java theme={null}
import com.statsig.*;
import java.util.HashMap;
import java.util.Map;
class MyPersistentStorage implements PersistentStorage {
private Map> storage = new HashMap<>();
@Override
public Map load(String key) {
// Load persisted sticky values for the given key
// Key format is "{userId}:userID" or "{customId}:{idType}"
return storage.get(key);
}
@Override
public void save(String key, String configName, StickyValues data) {
// Save sticky values for a specific experiment/config
storage.computeIfAbsent(key, k -> new HashMap<>()).put(configName, data);
}
@Override
public void delete(String key, String configName) {
// Delete sticky values for a specific experiment/config
Map values = storage.get(key);
if (values != null) {
values.remove(configName);
}
}
}
// Use persistent storage
StatsigOptions options = new StatsigOptions.Builder()
.setPersistentStorage(new MyPersistentStorage())
.build();
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();
```
```kotlin Kotlin theme={null}
import com.statsig.*
class MyPersistentStorage : PersistentStorage {
private val storage = mutableMapOf>()
override fun load(key: String): Map? {
// Load persisted sticky values for the given key
// Key format is "{userId}:userID" or "{customId}:{idType}"
return storage[key]
}
override fun save(key: String, configName: String, data: StickyValues) {
// Save sticky values for a specific experiment/config
storage.getOrPut(key) { mutableMapOf() }[configName] = data
}
override fun delete(key: String, configName: String) {
// Delete sticky values for a specific experiment/config
storage[key]?.remove(configName)
}
}
// Use persistent storage
val options = StatsigOptions.Builder()
.setPersistentStorage(MyPersistentStorage())
.build()
val statsig = Statsig("secret-key", options)
statsig.initialize().get()
```
### Helper methods
The `PersistentStorage` interface provides helper methods for working with user-based storage keys:
```java theme={null}
// Get persisted values for a user using the helper method
Map values = persistentStorage.getValuesForUser(user, "userID");
// Generate a storage key from a user and ID type
String key = PersistentStorage.getStorageKey(user, "userID"); // Returns "{userId}:userID"
String customKey = PersistentStorage.getStorageKey(user, "companyID"); // Returns "{companyId}:companyID"
```
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
Data stores allow you to customize how the SDK fetches and caches feature specifications, enabling advanced use cases like using Redis or other distributed caches.
```java Java theme={null}
import com.statsig.*;
class MyDataStore implements DataStore {
@Override
public String getDataSync(String key) {
// Synchronously fetch data for the given key
// This is called during SDK evaluation
return null;
}
@Override
public CompletableFuture setData(String key, String data) {
// Store data for the given key
// Called when SDK receives updates from Statsig
return CompletableFuture.completedFuture(null);
}
@Override
public CompletableFuture initialize() {
// Perform any initialization needed for your data store
return CompletableFuture.completedFuture(null);
}
@Override
public void shutdown() {
// Clean up resources
}
}
// Use data store
StatsigOptions options = new StatsigOptions.Builder()
.setDataStore(new MyDataStore())
.build();
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();
```
```kotlin Kotlin theme={null}
import com.statsig.*
import java.util.concurrent.CompletableFuture
class MyDataStore : DataStore {
override fun getDataSync(key: String): String? {
// Synchronously fetch data for the given key
// This is called during SDK evaluation
return null
}
override fun setData(key: String, data: String): CompletableFuture {
// Store data for the given key
// Called when SDK receives updates from Statsig
return CompletableFuture.completedFuture(null)
}
override fun initialize(): CompletableFuture {
// Perform any initialization needed for your data store
return CompletableFuture.completedFuture(null)
}
override fun shutdown() {
// Clean up resources
}
}
// Use data store
val options = StatsigOptions.Builder()
.setDataStore(MyDataStore())
.build()
val statsig = Statsig("secret-key", options)
statsig.initialize().get()
```
## Custom Output Logger
The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity.
Custom output logger allows you to redirect SDK logs to your own logging system.
```java Java theme={null}
import com.statsig.*;
class MyOutputLogger implements OutputLogger {
@Override
public void log(LogLevel level, String message) {
// Route SDK logs to your logging system
switch (level) {
case ERROR:
System.err.println("[ERROR] " + message);
break;
case WARN:
System.out.println("[WARN] " + message);
break;
case INFO:
System.out.println("[INFO] " + message);
break;
case DEBUG:
System.out.println("[DEBUG] " + message);
break;
}
}
}
// Use custom output logger
StatsigOptions options = new StatsigOptions.Builder()
.setOutputLogger(new MyOutputLogger())
.setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
.build();
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();
```
```kotlin Kotlin theme={null}
import com.statsig.*
class MyOutputLogger : OutputLogger {
override fun log(level: OutputLogger.LogLevel, message: String) {
// Route SDK logs to your logging system
when (level) {
OutputLogger.LogLevel.ERROR -> println("[ERROR] $message")
OutputLogger.LogLevel.WARN -> println("[WARN] $message")
OutputLogger.LogLevel.INFO -> println("[INFO] $message")
OutputLogger.LogLevel.DEBUG -> println("[DEBUG] $message")
else -> {}
}
}
}
// Use custom output logger
val options = StatsigOptions.Builder()
.setOutputLogger(MyOutputLogger())
.setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
.build()
val statsig = Statsig("secret-key", options)
statsig.initialize().get()
```
## Observability Client
The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the [Monitoring documentation](/sdk_monitoring).
Observability client allows you to monitor SDK performance and emit custom metrics.
```java Java theme={null}
import com.statsig.*;
class MyObservabilityClient implements ObservabilityClient {
@Override
public void emitMetric(String metricName, double value, Map tags) {
// Send metric to your monitoring system
System.out.println("Metric: " + metricName + " = " + value + ", tags: " + tags);
}
@Override
public void startTimer(String operationName) {
// Start timing an operation
}
@Override
public void endTimer(String operationName, Map tags) {
// End timing and emit duration metric
}
}
// Use observability client
StatsigOptions options = new StatsigOptions.Builder()
.setObservabilityClient(new MyObservabilityClient())
.build();
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();
```
```kotlin Kotlin theme={null}
import com.statsig.*
class MyObservabilityClient : ObservabilityClient {
override fun emitMetric(metricName: String, value: Double, tags: Map) {
// Send metric to your monitoring system
println("Metric: $metricName = $value, tags: $tags")
}
override fun startTimer(operationName: String) {
// Start timing an operation
}
override fun endTimer(operationName: String, tags: Map) {
// End timing and emit duration metric
}
}
// Use observability client
val options = StatsigOptions.Builder()
.setObservabilityClient(MyObservabilityClient())
.build()
val statsig = Statsig("secret-key", options)
statsig.initialize().get()
```
## FAQ
The Java Core SDK supports Java 8 and higher. Java 8 support was added in version 0.4.3.
The SDK supports:
* Linux (x86\_64, arm64, musl variants)
* macOS (x86\_64, arm64)
* Windows (x86\_64)
See the Tested Platforms section for verified Docker images.
The uber JAR is recommended for most use cases as it includes native libraries for all popular platforms and simplifies deployment. Use platform-specific JARs only if you need to minimize JAR size or have specific dependency requirements.
For Alpine Linux (musl-based systems), install compatibility packages:
```dockerfile theme={null}
RUN apk add --no-cache libgcc gcompat
```
The SDK will automatically use musl-compatible native libraries.
The SDK initialization is asynchronous. Use `.get()` on the CompletableFuture to wait for initialization:
```java theme={null}
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get(); // Blocks until initialized
```
Always call `shutdown()` when your application terminates to flush pending events.
Yes, you can create multiple Statsig instances with different configurations. You can also use the global singleton with `Statsig.getGlobalSingleton()` for convenience.
Set the output logger level to DEBUG to see detailed logs:
```java theme={null}
StatsigOptions options = new StatsigOptions.Builder()
.setOutputLoggerLevel(OutputLogger.LogLevel.DEBUG)
.build();
```
## Reference
### FeatureGate Class
```java theme={null}
class FeatureGate {
String name; // Gate name
boolean value; // Evaluation boolean result
String ruleID; // Rule ID for this gate
EvaluationDetails evaluationDetails; // Evaluation details
String rawJson; // Raw JSON string representation
}
```
### Experiment Class
```java theme={null}
class Experiment {
String name; // Name of the experiment
String ruleID; // ID of the rule used in the experiment
Map value; // Configuration values specific to the experiment
String groupName; // The group name the user falls into
EvaluationDetails evaluationDetails; // Details about how the experiment was evaluated
String rawJson; // Raw JSON representation of the experiment
}
```
**Methods for Experiment:**
```java theme={null}
public String getString(String key, String fallbackValue)
public boolean getBoolean(String key, Boolean fallbackValue)
public double getDouble(String key, double fallbackValue)
public int getInt(String key, int fallbackValue)
public long getLong(String key, long fallbackValue)
public Object[] getArray(String key, Object[] fallbackValue)
public Map getMap(String key, Map fallbackValue)
```
### DynamicConfig Class
```java theme={null}
class DynamicConfig {
String name; // Name of the config
String ruleID; // ID of the rule used
Map value; // Configuration values
EvaluationDetails evaluationDetails; // Details about how the config was evaluated
String rawJson; // Raw JSON representation
}
```
**Methods for DynamicConfig:**
```java theme={null}
public String getString(String key, String fallbackValue)
public boolean getBoolean(String key, Boolean fallbackValue)
public double getDouble(String key, double fallbackValue)
public int getInt(String key, int fallbackValue)
public long getLong(String key, long fallbackValue)
public Object[] getArray(String key, Object[] fallbackValue)
public Map getMap(String key, Map fallbackValue)
```
### Layer Class
```java theme={null}
class Layer {
String name; // Layer name
String ruleID; // Rule ID for this layer
String groupName; // Group name
Map value; // Layer values
String allocatedExperimentName; // Allocated experiment name
EvaluationDetails evaluationDetails; // Evaluation details
String rawJson; // Raw JSON string representation
}
```
**Methods for Layer:**
```java theme={null}
public String getString(String key, String fallbackValue)
public boolean getBoolean(String key, Boolean fallbackValue)
public double getDouble(String key, double fallbackValue)
public int getInt(String key, int fallbackValue)
public long getLong(String key, long fallbackValue)
public Object[] getArray(String key, Object[] fallbackValue)
public Map getMap(String key, Map fallbackValue)
```
### Fields Needed Methods (Enterprise Only)
This is available for Enterprise contracts. Please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
These methods allow you to retrieve a list of user fields that are used in the targeting rules for gates, configs, experiments, and layers.
```java theme={null}
// Get user fields needed for a gate evaluation
List getFieldsNeededForGate(String gateName)
// Get user fields needed for a dynamic config evaluation
List getFieldsNeededForDynamicConfig(String configName)
// Get user fields needed for an experiment evaluation
List getFieldsNeededForExperiment(String experimentName)
// Get user fields needed for a layer evaluation
List getFieldsNeededForLayer(String layerName)
```
**Field Mapping**
The fields returned by these methods correspond to the following user properties:
```java theme={null}
// Field mapping between user properties and internal field names
userID -> "u"
email -> "e"
ip -> "i"
userAgent -> "ua"
country -> "c"
locale -> "l"
appVersion -> "a"
time -> "t"
stableID -> "s"
environment -> "en"
targetApp -> "ta"
// Custom fields are prefixed with "cf:"
// Example: "cf:plan", "cf:age"
```
# Legacy Server SDKs
Source: https://docs.statsig.com/server-core/legacy-sdks
Reference for Statsig's long-lived legacy Server SDKs that are transitioning to the Server Core framework, including supported versions and migration timelines.
Statsig is in the process of transitioning to the new Statsig Server Core architecture, which unifies all Server SDKs around a unified, performance optimized core package. We expect this model will support both superior performance and greater feature consistency across SDKs. However, the vast majority of customers continue to use Statsig's legacy SDKs, and we'll continue to support them for the foreseeable future, with the exception of major feature additions.
## Timelines
We've begun announcing end-of-life for some Legacy Server SDKs. We encourage you to explore using the [Server Core SDKs](server-core/index), which often evaluate 5-10x faster than the legacy SDKs, are more feature complete, and have other performance advantages. See docs for our existing SDKs below:
* [Node](/server/nodejsServerSDK)
* [Python](/server/pythonSDK)
* [Elixir/Erlang](/server/erlangSDK) (End of Life April 30th, 2026)
* [Java](/server/javaSdk)
* [Rust](/server/rustSDK) (End of Life April 30th, 2026)
* [Go](/server/go)
* [PHP](/server/php)
* [.NET](/server/dotnet)
# Node Server SDK
Source: https://docs.statsig.com/server-core/node-core
Statsig's next-generation Node.js Server SDK built on the Server Core framework, with improved performance and a unified evaluation engine for Node backends.
Node Core on Github ,
NPM Package
Migrating from the Legacy Node SDK? See our [Migration Guide](/server-core/migration-guides/node).
## Setup the SDK
```shell theme={null}
npm i @statsig/statsig-node-core
```
The Node SDK is pre-built and compiled for different OSs & CPU architectures. Package managers will resolve the correct version automatically.
If your service has locked dependencies with package-lock.json or pnpm-lock.yml, you'll need to include all versions you need. For example, if you develop locally on macOS, and deploy to linux, then you have to include:
```
dependencies {
"@statsig/statsig-node-core-darwin-arm64": "0.1.0" // for macOS
"@statsig/statsig-node-core-linux-x64-gnu": "0.1.0" // for linux x64 machines
}
```
`statsig-node-core` uses native binary files that can't be packaged with webpack/esbuild. To prevent errors, take the following steps:
In your `next.config.js` file, add the `@statsig/statsig-node-core` package to the `serverExternalPackages` array:
```jsx theme={null}
const nextConfig = {
serverExternalPackages: ['@statsig/statsig-node-core'],
}
```
Add the `--packages=external` flag to your build script:
```shell theme={null}
esbuild --packages=external
```
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
```jsx theme={null}
// Basic initialization
import { Statsig, StatsigUser } from '@statsig/statsig-node-core';
//Or, in common JS, const { Statsig, StatsigUser } = require('@statsig/statsig-node-core');
const statsig = new Statsig("secret-key");
await statsig.initialize();
// or with StatsigOptions
const options: StatsigOptions = { environment: "staging" };
const statsigWithOptions = new Statsig("secret-key", options);
await statsigWithOptions.initialize();
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```jsx theme={null}
const user = new StatsigUser({ userID: "a-user" });
if (statsig.checkGate(user, "a_gate")) {
// Gate is on, enable new feature
} else {
// Gate is off
}
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```jsx theme={null}
// Get the dynamic config
const config = statsig.getDynamicConfig(user, "a_config");
// Get typed values using the getValue() method
const itemName = config.getValue("product_name", "Awesome Product v1");
const price = config.getValue("price", 10.0);
const shouldDiscount = config.getValue("discount", false);
// Or access the entire value object directly
const value = config.value;
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```jsx theme={null}
// Or, via individual experiments
const titleExp = statsig.getExperiment(user, "new_user_promo_title");
const priceExp = statsig.getExperiment(user, "new_user_promo_price");
const experimentTitle = titleExp.getValue("title", "Welcome to Statsig!");
const experimentDiscount = priceExp.getValue("discount", 0.1);
// Get values via Layer
const layer = statsig.getLayer(user, "user_promo_experiments");
const title = layer.getValue("title", "Welcome to Statsig!");
const discount = layer.getValue("discount", 0.1);
```
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```jsx theme={null}
const gate = statsig.getFeatureGate(statsigUser, "example_gate")
console.log(gate.rule_id)
console.log(gate.value)
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
```jsx theme={null}
const paramStore = statsig.getParameterStore(statsigUser, "my_parameters")
const paramStoreValue = paramStore.getValue('my_parameter_value')
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```jsx theme={null}
statsig.logEvent(
user,
"add_to_cart",
null,
{
price: "9.99",
item_name: "diet_coke_48_pack"
}
);
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
### Sending Events to Log Explorer
You can forward logs to Logs Explorer for convenient analysis using the Forward Log Line Event API. This lets you include custom metadata and event values with each log.
```jsx theme={null}
const user = new StatsigUser({ userID: "a-user", custom: {
service: "my-service",
pod: "my-pod",
namespace: "my-namespace",
container: "my-container",
// ...include any service-specific metadata
} });
// levels: trace, debug, info, log, warn, error
statsig.forwardLogLineEvent(user, "warn", "script failed to load", {
cusom_metadata: "script_name:my-script"
// ... include any event-specific metadata
});
```
## Using Shared Instance
In some applications, you may want to create a single Statsig instance that can be accessed globally throughout your codebase. The shared instance functionality provides a singleton pattern for this purpose:
```jsx theme={null}
// Create a shared instance that can be accessed globally
const statsig = Statsig.newShared("secret-key");
await statsig.initialize();
// Access the shared instance from anywhere in your code
const sharedStatsig = Statsig.shared();
const isFeatureEnabled = sharedStatsig.checkGate(user, "feature_name");
// Check if a shared instance exists
if (Statsig.hasSharedInstance()) {
// Use the shared instance
}
// Remove the shared instance when no longer needed
Statsig.removeShared();
```
The shared instance functionality provides a singleton pattern where a single Statsig instance can be created and accessed globally throughout your application. This is useful for applications that need to access Statsig functionality from multiple parts of the codebase without having to pass around a Statsig instance.
* `Statsig.newShared(sdkKey, options)`: Creates a new shared instance of Statsig that can be accessed globally
* `Statsig.shared()`: Returns the shared instance
* `Statsig.hasSharedInstance()`: Checks if a shared instance exists (useful when you aren't sure if the shared instance is ready yet)
* `Statsig.removeShared()`: Removes the shared instance (useful when you want to switch to a new shared instance)
`hasSharedInstance()` and `removeShared()` are helpful in specific scenarios but aren't required in most use cases where the shared instance is set up near the top of your application.
Also note that only one shared instance can exist at a time. Attempting to create a second shared instance will result in an error.
## Manual Exposures
By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or call get() on a parameter in a layer. However, there are times when you may want to log an exposure event manually. For example, if you're using a gate to control access to a feature, but you don't want to log an exposure until the user actually uses the feature, you can use manual exposures.
All of the main SDK functions (`checkGate`, `getDynamicConfig`, `getExperiment`, `getLayer`) accept an optional `disableExposureLogging` parameter. When this is set to `true`, the SDK will not automatically log an exposure event. You can then manually log the exposure at a later time using the corresponding manual exposure logging method:
```jsx theme={null}
const result = statsig.checkGate(aUser, 'a_gate_name', {disableExposureLogging: true});
```
```jsx theme={null}
statsig.manuallyLogGateExposure(aUser, 'a_gate_name');
```
```jsx theme={null}
const config = statsig.getDynamicConfig(aUser, 'a_dynamic_config_name', {disableExposureLogging: true});
```
```jsx theme={null}
statsig.manuallyLogDynamicConfigExposure(aUser, 'a_dynamic_config_name');
```
```jsx theme={null}
const experiment = statsig.getExperiment(aUser, 'an_experiment_name', {disableExposureLogging: true});
```
```jsx theme={null}
statsig.manuallyLogExperimentExposure(aUser, 'an_experiment_name');
```
```jsx theme={null}
const layer = statsig.getLayer(aUser, 'a_layer_name', {disableExposureLogging: true});
const paramValue = layer.get('a_param_name', 'fallback_value');
```
```jsx theme={null}
statsig.manuallyLogLayerParameterExposure(aUser, 'a_layer_name', 'a_param_name');
```
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
```typescript theme={null}
const user = new StatsigUser({
userID: "a-user-id",
email: "user@example.com",
ip: "192.168.1.1",
userAgent: "Mozilla/5.0...",
country: "US",
locale: "en_US",
appVersion: "1.0.0",
custom: {
// Custom fields
plan: "premium",
age: 25
},
customIDs: {
// Custom ID types
stableID: "stable-id-123"
},
privateAttributes: {
// Private attributes not forwarded to integrations
email: "private@example.com"
}
});
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
### Parameters
Environment parameter for evaluation.
Custom URL for fetching feature specifications.
How often the SDK updates specifications from Statsig servers (in milliseconds).
Turn this on if you are proxying `download_config_specs` / `get_id_lists` and want to fall back to the default Statsig endpoint to increase reliability.
Custom URL for logging events.
If true, the SDK will not collect any logging within the session, including custom events and config check exposure events.
Required to be `true` when using segments with more than 1000 IDs. See [ID List segments](/segments/add-id-list).
If true, the SDK will not parse User-Agent strings into `browserName`, `browserVersion`, `systemName`, `systemVersion`, and `appVersion` when needed for evaluation.
When true, the SDK waits until user agent parsing data is fully loaded during initialization (\~1 second), ensuring parsing is ready before any evaluations.
If true, the SDK will not parse IP addresses (from `user.ip`) into country codes when needed for evaluation.
When true, the SDK waits for country lookup data (e.g., GeoIP or YAML files) to fully load during initialization (\~1 second), ensuring IP-to-country parsing is ready at evaluation time.
How often events are flushed to Statsig servers (in milliseconds).
Maximum number of events to queue before forcing a flush.
An adapter with custom storage behavior for config specs. Can also continuously fetch updates in place of the Statsig network. See [Data Stores](#data-store). For example, see our 1P Redis implementation [statsig-node-redis](https://github.com/statsig-io/node-js-server-sdk-redis).
Advanced settings to fetch from different sources (e.g., [statsig forward proxy](/infrastructure/forward-proxy), your own proxy server, data store) or to use different network protocols (HTTP vs gRPC streaming).
Interface to integrate observability metrics exposed by the SDK (e.g., config propagation delay, initialization time). See [details](#observability-client).
Interface to use persistent storage within the SDK. See [details](#persistent-storage).
Configuration for connecting through a proxy server.
Proxy server host.
Proxy server port.
Proxy authentication in the form "username:password".
Protocol (e.g., "http", "https").
Optional path to a PEM CA bundle for outbound TLS.
### Proxy and Custom Network Routing
Use `proxyConfig` if your service needs a standard outbound HTTP proxy. Use `specAdaptersConfig` if you are routing spec downloads through [Statsig Forward Proxy](/infrastructure/forward-proxy) or another custom spec source.
```typescript theme={null}
// Example usage:
const options = new StatsigOptions();
options.environment = "staging";
options.initTimeoutMs = 3000;
options.proxyConfig = {
proxyHost: "proxy.example.com",
proxyPort: 8080,
// proxyAuth can be set if authentication is required
proxyProtocol: "https",
caCertPath: "/etc/ssl/certs/corporate-ca.pem"
};
const statsig = new Statsig("secret-key", options);
await statsig.initialize();
```
Set `caCertPath` when your environment requires a custom PEM CA bundle for outbound TLS.
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```jsx theme={null}
await statsig.shutdown();
```
## Client SDK Bootstrapping | SSR
If you are using the Statsig client SDK in a browser or mobile app, you can bootstrap the client SDK with the values from the server SDK to avoid a network request on the client. This is useful for server-side rendering (SSR) or when you want to reduce the number of network requests on the client.
## Client Initialize Response
The Node Core SDK provides a method to generate a client initialize response that can be used to bootstrap client SDKs without requiring network requests.
```typescript theme={null}
// Get client initialize response for a user
const values = statsig.getClientInitializeResponse(user, options);
// Pass values to a client SDK to initialize without a network request
```
The `getClientInitializeResponse` method accepts an optional `options` parameter with the following properties:
```typescript theme={null}
export interface ClientInitializeResponseOptions {
hashAlgorithm?: string; // Algorithm used for hashing gate/experiment names (default: 'djb2')
clientSdkKey?: string; // Client SDK key to use for initialization
includeLocalOverrides?: boolean; // Whether to include local overrides in the response
featureGateFilter?: Set; // Filter to only include specific feature gates
experimentFilter?: Set; // Filter to only include specific experiments
dynamicConfigFilter?: Set; // Filter to only include specific dynamic configs
layerFilter?: Set; // Filter to only include specific layers
paramStoreFilter?: Set; // Filter to only include specific parameter stores
}
```
The `hashAlgorithm` option specifies which algorithm to use for hashing gate and experiment names in the client initialize response. The default is `'djb2'` for better performance and smaller payload size.
```typescript theme={null}
// Use djb2 hashing algorithm for better performance
const values = statsig.getClientInitializeResponse(user, {
hashAlgorithm: 'djb2',
});
```
The `clientSdkKey` option lets you filter the response to only the specific feature gates, experiments, dynamic configs, layers, or parameter stores that a particular client key has access to - effectively letting you apply [target apps](/sdk-keys/target-apps/).
```typescript theme={null}
// Specify a client SDK key
const values = statsig.getClientInitializeResponse(user, {
clientSdkKey: 'client-key',
});
```
The filter options allow you to reduce the payload size by only including specific feature gates, experiments, dynamic configs, layers, or parameter stores in the response.
```typescript theme={null}
// Only include specific feature gates and experiments
const values = statsig.getClientInitializeResponse(user, {
featureGateFilter: new Set(['my_gate_1', 'my_gate_2']),
experimentFilter: new Set(['my_experiment']),
});
```
The `includeLocalOverrides` option determines whether to consider [local overrides](#local-overrides) you've set when evaluating each config in the response.
```typescript theme={null}
// Include local overrides in the response
const values = statsig.getClientInitializeResponse(user, {
includeLocalOverrides: true,
});
```
Below is a complete example of using the client initialize response to bootstrap a client SDK. Note that you may choose to parallelize or inline the initialize response data with other requests to your server, to eliminate additional requests and latency.
```typescript theme={null}
// Server-side code
import { Statsig, StatsigUser } from '@statsig/node-core';
// Initialize the server SDK
await Statsig.initialize('server-secret-key');
// In your API endpoint handler
app.get('/statsig-bootstrap', (req, res) => {
// Create a user object from the request
const user = new StatsigUser({
userID: req.query.userID || '',
email: req.query.email,
ip: req.ip,
userAgent: req.headers['user-agent'],
});
// Generate the client initialize response with filters
const values = Statsig.getClientInitializeResponse(user, {
hashAlgorithm: 'djb2',
featureGateFilter: new Set(['onboarding_v2', 'new_checkout']),
experimentFilter: new Set(['pricing_experiment']),
layerFilter: new Set(['ui_layer']),
});
// Return the values to the client
res.json({ statsigValues: values });
});
```
```typescript theme={null}
// Client-side code using @statsig/js-client
import { Statsig } from '@statsig/js-client';
// Fetch bootstrap values from your API
const response = await fetch('/statsig-bootstrap');
const { statsigValues } = await response.json();
// Initialize the client SDK with the bootstrap values
await Statsig.initialize({
sdkKey: 'client-sdk-key',
initializeValues: statsigValues,
});
```
## SDK Event Subscriptions
The Statsig SDK provides an event subscription system that allows you to listen for evaluation events and lifecycle events in real-time. This feature is useful for debugging, analytics, custom logging, and integrating with external systems.
### Supported Events
The SDK supports subscribing to the following evaluation events:
* **`gate_evaluated`** - Fired when a feature gate is evaluated for a user
* **`dynamic_config_evaluated`** - Fired when a dynamic config is retrieved for a user
* **`experiment_evaluated`** - Fired when an experiment is evaluated for a user
* **`layer_evaluated`** - Fired when a layer is evaluated for a user
* **`specs_updated`** - Fired when the SDK updates its cached specs, including where the specs were loaded from
* **`"*"`** - Subscribe to all evaluation events
### SDK Event Data
Each event includes relevant context about the evaluation:
* **Gate Evaluated Events** include: `gate_name`, `value` (boolean), `rule_id`, `reason`
* **Dynamic Config Events** include: the full `dynamic_config` object with values and metadata
* **Experiment Events** include: the full `experiment` object with variant assignment and parameters
* **Layer Events** include: the full `layer` object with allocated experiment and parameters
* **Specs Updated Events** include `source`, `source_api`, and `values` metadata, where `values.time` is the timestamp of the last update to the project in the Statsig console
### Use Cases
Event subscriptions are particularly useful for:
* **Debugging**: Monitor which features are being evaluated and their results
* **Analytics**: Track feature usage patterns and user segments
* **Custom Logging**: Send evaluation data to your own logging systems
* **Integration**: Forward events to external analytics or monitoring tools
* **Testing**: Verify that features are being evaluated as expected
### Best Practices
* **Clean up subscriptions**: Always unsubscribe when you no longer need to listen for events to prevent memory leaks
* **Handle event data carefully**: Event objects may contain sensitive user information depending on your configuration
* **Use specific event types**: Subscribe to specific events rather than "\*" when possible for better performance
* **Avoid heavy processing**: Keep event handlers lightweight to avoid impacting SDK performance
```javascript expandable theme={null}
const statsig = new Statsig('server-secret-key');
// Subscribe to gate evaluation events
const gateSubId = statsig.subscribe('gate_evaluated', (event) => {
console.log('Gate evaluated:', {
gateName: event.gate_name,
value: event.value,
ruleId: event.rule_id,
reason: event.reason
});
});
// Subscribe to dynamic config evaluation events
const configSubId = statsig.subscribe('dynamic_config_evaluated', (event) => {
console.log('Config evaluated:', {
configName: event.dynamic_config.name,
values: event.dynamic_config.value
});
});
// Subscribe to experiment evaluation events
const experimentSubId = statsig.subscribe('experiment_evaluated', (event) => {
console.log('Experiment evaluated:', {
experimentName: event.experiment.name,
groupName: event.experiment.group_name,
parameters: event.experiment.value
});
});
// Subscribe to layer evaluation events
const layerSubId = statsig.subscribe('layer_evaluated', (event) => {
console.log('Layer evaluated:', {
layerName: event.layer.name,
allocatedExperiment: event.layer.allocated_experiment_name,
parameters: event.layer.value
});
});
// Subscribe to specs updated events
const specsUpdatedSubId = statsig.subscribe('specs_updated', (event) => {
console.log('Specs updated:', {
source: event.data.source,
sourceApi: event.data.source_api,
projectLastUpdated: event.data.values.time,
});
});
// Subscribe to all events
const allEventsSubId = statsig.subscribe('*', (event) => {
console.log('Event received:', event.event_name, event);
});
// Unsubscribe from specific event types
statsig.unsubscribe('gate_evaluated');
statsig.unsubscribe('specs_updated');
// Unsubscribe using subscription ID
statsig.unsubscribeById(configSubId);
// Unsubscribe from all events
statsig.unsubscribeAll();
```
## Local Overrides
Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console.
```jsx theme={null}
// Overrides the given gate to the specified value
Statsig.overrideGate("a_gate_name", true);
// Optional third parameter, overrides the gate only for a given ID
Statsig.overrideGate("a_gate_name", true, "userID-123");
```
```jsx theme={null}
// Overrides the given dynamic config to the provided value
Statsig.overrideDynamicConfig("a_config_name", { key: "value" });
// Optional third parameter, overrides the dynamic config only for a given ID
Statsig.overrideDynamicConfig("a_config_name", { key: "value" }, "userID-123");
```
```jsx theme={null}
// Overrides the given experiment to the provided value
Statsig.overrideExperiment("an_experiment_name", { key: "value" });
// Optional third parameter, overrides the experiment only for a given ID
Statsig.overrideExperiment("an_experiment_name", { key: "value" }, "userID-123");
// Overrides the given experiment to a particular groupname
Statsig.overrideExperimentByGroupName("an_experiment_name", "a_group_name");
// Alternatively, get the Experiment object for a given groupName
const groupExp = statsig.getExperimentByGroupName("pricing_experiment", "premium_group");
const premiumPrice = groupExp.getValue("price", 9.99);
```
```jsx theme={null}
// Overrides the given layer to the provided value
Statsig.overrideLayer("a_layer_name", { key: "value" });
// Optional third parameter, overrides the layer only for a given ID
Statsig.overrideLayer("a_layer_name", { key: "value" }, "userID-123");
```
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant.
```typescript expandable PersistentStorageInterface.ts theme={null}
export interface PersistentStorage {
load: (key: string) => UserPersistedValues | null;
save: (key: string, config_name: string, data: StickyValues) => void;
delete: (key: string, config_name: string) => void;
}
export interface StickyValues {
value: boolean;
json_value: Record;
rule_id: string;
group_name: string | null;
secondary_exposures: SecondaryExposure[];
undelegated_secondary_exposures: SecondaryExposure[];
config_delegate: string | null;
explicit_parameters: string[] | null;
time: number;
configVersion?: number | undefined;
}
export type UserPersistedValues = Record;
export interface SecondaryExposure {
gate: string;
gateValue: string;
ruleId: string;
}
```
### Usage Example
```typescript expandable PersistentStorageUsage.ts theme={null}
import { PersistentStorage, StickyValues, UserPersistedValues } from '@statsig/statsig-node-core';
class MyPersistentStorage implements PersistentStorage {
private storage = new Map();
constructor() {
this.load = this.load.bind(this);
this.save = this.save.bind(this);
this.delete = this.delete.bind(this);
}
load(key: string): UserPersistedValues | null {
return this.storage.get(key) || null;
}
save(key: string, config_name: string, data: StickyValues): void {
const existing = this.storage.get(key) || {};
existing[config_name] = data;
this.storage.set(key, existing);
}
delete(key: string, config_name: string): void {
const existing = this.storage.get(key);
if (existing) {
delete existing[config_name];
this.storage.set(key, existing);
}
}
getUserPersistedValue(user: StatsigUser, idType: string): UserPersistedValues | null {
const storageKey = this.getStorageKey(user, idType);
if (storageKey !== null) {
return this.load(storageKey);
}
return null;
}
private getStorageKey(user: StatsigUser, idType: string): string | null {
const lowerCaseIdType = idType.toLowerCase();
if (lowerCaseIdType === "user_id" || lowerCaseIdType === "userid") {
const id = user.userID;
return id ? `${id}:userID` : null;
} else if (user.customIDs) {
const id = user.customIDs[idType];
return id ? `${id}:${idType}` : null;
}
return null;
}
}
```
Persistent storage support was added in version 0.6.1 of the Node.js SDK.
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
```typescript theme={null}
export interface DataStore {
initialize?: () => Promise;
shutdown?: () => Promise;
get?: (key: string) => Promise;
set?: (key: string, value: string, time?: number) => Promise;
supportPollingUpdatesFor?: (key: string) => Promise;
}
export interface DataStoreResponse {
result?: string;
time?: number;
}
```
For example, see our 1P implementation via Redis [statsig-node-redis](https://github.com/statsig-io/node-js-server-sdk-redis).
## Custom Output Logger
The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity.
```typescript theme={null}
interface OutputLoggerProvider {
initialize?: () => void;
debug?: (tag: string, message: string) => void;
info?: (tag: string, message: string) => void;
warn?: (tag: string, message: string) => void;
error?: (tag: string, message: string) => void;
shutdown?: () => void;
}
```
### Implementation Example
```typescript theme={null}
import { OutputLoggerProvider } from '@statsig/statsig-node-core';
class CustomOutputLogger implements OutputLoggerProvider {
initialize = () => {
console.log('Logger initialized');
};
debug = (tag: string, message: string) => {
console.debug(`[${tag}] ${message}`);
};
info = (tag: string, message: string) => {
console.info(`[${tag}] ${message}`);
};
warn = (tag: string, message: string) => {
console.warn(`[${tag}] ${message}`);
};
error = (tag: string, message: string) => {
console.error(`[${tag}] ${message}`);
};
shutdown = () => {
console.log('Logger shutdown');
};
}
```
```typescript theme={null}
import { Statsig, StatsigOptions } from '@statsig/statsig-node-core';
const customLogger = new CustomOutputLogger();
const options: StatsigOptions = {
outputLoggerProvider: customLogger,
outputLogLevel: 'info', // 'none' | 'debug' | 'info' | 'warn' | 'error'
};
const statsig = new Statsig('secret-key', options);
await statsig.initialize();
```
* All methods in the `OutputLoggerProvider` interface are optional
* The `tag` parameter indicates the SDK component or category generating the log message
* Use `outputLogLevel` in StatsigOptions to control which log levels are actually called
* The logger is automatically initialized when the Statsig client initializes and shut down when the client shuts down
## Observability Client
The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the [Monitoring documentation](/sdk_monitoring).
```typescript theme={null}
export interface ObservabilityClient {
initialize?: () => void;
increment?: (metricName: string, value: number, tags: Record) => void;
gauge?: (metricName: string, value: number, tags: Record) => void;
dist?: (metricName: string, value: number, tags: Record) => void;
error?: (tag: string, error: string) => void;
}
```
## FAQs
### How do I run experiments for logged out users?
### Common Problems while installing
1. **Seeing SSL Error**
Right now the binary files will look at certain versions of SSL.
```shell theme={null}
// Try run this
apt-get update && apt-get install libcurl4-openssl-dev -y && rm -rf /var/lib/apt/lists/*
```
2. **Docker build failing with platform-specific dependencies**
When building in Docker (Linux environment), the build may fail if your local `package-lock.json` or `yarn.lock` contains platform-specific dependencies for macOS. This happens because `npm install` locally on Mac pulls down Apple-specific variants, but Docker tries to use those same locked dependencies on Linux.
**Solution:** Either install the Linux-specific variant during your Docker build step:
```dockerfile theme={null}
RUN npm install @statsig/statsig-node-core-linux-x64-gnu
```
Or add both platform variants as dependencies in your `package.json`:
```json theme={null}
"dependencies": {
"@statsig/statsig-node-core": "X.Y.Z", // Common (Required)
"@statsig/statsig-node-core-darwin-arm64": "X.Y.Z", // Mac Specific
"@statsig/statsig-node-core-linux-x64-gnu": "X.Y.Z" // Linux Specific
}
```
## Reference
* `checkGate(user: StatsigUser, gateName: string, options?: EvaluationOptions): boolean`
* `getDynamicConfig(user: StatsigUser, configName: string, options?: EvaluationOptions): DynamicConfig`
* `getExperiment(user: StatsigUser, experimentName: string, options?: EvaluationOptions): DynamicConfig`
* `getLayer(user: StatsigUser, layerName: string, options?: EvaluationOptions): Layer`
* `getFeatureGate(user: StatsigUser, gateName: string, options?: EvaluationOptions): FeatureGate`
* `getParameterStore(user: StatsigUser, parameterStoreName: string, options?: EvaluationOptions): ParameterStore`
* `getPrompt(user: StatsigUser, promptName: string, options?: EvaluationOptions): Prompt`
* `getPromptSet(user: StatsigUser, promptSetName: string, options?: EvaluationOptions): PromptSet`
* `logEvent(user: StatsigUser, eventName: string, value?: string | number | null, metadata?: Record): void`
* `forwardLogLineEvent(user: StatsigUser, level: string, message: string, metadata?: Record): void`
* `manuallyLogGateExposure(user: StatsigUser, gateName: string): void`
* `manuallyLogDynamicConfigExposure(user: StatsigUser, configName: string): void`
* `manuallyLogExperimentExposure(user: StatsigUser, experimentName: string): void`
* `manuallyLogLayerParameterExposure(user: StatsigUser, layerName: string, parameterName: string): void`
* `overrideExperimentByGroupName(experimentName: string, groupName: string, id?: string | null): void`
* `getClientInitializeResponse(user: StatsigUser, options?: ClientInitializeResponseOptions): ClientInitializeResponse`
* `shutdown(): Promise`
The following methods return information about which user fields are needed for evaluation:
* `getGateFieldsNeeded(gateName: string): string[]`
* `getDynamicConfigFieldsNeeded(configName: string): string[]`
* `getExperimentFieldsNeeded(experimentName: string): string[]`
* `getLayerFieldsNeeded(layerName: string): string[]`
These methods return an array of strings representing the user fields that are required to properly evaluate the specified gate, config, experiment, or layer. This can be useful for:
* Optimizing user object creation by only including necessary fields
* Understanding which user attributes affect a particular feature
* Debugging evaluation issues
# PHP Server SDK
Source: https://docs.statsig.com/server-core/php-core
Statsig's next-generation PHP Server SDK built on the Server Core framework, with improved performance and a unified evaluation engine for PHP applications.
PHP Core on Github ,
Packagist Package
Migrating from the Legacy PHP SDK? See our [Migration Guide](/server-core/migration-guides/php).
## Setup the SDK
## Installation
### 1. Install and Add as a Dependency
You can install the new PHP Core SDK using composer:
```shell theme={null}
composer require statsig/statsig-php-core
```
### 2. PHP Configuration Requirements
The PHP Core SDK uses the FFI extension to interface with the Rust core. You must enable FFI in your PHP configuration by setting `ffi.enable=true` in your php.ini file.
For more information about this setting, see the [PHP manual for ffi.enable](https://www.php.net/manual/en/ffi.configuration.php#ini.ffi.enable).
### 3. Add Scripts & Cron Job
Add post-install and post-update scripts in composer.json:
```json theme={null}
// composer.json
{
"name": "awesome-php-project",
...
"scripts": {
...
"post-install-cmd": [
"cd vendor/statsig/statsig-php-core && php post-install.php"
],
"post-update-cmd": [
"cd vendor/statsig/statsig-php-core && php post-install.php"
]
}
}
```
Next, you'll want to add a script to sync your Statsig configs and flush your events, see example files on Statsig's Github [here](https://github.com/daniel-statsig/statsig-php-core-slim-example/tree/main/bin).
You'll also want to setup cron jobs to run these scripts periodically:
```shell theme={null}
*/10 * * * * /usr/bin/php /var/www/example.com/bin/StatsigSyncConfig.php 1>> /dev/null 2>&1
*/1 * * * * /usr/bin/php /var/www/example.com/bin/StatsigFlushEvents.php 1>> /dev/null 2>&1
```
Also, be sure to run the StatsigSyncConfig.php cron job at least once before proceeding.
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
You'll want to add your client secret key to the environment, by adding to a .env file, or directly on the command line:
```shell theme={null}
export STATSIG_SECRET_KEY=secret-123456789
```
```php theme={null}
// At the top of your file
use Statsig\Statsig;
use Statsig\StatsigOptions;
use Statsig\StatsigLocalFileEventLoggingAdapter;
use Statsig\StatsigLocalFileSpecsAdapter;
//In the case of slim framework, in container builder definitions:
Statsig::class => function (ContainerInterface $c) {
$sdk_key = getenv("STATSIG_SECRET_KEY");
$options = new StatsigOptions(
null,
null,
new StatsigLocalFileSpecsAdapter($sdk_key, "/tmp"),
new StatsigLocalFileEventLoggingAdapter($sdk_key, "/tmp")
);
$statsig = new Statsig($sdk_key, $options);
$statsig->initialize();
return $statsig;
},
```
`StatsigLocalFile` Adapters rely on cron jobs and files. If you are seeing errors around file access, ensure your cron job has run at least one time before using Statsig.
See [Add Scripts & Cron Job](#2-add-scripts--cron-job)
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```php theme={null}
use Statsig\Statsig;
use Statsig\StatsigUserBuilder;
$user = StatsigUserBuilder::withUserID('my_user')->build();
$passed = $statsig->checkGate($user, 'my_gate');
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```php theme={null}
$user = StatsigUserBuilder::withUserID('my_user')->build();
$config = $statsig->getDynamicConfig($user, 'my_config');
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```php theme={null}
$user = StatsigUserBuilder::withUserID('my_user')->build();
$xp = $statsig->getExperiment($user, 'an_experiment');
```
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```php theme={null}
$gate = $statsig->getFeatureGate($user, "example_gate");
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
*Parameter stores are not yet available for this sdk. Need it now? Let us know in [Slack](https://statsig.com/slack).*
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```php theme={null}
$user = StatsigUserBuilder::withUserID('my_user')->build();
$statsig->logEvent($user, 'an_experiment');
```
### Sending Events to Log Explorer
You can forward logs to Logs Explorer for convenient analysis using the Forward Log Line Event API. This lets you include custom metadata and event values with each log.
Sending events to Log Explorer is not yet available for this sdk. Need it now? Let us know in [Slack](https://statsig.com/slack).
## Using Shared Instance
In some applications, you may want to create a single Statsig instance that can be accessed globally throughout your codebase. The shared instance functionality provides a singleton pattern for this purpose:
```php theme={null}
use Statsig\Statsig;
// Initialize the shared instance
Statsig::initializeShared('your-server-secret-key', $options);
// Access the shared instance from anywhere in your code
$user = StatsigUserBuilder::withUserID('my_user')->build();
$gate = Statsig::shared()->checkGate($user, 'my_gate');
// Shutdown the shared instance when your application closes
Statsig::shared()->shutdown();
```
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
```php theme={null}
use Statsig\StatsigUser;
$user = new StatsigUser([
'userID' => 'a-user-id',
'email' => 'user@example.com',
'ip' => '192.168.1.1',
'userAgent' => 'Mozilla/5.0...',
'country' => 'US',
'locale' => 'en_US',
'appVersion' => '1.0.0',
'custom' => [
// Custom fields
'plan' => 'premium',
'age' => 25
],
'customIDs' => [
// Custom ID types
'stableID' => 'stable-id-123'
],
'privateAttributes' => [
// Private attributes not forwarded to integrations
'email' => 'private@example.com'
]
]);
```
## Private Attributes
You can define which attributes are considered "private" and should not be forwarded to any third-party integrations like the data connectors by setting the `privateAttributes` parameter in the `StatsigUser` constructor. The `privateAttributes` parameter is a key-value dictionary where keys are attribute names and values are the private values. Note that in the example user object above, for the key `"email"`, we have values for the top-level `email` field AND for the private attributes field with `"email"` as the key. These are distinct; you can have a value in the top-level `email` field that is not `private`, and a value in `private_attributes` that is `private`, or vice versa.
```php theme={null}
$user = new StatsigUser([
'userID' => 'a-user-id',
'email' => 'non_private@example.com',
'privateAttributes' => [
'email' => 'private@example.com'
]
]);
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
Custom URL for fetching feature specifications.
Custom URL for logging events.
An adapter with custom storage behavior for config specs. For example, use `StatsigLocalFileSpecsAdapter` to store configs in the local filesystem.
An adapter with custom event logging behavior. For example, use `StatsigLocalFileEventLoggingAdapter` to store events in the local filesystem.
Environment parameter for evaluation.
How often events are flushed to Statsig servers (in milliseconds).
Maximum number of events to queue before forcing a flush.
* Default is `2000`
* event\_logging\_max\_queue\_size \* event\_logging\_max\_pending\_batch\_queue\_size is the upper limit on how many events are queued
* See also `event_logging_max_pending_batch_queue_size`
Maximum number of event batches to hold in buffer to retry.
* Default is `100`.
* event\_logging\_max\_queue\_size \* event\_logging\_max\_pending\_batch\_queue\_size is the upper limit on how many events are queued
* eg: 2000 \* 100 means the SDK can process 200k event per second before events start getting dropped
* See also `event_logging_max_queue_size`.
How often the SDK updates specifications from Statsig servers (in milliseconds).
Controls the verbosity of SDK logs.
Disables country lookup based on IP address. Set to `true` to improve performance if country-based targeting is not needed.
Disables user agent parsing. Set to `true` to improve performance if device/browser-based targeting is not needed.
Maximum time in milliseconds to wait for SDK initialization to complete. If initialization takes longer than this timeout, the SDK will continue to operate but may return default values until initialization completes.
When set to true, the SDK will fallback to using the Statsig API directly if custom adapters (like local file adapters) fail to load configurations.
Enable/disable ID list functionality. **Required to be `true` when using segments with more than 1000 IDs.** See [ID List segments](/segments/add-id-list) for more details.
Configuration for connecting through a proxy server.
The hostname or IP address of the proxy server (e.g., `"proxy.example.com"` or `"192.168.1.100"`).
The port number of the proxy server (e.g., `8080`, `3128`, `1080`).
Authentication credentials for the proxy server in the format `"username:password"`. Only required if the proxy requires authentication.
The protocol to use for the proxy connection. Supported values: `"http"`, `"https"`, `"socks5"`.
### Proxy and Custom Network Routing
The PHP Server Core SDK supports a dedicated `proxy_config` for a standard outbound HTTP proxy. If you only need to route Statsig traffic to different endpoints, use `specs_url`, `log_event_url`, and `id_lists_url`.
***
### Performance Recommendations
If you are experiencing performance issues, particularly with long initialization times, you can disable user agent parsing and country lookup to improve performance:
* Set `disable_user_agent_parsing: true` if you don't need device or browser-based targeting
* Set `disable_country_lookup: true` if you don't need country-based targeting
These optimizations were added in response to performance issues identified in [PR #1119](https://github.com/statsig-io/private-statsig-server-core/pull/1119).
***
### Example Usage
```php theme={null}
use Statsig\Statsig;
use Statsig\StatsigOptions;
use Statsig\ProxyConfig;
use Statsig\StatsigLocalFileSpecsAdapter;
use Statsig\StatsigLocalFileEventLoggingAdapter;
// Create proxy configuration
$proxyConfig = new ProxyConfig(
proxyHost: "proxy.example.com",
proxyPort: 8080,
proxyAuth: "username:password", // Optional, only if authentication is required
proxyProtocol: "http"
);
// Initialize StatsigOptions with custom parameters
$options = new StatsigOptions(
specs_url: null,
log_event_url: null,
specs_adapter: new StatsigLocalFileSpecsAdapter($sdk_key, "/tmp"),
event_logging_adapter: new StatsigLocalFileEventLoggingAdapter($sdk_key, "/tmp"),
environment: "development",
event_logging_flush_interval_ms: 60000,
event_logging_max_queue_size: 1000,
specs_sync_interval_ms: 600000,
output_log_level: "INFO",
disable_country_lookup: true, // For better performance
wait_for_country_lookup_init: false,
wait_for_user_agent_init: false,
enable_id_lists: false,
disable_network: false,
id_lists_url: null,
id_lists_sync_interval_ms: null,
disable_all_logging: false,
init_timeout_ms: 3000,
fallback_to_statsig_api: false,
use_third_party_ua_parser: null,
persistent_storage: null,
proxy_config: $proxyConfig // Add proxy configuration
);
// Pass the options object into Statsig constructor
$statsig = new Statsig($sdk_key, $options);
$statsig->initialize();
```
When using `StatsigLocalFile` Adapters, ensure your cron job has run at least one time before using Statsig.
See [Add Scripts & Cron Job](#2-add-scripts--cron-job)
## Custom Adapters
### SpecsAdapterBase - Custom Configuration Sources
The `SpecsAdapterBase` allows you to fetch Statsig configurations from custom sources instead of (or in addition to) Statsig's servers. This is useful when you want to:
* Store configurations in your own database or cache (e.g., Redis, Memcached)
* Implement custom caching strategies
* Use Statsig in environments with restricted network access
* Reduce latency by serving configs from a local source
#### Implementation
To create a custom specs adapter, extend the `SpecsAdapterBase` class and implement the required methods:
```php theme={null}
redis = $redis;
}
public function setup(SpecsUpdateListener $listener): void
{
$this->listener = $listener;
}
public function start(): void
{
// Fetch initial specs when SDK starts
$this->refreshSpecsFromRedis();
// Optionally, trigger a background job or set up a timer
$this->refreshSpecsFromRedis();
}
private function fetchSpecsFromRedis()
{
try {
$specs = $this->redis->get('statsig_config_specs');
return $specs ?: null;
} catch (Exception $e) {
error_log("Failed to fetch specs from Redis: " . $e->getMessage());
return null;
}
}
private function refreshSpecsFromRedis()
{
$specs = $this->fetchSpecsFromRedis();
if ($specs && $this->listener) {
$timestamp = intval(microtime(true) * 1000);
$this->listener->didReceiveSpecsUpdate($specs, "Redis", $timestamp);
}
}
}
```
#### Usage
```php theme={null}
use Statsig\Statsig;
use Statsig\StatsigOptions;
$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
$specsAdapter = new RedisSpecsAdapter($redis);
$options = new StatsigOptions(
specs_adapter: $specsAdapter
);
$statsig = new Statsig('your-server-secret-key', $options);
$statsig->initialize();
```
#### Key Methods
* **`setup(SpecsUpdateListener $listener)`**: Called during initialization to provide the listener for spec updates
* **`start()`**: Called when the SDK starts. Fetch and provide initial configuration specs
* **`shutdown()`**: Called when the SDK shuts down. Clean up resources
* **`scheduleBackgroundSync()`**: Called to schedule periodic updates of configuration specs
The `SpecsUpdateListener` provides:
* **`didReceiveSpecsUpdate(string $specs, string $source, int $timestamp)`**: Notify the SDK of new specs
* **`getCurrentSpecsInfo()`**: Get information about current specs
***
### EventLoggingAdapterBase - Custom Event Destinations
The `EventLoggingAdapterBase` allows you to send events to custom destinations instead of or in addition to Statsig's servers. This is useful when you want to:
* Send events to your existing analytics platform
* Store events in a database for custom analysis
* Forward events to multiple destinations
* Implement custom batching or retry logic
#### Implementation
To create a custom event logging adapter, extend the `EventLoggingAdapterBase` class and implement the required methods:
```php theme={null}
analyticsClient = $analyticsClient;
}
public function start(): void
{
$this->isStarted = true;
// Initialize analytics client connection if needed
$this->analyticsClient->connect();
}
public function logEvents(LogEventRequest $request): bool
{
if (!$this->isStarted) {
return false;
}
try {
$events = $request->payload->events;
$metadata = $request->payload->statsig_metadata;
foreach ($events as $event) {
// Transform Statsig event to analytics platform format
$analyticsEvent = [
'event_name' => $event['eventName'],
'user_id' => $event['user']['userID'] ?? null,
'timestamp' => $event['time'],
'properties' => array_merge(
$event['metadata'] ?? [],
['statsig_metadata' => $metadata]
)
];
// Send to analytics platform
$this->analyticsClient->track($analyticsEvent);
}
return true;
} catch (Exception $e) {
error_log("Failed to log events to analytics platform: " . $e->getMessage());
return false;
}
}
public function shutdown(): void
{
$this->isStarted = false;
// Clean up analytics client connection
$this->analyticsClient->disconnect();
}
}
```
#### Usage
```php theme={null}
use Statsig\Statsig;
use Statsig\StatsigOptions;
$analyticsClient = new MyAnalyticsClient('api-key');
$eventAdapter = new AnalyticsEventAdapter($analyticsClient);
$options = new StatsigOptions(
event_logging_adapter: $eventAdapter
);
$statsig = new Statsig('your-server-secret-key', $options);
$statsig->initialize();
// Events will now be sent to your custom analytics platform
$statsig->logEvent($user, 'button_clicked', ['button_id' => 'signup']);
```
#### Key Methods
* **`start()`**: Called when the SDK starts. Initialize connections or resources
* **`logEvents(LogEventRequest $request): bool`**: Process and send events. Return true on success, false on failure
* **`shutdown()`**: Called when the SDK shuts down. Clean up resources
The `LogEventRequest` contains:
* **`event_count`**: Number of events in the request
* **`retries`**: Number of retry attempts for this request
* **`payload`**: `LogEventPayload` with events and metadata
The `LogEventPayload` contains:
* **`events`**: Array of event objects with user data, event names, and metadata
* **`statsig_metadata`**: SDK metadata including version and environment information
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```php theme={null}
// Method signature
public function shutdown(): void
// example usage
try {
$statsig->shutdown();
echo "Statsig instance has been successfully shutdown.\n";
} catch (Exception $e) {
error_log($e->getMessage());
}
```
Alternatively, if you are operating in a serverless environment/cloud function, you may wish to leave Statsig running in case your function is recycled but flush the logs to Statsig servers. Or, if you need an async method to wait for logs to post before resolving, you can use:
```php theme={null}
// Method signature
public function flushEvents(): void
// example usage
try {
$statsig->flushEvents();
echo "All events have been successfully flushed.\n";
} catch (Exception $e) {
echo "Failed to flush events: " . $e->getMessage() . "\n";
}
```
## Local Overrides
Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console.
```php theme={null}
$statsig->overrideGate("a_gate_name", true);
$statsig->overrideDynamicConfig("a_config_name", [
"key" => "value",
]);
$statsig->overrideExperiment("an_experiment_name", [
"key" => "value",
]);
$statsig->overrideExperimentByGroupName("an_experiment_name", "a_group_name");
$statsig->overrideLayer("a_layer_name", [
"key" => "value",
]);
```
You can also pass a third argument to scope an override to a specific ID:
```php theme={null}
$statsig->overrideExperimentByGroupName("an_experiment_name", "a_group_name", "user_123");
```
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant.
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for experiment assignments. This ensures consistent user experiences across sessions by persisting experiment assignments. For more information on persistent assignments, see the [Persistent Assignment](/server/concepts/persistent_assignment) documentation.
```php expandable MyPersistentStorage.php theme={null}
use Statsig\PersistentStorage;
use Statsig\StickyValues;
class MyPersistentStorage extends PersistentStorage
{
private array $storage = [];
public function load(string $key): ?array
{
return $this->storage[$key] ?? null;
}
public function save(string $key, string $config_name, StickyValues $data): void
{
$this->storage[$key] ??= [];
$this->storage[$key][$config_name] = $data->toArray();
}
public function delete(string $key, string $config_name): void
{
unset($this->storage[$key][$config_name]);
}
}
```
```php expandable PersistentStorageUsage.php theme={null}
$persistent_storage = new MyPersistentStorage();
$options = new StatsigOptions(
persistent_storage: $persistent_storage
);
$statsig = new Statsig("secret-key", $options);
$statsig->initialize();
$persisted_user = new StatsigUser("test-123");
$values = $persistent_storage->getValuesForUser($persisted_user, "userID") ?? [];
$experiment = $statsig->getExperiment(
$persisted_user,
"active_experiment",
["user_persisted_values" => $values],
);
```
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
Not supported at this time.
## Custom Output Logger
The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity.
## Custom Output Logger
The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity.
Not supported at this time.
## Observability Client
The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the [Monitoring documentation](/sdk_monitoring).
## Observability Client
The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the [Monitoring](/infrastructure/monitoring) documentation.
Not supported at this time.
## Notes on Beta Version
The PHP SDK expects an adapter to be provided for both logging and saving config specs, given the stateless nature of PHP. In [our example](https://github.com/daniel-statsig/statsig-php-core-slim-example), we've provided simple file-based adapters. More mature implementations may choose a different, and more performant caching approach. If you need help setting this up, reach out to us in [Slack](https://statsig.com/slack).
## FAQ
See the guide on [device level experiments](/guides/device-level-experiment)
# Python Server SDK
Source: https://docs.statsig.com/server-core/python-core
Statsig's next-generation Python Server SDK built on the Server Core framework, with improved performance and a unified evaluation engine for Python services.
Python Core on Github
Migrating from the Legacy Python SDK? See our [Migration Guide](/server-core/migration-guides/python).
## Setup the SDK
## Installation
```shell theme={null}
pip install statsig-python-core
```
## Tested Platforms
Docker base images where the Python Core SDK has been tested and verified:
| Docker Base Image | Description |
| ----------------------------------- | ---------------------------------------------------- |
| `python:3.7-alpine` | Python 3.7 on Alpine Linux |
| `python:3.7-buster` | Python 3.7 on Debian Buster |
| `python:3.7-slim` | Python 3.7 slim variant |
| `quay.io/pypa/manylinux2014_x86_64` | Manylinux 2014 x86\_64 for broad Linux compatibility |
| `python:3.10-alpine` | Python 3.10 on Alpine Linux |
| `python:3.10-slim` | Python 3.10 slim variant |
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
```python theme={null}
from statsig_python_core import Statsig, StatsigOptions # note, import statement has underscores while install has dashes
options = StatsigOptions()
options.environment = "development"
statsig = Statsig("secret-key", options)
statsig.initialize().wait()
# If you're running this in a script, be sure to wait for shutdown at the end to flush event logs to statsig
statsig.shutdown().wait()
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
### ⚠️ Warning: Process Forking and WSGI Servers
**Important:** Never fork processes after calling `statsig.initialize()`. Doing so will put Statsig in an undefined state and may cause deadlock.
The Python Core SDK uses internal threading and async runtime components that do not work correctly when copied across process boundaries. When a process forks after initialization, these components can become corrupted, leading to:
* Deadlocks in event logging
* Hanging initialization calls
* Unpredictable SDK behavior
* Silent failures in feature evaluation
### Initializing with WSGI servers
For production deployments using WSGI servers like uWSGI or Gunicorn, ensure Statsig is initialized **after** the worker processes are forked, not in the main process.
#### ✅ Correct: uWSGI example
```python expandable theme={null}
# app.py
from statsig_python_core import Statsig, StatsigOptions
from flask import Flask
app = Flask(__name__)
statsig = None
def init_statsig():
global statsig
if statsig is None:
options = StatsigOptions()
options.environment = "production"
statsig = Statsig("your-server-secret-key", options)
statsig.initialize().wait()
# Initialize in each worker process
@app.before_first_request
def before_first_request():
init_statsig()
@app.route('/')
def index():
# Use statsig here
return "Hello World"
```
```ini theme={null}
# uwsgi.ini
[uwsgi]
module = app:app
master = true
processes = 4
# Statsig will be initialized in each worker process
```
#### ✅ Correct: Gunicorn example
```python theme={null}
# gunicorn_config.py
def post_fork(server, worker):
# Initialize Statsig after worker process is forked
from app import init_statsig
init_statsig() # as defined above
# ...app.py
```
```bash theme={null}
# Start Gunicorn with post-fork hook
gunicorn --config gunicorn_config.py app:app
```
#### ✅ Correct: FastAPI example
```python expandable theme={null}
from fastapi import FastAPI
from statsig_python_core import Statsig, StatsigOptions
app = FastAPI()
statsig = None
@app.on_event("startup")
async def startup_event():
global statsig
options = StatsigOptions()
options.environment = "production"
statsig = Statsig("your-server-secret-key", options)
statsig.initialize().wait()
@app.on_event("shutdown")
async def shutdown_event():
if statsig:
statsig.shutdown().wait()
@app.get("/")
async def root():
# Use statsig here
return {"message": "Hello World"}
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```python theme={null}
user = StatsigUser("a-user")
if statsig.check_gate(user, "a_gate"):
# Gate is on, enable new feature
else:
# Gate is off
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```python theme={null}
# Get a dynamic config for a specific user
config = statsig.get_dynamic_config(StatsigUser("my_user"), "a_config")
# Access config values with type-safe getters and fallback values
product_name = config.get_string("product_name", "Awesome Product v1") # returns String
price = config.get_float("price", 10.0) # returns float
should_discount = config.get_bool("discount", False) # returns bool
quantity = config.get_integer("quantity", 1) # returns int64
# Advanced Usage:
# You can disable exposure logging for this specific check
options = DynamicConfigEvaluationOptions(disable_exposure_logging=True)
config = statsig.get_dynamic_config(user, "a_config", options)
# The config object also provides metadata about the evaluation
print(config.rule_id) # The ID of the rule that served this config
print(config.id_type) # The type of the evaluation (experiment, config, etc)
```
The `get_dynamic_config()` method returns a DynamicConfig object that allows you to:
* Fetch typed values with fallback defaults using `get_string()`, `get_float()`, `get_boolean()`, and `get_integer()`
* Access evaluation metadata through properties like `rule_id` and `id_type`
* Configure evaluation behavior using `DynamicConfigEvaluationOptions`
By default, Statsig logs exposures automatically when configs are evaluated. You can disable this for specific checks using the evaluation options.
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```Python theme={null}
# Values via get_layer
layer = statsig.get_layer(StatsigUser("my_user"), "user_promo_experiments")
title = layer.get_string("title", "Welcome to Statsig!")
discount = layer.get_float("discount", 0.1)
# Via get_experiment
title_exp = statsig.get_experiment(StatsigUser("my_user"), "new_user_promo_title")
price_exp = statsig.get_experiment(StatsigUser("my_user"), "new_user_promo_price")
title = title_exp.get_string("title", "Welcome to Statsig!")
discount = price_exp.get_float("discount", 0.1)
```
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```python theme={null}
gate = statsig.get_feature_gate(user, "example_gate")
print(gate.rule_id)
print(gate.value)
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
```python theme={null}
# Get a Parameter Store by name
param_store = statsig.get_parameter_store(user, "my_parameter_store")
```
### Retrieving Parameter Values
Parameter Store provides methods for retrieving values of different types with fallback defaults.
```python theme={null}
# String parameters
string_value = param_store.get_string("string_param", "default_value")
# Boolean parameters
bool_value = param_store.get_bool("bool_param", False)
# Numeric parameters
float_value = param_store.get_float("float_param", 0.0)
integer_value = param_store.get_integer("integer_param", 0)
# Complex parameters
default_array = ["item1", "item2"]
array_value = param_store.get_array("array_param", default_array)
default_map = {"key": "value"}
map_value = param_store.get_map("map_param", default_map)
```
### Evaluation Options
You can disable exposure logging when retrieving a parameter store:
```python theme={null}
from statsig_python_core import ParameterStoreEvaluationOptions
options = ParameterStoreEvaluationOptions(disable_exposure_logging=True)
param_store = statsig.get_parameter_store(user, "my_parameter_store", options)
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```Python theme={null}
statsig.log_event(
user=StatsigUser("user_id"), # Replace with your user object
event_name="add_to_cart",
value="SKU_12345",
metadata={
"price": "9.99",
"item_name": "diet_coke_48_pack"
}
)
```
### Sending Events to Log Explorer
You can forward logs to Logs Explorer for convenient analysis using the Forward Log Line Event API. This lets you include custom metadata and event values with each log.
```python theme={null}
user = StatsigUser(
user_id="a-user",
custom={
"service": "my-service",
"pod": "my-pod",
"namespace": "my-namespace",
"container": "my-container",
# ...include any service-specific metadata
}
)
# levels: trace, debug, info, log, warn, error
statsig.forward_log_line_event(user, "warn", "script failed to load", {
"custom_metadata": "script_name:my-script"
# ... include any event-specific metadata
})
```
## Using Shared Instance
In some applications, you may want to create a single Statsig instance that can be accessed globally throughout your codebase. The shared instance functionality provides a singleton pattern for this purpose:
```python theme={null}
# Create a shared instance that can be accessed globally
statsig = Statsig.new_shared("secret-key", options)
statsig.initialize().wait()
# Access the shared instance from anywhere in your code
shared_statsig = Statsig.shared()
is_feature_enabled = shared_statsig.check_gate(StatsigUser("user_id"), "feature_name")
# Check if a shared instance exists
if Statsig.has_shared_instance():
# Use the shared instance
pass
# Remove the shared instance when no longer needed
Statsig.remove_shared()
```
The shared instance functionality provides a singleton pattern where a single Statsig instance can be created and accessed globally throughout your application. This is useful for applications that need to access Statsig functionality from multiple parts of the codebase without having to pass around a Statsig instance.
* `Statsig.new_shared(sdk_key, options)`: Creates a new shared instance of Statsig that can be accessed globally
* `Statsig.shared()`: Returns the shared instance
* `Statsig.has_shared_instance()`: Checks if a shared instance exists (useful when you aren't sure if the shared instance is ready yet)
* `Statsig.remove_shared()`: Removes the shared instance (useful when you want to switch to a new shared instance)
`has_shared_instance()` and `remove_shared()` are helpful in specific scenarios but aren't required in most use cases where the shared instance is set up near the top of your application.
Also note that only one shared instance can exist at a time. Attempting to create a second shared instance will result in an error.
## Manual Exposures
By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or call get() on a parameter in a layer. However, there are times when you may want to log an exposure event manually. For example, if you're using a gate to control access to a feature, but you don't want to log an exposure until the user actually uses the feature, you can use manual exposures.
All of the main SDK functions (`check_gate`, `get_dynamic_config`, `get_experiment`, `get_layer`) accept an optional `disable_exposure_logging` parameter. When this is set to `True`, the SDK will not automatically log an exposure event. You can then manually log the exposure at a later time using the corresponding manual exposure logging method:
```python theme={null}
result = statsig.check_gate(aUser, 'a_gate_name', FeatureGateEvaluationOptions(disable_exposure_logging=True))
```
```python theme={null}
statsig.manually_log_gate_exposure(aUser, 'a_gate_name')
```
```python theme={null}
config = statsig.get_dynamic_config(aUser, 'a_dynamic_config_name', DynamicConfigEvaluationOptions(disable_exposure_logging=True))
```
```python theme={null}
statsig.manually_log_dynamic_config_exposure(aUser, 'a_dynamic_config_name')
```
```python theme={null}
experiment = statsig.get_experiment(aUser, 'an_experiment_name', ExperimentEvaluationOptions(disable_exposure_logging=True))
```
```python theme={null}
statsig.manually_log_experiment_exposure(aUser, 'an_experiment_name')
```
```python theme={null}
layer = statsig.get_layer(aUser, 'a_layer_name', LayerEvaluationOptions(disable_exposure_logging=True))
paramValue = layer.get('a_param_name', 'fallback_value')
```
```python theme={null}
statsig.manually_log_layer_parameter_exposure(aUser, 'a_layer_name', 'a_param_name')
```
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
```python expandable theme={null}
from statsig_python_core import StatsigUser
user = StatsigUser(
user_id="a-user-id",
email="user@example.com",
ip="192.168.1.1",
user_agent="Mozilla/5.0...",
country="US",
locale="en_US",
app_version="1.0.0",
custom={
# Custom fields
"plan": "premium",
"age": 25
},
custom_ids={
# Custom ID types
"stable_id": "stable-id-123"
},
private_attributes={
# Private attributes not forwarded to integrations
"email": "private@example.com"
}
)
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
Custom URL for fetching feature specifications.
How often the SDK updates specifications from Statsig servers (in milliseconds).
Sets the maximum timeout for initialization requests (in milliseconds).
Custom URL for logging events.
When `true`, disables all event logging.
When `true`, disables all network functions: event & exposure logging, spec downloads, and ID List downloads. Formerly called "localMode".
How often events are flushed to Statsig servers (in milliseconds).
Maximum number of events to queue before forcing a flush.
* Default is `2000`
* event\_logging\_max\_queue\_size \* event\_logging\_max\_pending\_batch\_queue\_size is the upper limit on how many events are queued
* See also `event_logging_max_pending_batch_queue_size`
Maximum number of event batches to hold in buffer to retry.
* Default is `100`.
* event\_logging\_max\_queue\_size \* event\_logging\_max\_pending\_batch\_queue\_size is the upper limit on how many events are queued
* eg: 2000 \* 100 means the SDK can process 200k event per second before events start getting dropped
* See also `event_logging_max_queue_size`.
Enable/disable ID list functionality. **Required to be `true` when using segments with more than 1000 IDs.** See [ID List segments](/segments/add-id-list) for more details.
If set to true, the SDK will NOT attempt to parse UserAgents (attached to the user object) into browserName, browserVersion, systemName, systemVersion, and appVersion at evaluation time, when needed for evaluation.
When set to true, the SDK will wait until user agent parsing data is fully loaded during initialization. This may slow down by \~1 second startup but ensures that parsing of the user's userAgent string into fields like browserName, browserVersion, systemName, systemVersion, and appVersion is ready before any evaluations.
If set to true, the SDK will NOT attempt to parse IP addresses (attached to the user object at user.ip) into Country codes at evaluation time, when needed for evaluation.
When set to true, the SDK will wait for country lookup data (e.g., GeoIP or YAML files) to fully load during initialization. This may slow down by \~1 second startup but ensures that IP-to-country parsing is ready at evaluation time.
Custom URL for fetching ID lists.
How often the SDK updates ID lists from Statsig servers (in milliseconds).
Whether to fallback to the Statsig API if custom endpoints fail.
Environment parameter for evaluation.
Controls the verbosity of SDK logs.
Adapter / Interface to use persistent assignment within SDK. See [Persistent Assignment](/server/concepts/persistent_assignment/) for more details.
Adapter to listen monitor the health of SDK. See [SDK Monitoring](https://docs.statsig.com/sdk_monitoring/) for more details.
Custom data store implementation for storing and retrieving configuration data. Used for advanced caching or storage strategies.
Maximum number of batches of events to hold in buffer to retry.
Custom fields to include in all events logged by the SDK.
Compression method for exposure logging. Options: "gzip", "dictionary"
Configuration for connecting through a proxy server. The `ProxyConfig` object has the following properties:
* `proxy_host`: Optional string specifying the proxy server host
* `proxy_port`: Optional number specifying the proxy server port
* `proxy_auth`: Optional string for proxy authentication (format: "username:password")
* `proxy_protocol`: Optional string specifying the protocol (e.g., "http", "https")
* `ca_cert_path`: Optional path to a PEM CA bundle for outbound TLS
Advanced configuration for customizing how the SDK fetches feature specifications. Allows you to configure multiple spec adapters with different priorities and settings.
Each `SpecAdapterConfig` object has the following properties:
* `adapter_type`: String specifying the adapter type (e.g., "http", "grpc")
* `specs_url`: Optional custom URL for fetching specifications
* `init_timeout_ms`: Optional timeout for initialization (in milliseconds)
**Migration Note:** This parameter was previously named `init_resources` in earlier versions. If you're upgrading from an older version, replace `init_resources` with `spec_adapter_configs`.
### Proxy and Custom Network Routing
Use `proxy_config` if your service needs a standard outbound HTTP proxy. Use `spec_adapter_configs` if you need to route spec downloads through [Statsig Forward Proxy](/infrastructure/forward-proxy) or another custom spec source.
```python theme={null}
from statsig_python_core import ProxyConfig, Statsig, StatsigOptions
proxy_config = ProxyConfig(
proxy_host="proxy.example.com",
proxy_port=8080,
proxy_protocol="https",
ca_cert_path="/etc/ssl/certs/corporate-ca.pem", # Optional
)
options = StatsigOptions()
options.proxy_config = proxy_config
statsig = Statsig("secret-key", options)
statsig.initialize().wait()
```
Set `ca_cert_path` when your environment requires a custom PEM CA bundle for outbound TLS.
### Using spec\_adapter\_configs with Multiple Sources
```python theme={null}
from statsig_python_core import StatsigOptions, SpecAdapterConfig
# Configure multiple spec adapters with priority order
# First source: Statsig CDN
primary_adapter = SpecAdapterConfig(
adapter_type="http",
specs_url="https://api.statsigcdn.com/v2/download_config_specs",
init_timeout_ms=3000
)
# Second source: Data Store adapter
# The SDK will try this source if the primary source fails
data_store_adapter = SpecAdapterConfig(
adapter_type="data_store",
init_timeout_ms=5000
)
options = StatsigOptions()
options.spec_adapter_configs = [primary_adapter, data_store_adapter]
options.environment = "production"
statsig = Statsig("secret-key", options)
statsig.initialize().wait()
```
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```python theme={null}
statsig.shutdown().wait()
```
## Local Overrides
Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console.
```python theme={null}
# Overrides the given gate to the specified value
statsig.override_gate("a_gate_name", True)
# Overrides the given dynamic config to the provided value
statsig.override_dynamic_config("a_config_name", {"key": "value"})
# Overrides the given experiment to the provided value
statsig.override_experiment("an_experiment_name", {"key": "value"})
# Overrides the given layer to the provided value
statsig.override_layer("a_layer_name", {"key": "value"})
# Overrides the given experiment to a particular groupname, available for experiments only:
statsig.override_experiment_by_group_name("an_experiment_name", "a_group_name")
```
## Client SDK Bootstrapping | SSR
If you are using the Statsig client SDK in a browser or mobile app, you can bootstrap the client SDK with the values from the server SDK to avoid a network request on the client. This is useful for server-side rendering (SSR) or when you want to reduce the number of network requests on the client.
## Client Initialize Response
The Python Core SDK provides a method to generate a client initialize response that can be used to bootstrap client SDKs without requiring network requests.
```python theme={null}
import json
from statsig_python_core import Statsig, StatsigUser
# Get client initialize response for a user
response_data = statsig.get_client_initialize_response(user)
response = json.loads(response_data)
# Pass response to a client SDK to initialize without a network request
```
The `get_client_initialize_response` method accepts the following parameters:
```python theme={null}
def get_client_initialize_response(
user: StatsigUser,
hash: Optional[str] = None,
client_sdk_key: Optional[str] = None,
include_local_overrides: Optional[bool] = None
) -> str:
```
* **`user`**: `StatsigUser` - The user to generate the initialize response for
* **`hash`**: `Optional[str]` - Algorithm used for hashing gate/experiment names (default: 'djb2')
* **`client_sdk_key`**: `Optional[str]` - Client SDK key to use for initialization
* **`include_local_overrides`**: `Optional[bool]` - Whether to include local overrides in the response
The `hash` parameter specifies which algorithm to use for hashing gate and experiment names in the client initialize response. The default is `'djb2'` for better performance and smaller payload size.
Available options:
* `'djb2'` (default) - DJB2 hashing algorithm for better performance
* `'sha256'` - SHA-256 hashing algorithm
* `'none'` - No hashing applied
```python theme={null}
# Use djb2 hashing algorithm (default)
response_data = statsig.get_client_initialize_response(user, hash='djb2')
# Use SHA-256 hashing algorithm
response_data = statsig.get_client_initialize_response(user, hash='sha256')
# Disable hashing
response_data = statsig.get_client_initialize_response(user, hash='none')
```
The `client_sdk_key` parameter lets you filter the response to only the specific feature gates, experiments, dynamic configs, layers, or parameter stores that a particular client key has access to - effectively letting you apply [target apps](/sdk-keys/target-apps/).
```python theme={null}
# Specify a client SDK key
response_data = statsig.get_client_initialize_response(
user,
client_sdk_key='client-key'
)
```
The `include_local_overrides` parameter determines whether to consider [local overrides](#local-overrides) you've set when evaluating each config in the response.
```python theme={null}
# Include local overrides in the response
response_data = statsig.get_client_initialize_response(
user,
include_local_overrides=True
)
```
Below is a complete example of using the client initialize response to bootstrap a client SDK. Note that you may choose to parallelize or inline the initialize response data with other requests to your server, to eliminate additional requests and latency.
```python theme={null}
# Server-side code
import json
from statsig_python_core import Statsig, StatsigUser, StatsigOptions
from flask import Flask, request, jsonify
app = Flask(__name__)
# Initialize the server SDK
options = StatsigOptions()
statsig = Statsig('server-secret-key', options)
statsig.initialize().wait()
# In your API endpoint handler
@app.route('/statsig-bootstrap')
def statsig_bootstrap():
# Create a user object from the request
user = StatsigUser(
user_id=request.args.get('userID', ''),
email=request.args.get('email'),
ip=request.remote_addr,
user_agent=request.headers.get('User-Agent')
)
# Generate the client initialize response
response_data = statsig.get_client_initialize_response(
user,
hash='djb2',
client_sdk_key='client-sdk-key'
)
# Parse the JSON response
statsig_values = json.loads(response_data)
# Return the values to the client
return jsonify({'statsigValues': statsig_values})
```
```javascript theme={null}
// Client-side code using @statsig/js-client
import { Statsig } from '@statsig/js-client';
// Fetch bootstrap values from your API
const response = await fetch('/statsig-bootstrap');
const { statsigValues } = await response.json();
// Initialize the client SDK with the bootstrap values
await Statsig.initialize({
sdkKey: 'client-sdk-key',
initializeValues: statsigValues,
});
```
The method returns a JSON string containing the client initialize response. You'll need to parse this string to access the data:
```python theme={null}
response_data = statsig.get_client_initialize_response(user)
response = json.loads(response_data)
# Access different parts of the response
feature_gates = response.get('feature_gates', {})
dynamic_configs = response.get('dynamic_configs', {})
layer_configs = response.get('layer_configs', {})
```
The response includes:
* `feature_gates`: Feature gate evaluations for the user
* `dynamic_configs`: Dynamic config and experiment evaluations
* `layer_configs`: Layer evaluations
* `has_updates`: Boolean indicating if there are updates
* `time`: Timestamp of the response
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant.
```python theme={null}
class PersistentStorage(PersistentStorageBaseClass):
def __init__():
# When you initialize, remember to call super.__init__()
super().__init__()
self.load_fn = self.load
self.save_fn = self.save
self.delete_fn = self.delete
def load(self, key: str) -> Optional[UserPersistedValues]:
"""
Load persisted values for a user from storage
Args:
key: A string key that uniquely identifies a user
Returns:
Dictionary mapping config names to their persisted values
"""
pass
def save(self, key: str, config_name: str, data: StickyValues):
"""
Save a persistent value for a user
Args:
key: A string key that uniquely identifies a user
config_name: The name of the config/experiment
data: The values to persist
"""
pass
def delete(self, key: str, config_name: str):
"""
Delete a persistent value for a user
Args:
key: A string key that uniquely identifies a user
config_name: The name of the config/experiment to delete
"""
pass
```
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
```python theme={null}
class DataStore(DataStoreBase):
def initialize(self):
"""
Initialize the data store. Called when the Statsig client initializes.
"""
pass
def shutdown(self):
"""
Clean up resources when the Statsig client shuts down.
"""
pass
def get(self, key: str) -> Optional[DataStoreResponse]:
"""
Retrieve value from the data store.
Args:
key: The key to retrieve the value for
Returns:
DataStoreResponse containing the result and time
"""
pass
def set(self, key: str, value: str, time: Optional[int] = None):
"""
Store a value in the data store.
Args:
key: The key to store the value under
value: The value to store
time: Optional timestamp
"""
pass
def support_polling_updates_for(self, key: str) -> bool:
"""
Whether the data store supports polling for updates for the given key.
Args:
key: The key to check
Returns:
True if polling is supported, False otherwise
"""
return False
```
## Custom Output Logger
The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity.
## Output Logger
The Output Logger Provider interface allows you to customize how the SDK logs internal messages.
```python theme={null}
class OutputLoggerProvider(OutputLoggerProviderBase):
def init(self):
"""
Initialize the logger. Called when the Statsig client initializes.
"""
pass
def debug(self, tag: str, msg: str):
"""
Log a debug message.
Args:
tag: Category/component tag for the message
msg: The message to log
"""
pass
def info(self, tag: str, msg: str):
"""
Log an info message.
Args:
tag: Category/component tag for the message
msg: The message to log
"""
pass
def warn(self, tag: str, msg: str):
"""
Log a warning message.
Args:
tag: Category/component tag for the message
msg: The message to log
"""
pass
def error(self, tag: str, msg: str):
"""
Log an error message.
Args:
tag: Category/component tag for the message
msg: The message to log
"""
pass
def shutdown(self):
"""
Clean up resources when the Statsig client shuts down.
"""
pass
```
## Observability Client
The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the [Monitoring documentation](/sdk_monitoring).
```python theme={null}
class ObservabilityClient(ObservabilityClientBase):
def init(self):
"""
Initialize the observability client. Called when the Statsig client initializes.
"""
pass
def increment(self, metric_name: str, value: float, tags: Optional[Dict[str, str]] = None):
"""
Report a counter metric.
Args:
metric_name: The name of the metric
value: The amount to increment by
tags: Optional tags to associate with the metric
"""
pass
def gauge(self, metric_name: str, value: float, tags: Optional[Dict[str, str]] = None):
"""
Report a gauge metric.
Args:
metric_name: The name of the metric
value: The current value
tags: Optional tags to associate with the metric
"""
pass
def dist(self, metric_name: str, value: float, tags: Optional[Dict[str, str]] = None):
"""
Report a distribution metric.
Args:
metric_name: The name of the metric
value: The value to record
tags: Optional tags to associate with the metric
"""
pass
def error(self, tag: str, error: str):
"""
Report an error.
Args:
tag: Category/component tag for the error
error: The error message
"""
pass
def should_enable_high_cardinality_for_this_tag(self, tag: str) -> bool:
"""
Determine if high cardinality should be enabled for a tag.
Args:
tag: The tag to check
Returns:
True if high cardinality should be enabled, False otherwise
"""
pass
```
## FAQ
See the guide on [device level experiments](/guides/first-device-level-experiment).
## Reference
### API Methods
* `check_gate(user: StatsigUser, gate_name: str, options: Optional[FeatureGateEvaluationOptions] = None) -> bool`
* `get_dynamic_config(user: StatsigUser, config_name: str, options: Optional[DynamicConfigEvaluationOptions] = None) -> DynamicConfig`
* `get_experiment(user: StatsigUser, experiment_name: str, options: Optional[ExperimentEvaluationOptions] = None) -> DynamicConfig`
* `get_layer(user: StatsigUser, layer_name: str, options: Optional[LayerEvaluationOptions] = None) -> Layer`
* `get_feature_gate(user: StatsigUser, gate_name: str, options: Optional[FeatureGateEvaluationOptions] = None) -> FeatureGate`
* `get_parameter_store(user: StatsigUser, parameter_store_name: str, options: Optional[ParameterStoreEvaluationOptions] = None) -> ParameterStore`
* `log_event(user: StatsigUser, event_name: str, value: Optional[Union[str, float]] = None, metadata: Optional[Dict[str, str]] = None) -> None`
* `manually_log_gate_exposure(user: StatsigUser, gate_name: str) -> None`
* `manually_log_dynamic_config_exposure(user: StatsigUser, config_name: str) -> None`
* `manually_log_experiment_exposure(user: StatsigUser, experiment_name: str) -> None`
* `manually_log_layer_parameter_exposure(user: StatsigUser, layer_name: str, parameter_name: str) -> None`
* `override_experiment_by_group_name(experiment_name: str, group_name: str, id: Optional[str] = None) -> None`
* `get_client_initialize_response(user: StatsigUser, options: Optional[ClientInitializeResponseOptions] = None) -> ClientInitializeResponse`
* `shutdown() -> AsyncResult[None]`
### Fields Needed Methods
The following methods return information about which user fields are needed for evaluation:
* `get_gate_fields_needed(gate_name: str) -> List[str]`
* `get_dynamic_config_fields_needed(config_name: str) -> List[str]`
* `get_experiment_fields_needed(experiment_name: str) -> List[str]`
* `get_layer_fields_needed(layer_name: str) -> List[str]`
These methods return a list of strings representing the user fields that are required to properly evaluate the specified gate, config, experiment, or layer.
# Rust Server SDK
Source: https://docs.statsig.com/server-core/rust-core
Statsig's next-generation Rust Server SDK built on the Server Core framework, with improved performance and a unified evaluation engine for Rust backends.
Rust Core on Github ,
Cargo Package
## Setup the SDK
To use the SDK, add the Statsig Rust package to your Cargo.toml file:
```toml theme={null}
[dependencies]
statsig-rust = "X.Y.Z" # Replace with the latest version
```
Or, you can use the cargo command:
```shell theme={null}
cargo add statsig-rust
```
You can find the latest version and documentation at [crates.io/crates/statsig-rust](https://crates.io/crates/statsig-rust).
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a StatsigOptions to customize the SDK.
```rust theme={null}
use statsig_rust::{Statsig, StatsigOptions};
use std::sync::Arc;
// Simple initialization
let statsig = Statsig::new("server-secret-key", None);
statsig.initialize().await?;
// Or with StatsigOptions
let mut options = StatsigOptions::default();
options.environment = Some("development".to_string());
let statsig = Statsig::new("server-secret-key", Some(Arc::new(options)));
statsig.initialize().await?;
// Don't forget to shutdown when done
statsig.shutdown().await?;
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
### Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```rust theme={null}
use statsig_rust::{Statsig, StatsigUserBuilder};
let user = StatsigUserBuilder::new_with_user_id("a-user".to_string()).build();
if statsig.check_gate(&user, "a_gate") {
// Gate is on, enable new feature
} else {
// Gate is off
}
```
### Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:
```rust theme={null}
use statsig_rust::{Statsig, StatsigUserBuilder, DynamicConfigEvaluationOptions};
use std::sync::Arc;
// Get a dynamic config for a specific user
let user = StatsigUserBuilder::new_with_user_id("my_user".to_string()).build();
let config = statsig.get_dynamic_config(&user, "a_config");
// Access config values with type-safe getters and fallback values
let product_name = config.get_string("product_name", "Awesome Product v1"); // returns String
let price = config.get_double("price", 10.0); // returns f64
let should_discount = config.get_bool("discount", false); // returns bool
let quantity = config.get_int("quantity", 1); // returns i64
// Advanced Usage:
// You can disable exposure logging for this specific check
let mut options = DynamicConfigEvaluationOptions::default();
options.disable_exposure_logging = Some(true);
let config = statsig.get_dynamic_config_with_options(&user, "a_config", &options);
// The config object also provides metadata about the evaluation
println!("{}", config.rule_id); // The ID of the rule that served this config
println!("{}", config.id_type); // The type of the evaluation (experiment, config, etc)
```
### Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of [layers](/layers), which make parameters reusable and let you run mutually exclusive experiments.
```rust theme={null}
use statsig_rust::{Statsig, StatsigUserBuilder};
// Values via get_layer
let user = StatsigUserBuilder::new_with_user_id("my_user".to_string()).build();
let layer = statsig.get_layer(&user, "user_promo_experiments");
let title = layer.get_string("title", "Welcome to Statsig!");
let discount = layer.get_double("discount", 0.1);
// Via get_experiment
let title_exp = statsig.get_experiment(&user, "new_user_promo_title");
let price_exp = statsig.get_experiment(&user, "new_user_promo_price");
let title = title_exp.get_string("title", "Welcome to Statsig!");
let discount = price_exp.get_double("discount", 0.1);
```
### Parameter Stores
Sometimes you don't know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.
```jsx theme={null}
let param_store = statsig.get_parameter_store("my_parameters");
let param_store_value = param_store.get(&user, "my_parameter_value", false); //false is fallback value
println!("param_store_value: {}", param_store_value);
```
### Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```rust theme={null}
use statsig_rust::{Statsig, StatsigUserBuilder};
use std::collections::HashMap;
use crate::evaluation::dynamic_value::DynamicValue;
// Create a user
let user = StatsigUserBuilder::new_with_user_id("user_id".to_string()).build();
// Create metadata hashmap
let mut metadata = HashMap::new();
metadata.insert("price".to_string(), "9.99".into());
metadata.insert("item_name".to_string(), "diet_coke_48_pack".into());
// Log the event
statsig.log_event(
&user,
"add_to_cart",
Some("SKU_12345".into()), // value as DynamicValue
Some(metadata)
);
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
### Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```rust theme={null}
use statsig_rust::{Statsig, StatsigUserBuilder};
// Create a user
let user = StatsigUserBuilder::new_with_user_id("user_id".to_string()).build();
// Get a feature gate
let gate = statsig.get_feature_gate(&user, "example_gate");
// Access gate properties
println!("{}", gate.rule_id);
println!("{}", gate.value); // Boolean value of the gate
```
## Using Shared Instance
In some applications, you may want to create a single Statsig instance that can be accessed globally throughout your codebase. The shared instance functionality provides a singleton pattern for this purpose:
```rust theme={null}
// Create a shared instance that can be accessed globally
let statsig = Statsig::new_shared("server-secret-key", None).unwrap();
statsig.initialize().await?;
// Access the shared instance from anywhere in your code
let shared_statsig = Statsig::shared();
let is_feature_enabled = shared_statsig.check_gate(&user, "feature_name");
// Check if a shared instance exists
if Statsig::has_shared_instance() {
// Use the shared instance
}
// Remove the shared instance when no longer needed
Statsig::remove_shared();
```
The shared instance functionality provides a singleton pattern where a single Statsig instance can be created and accessed globally throughout your application. This is useful for applications that need to access Statsig functionality from multiple parts of the codebase without having to pass around a Statsig instance.
* `Statsig::new_shared(sdk_key, options)`: Creates a new shared instance of Statsig that can be accessed globally
* `Statsig::shared()`: Returns the shared instance
* `Statsig::has_shared_instance()`: Checks if a shared instance exists (useful when you aren't sure if the shared instance is ready yet)
* `Statsig::remove_shared()`: Removes the shared instance (useful when you want to switch to a new shared instance)
`has_shared_instance()` and `remove_shared()` are helpful in specific scenarios but aren't required in most use cases where the shared instance is set up near the top of your application.
Also note that only one shared instance can exist at a time. Attempting to create a second shared instance will result in an error.
## Manual Exposures
By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or call get() on a parameter in a layer. However, there are times when you may want to log an exposure event manually. For example, if you're using a gate to control access to a feature, but you don't want to log an exposure until the user actually uses the feature, you can use manual exposures.
All of the main SDK functions (`check_gate`, `get_dynamic_config`, `get_experiment`, `get_layer`) accept an options parameter with a `disable_exposure_logging` field. When this is set to `true`, the SDK will not automatically log an exposure event. You can then manually log the exposure at a later time using the corresponding manual exposure logging method:
```rust theme={null}
result = statsig.check_gate_with_options(&user, 'a_gate_name', FeatureGateEvaluationOptions {disable_exposure_logging: true});
```
```rust theme={null}
statsig.manually_log_gate_exposure(&user, 'a_gate_name')
```
```rust theme={null}
config = statsig.get_dynamic_config_with_options(&user, 'a_dynamic_config_name', DynamicConfigEvaluationOptions {disable_exposure_logging: true});
```
```rust theme={null}
statsig.manually_log_dynamic_config_exposure(&user, 'a_dynamic_config_name')
```
```rust theme={null}
experiment = statsig.get_experiment_with_options(&user, 'an_experiment_name', ExperimentEvaluationOptions {disable_exposure_logging: true});
```
```rust theme={null}
statsig.manually_log_experiment_exposure(&user, 'an_experiment_name')
```
```rust theme={null}
layer = statsig.get_layer_with_options(&user, 'a_layer_name', LayerEvaluationOptions {disable_exposure_logging: true});
paramValue = layer.get('a_param_name', 'fallback_value')
```
```rust theme={null}
statsig.manually_log_layer_parameter_exposure(&user, 'a_layer_name', 'a_param_name')
```
## Statsig User
The `StatsigUser` object represents a user in Statsig. You must provide a `userID` or at least one of the `customIDs` to identify the user.
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
### Private Attributes
Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don't want to send to third-party services.
```rust theme={null}
use statsig_rust::StatsigUserBuilder;
use std::collections::HashMap;
// Create a user with just a user ID
let user = StatsigUserBuilder::new_with_user_id("user-123".to_string())
.build();
// Or create a user with custom IDs
let mut custom_ids = HashMap::new();
custom_ids.insert("employee_id".to_string(), "emp-456".to_string());
let user_with_custom_ids = StatsigUserBuilder::new_with_custom_ids(custom_ids)
.build();
// Create a user with several properties
let mut custom_fields = HashMap::new();
custom_fields.insert("plan".to_string(), "premium".into());
custom_fields.insert("age".to_string(), 25.into());
let user = StatsigUserBuilder::new_with_user_id("user-123".to_string())
.email(Some("user@example.com".to_string()))
.ip(Some("192.168.1.1".to_string()))
.user_agent(Some("Mozilla/5.0...".to_string()))
.country(Some("US".to_string()))
.locale(Some("en-US".to_string()))
.app_version(Some("1.0.0".to_string()))
.custom(Some(custom_fields))
.build();
// Private Attributes (not forwarded to integrations)
let mut private_attrs = HashMap::new();
private_attrs.insert("internal_id".to_string(), "emp-123".into());
let user_with_private = StatsigUserBuilder::new_with_user_id("user-123".to_string())
.email(Some("user@example.com".to_string()))
.private_attributes(Some(private_attrs))
.build();
```
## Statsig Options
You can pass in an optional parameter `options` in addition to `sdkKey` during initialization to customize the Statsig client. Here are the available options that you can configure.
External data store for Statsig values.
When true, disables all event logging.
When `true`, disables all network functions: event & exposure logging, spec downloads, and ID List downloads. Formerly called "localMode".
Enable/disable ID list functionality. **Required to be `true` when using segments with more than 1000 IDs.** See [ID List segments](/segments/add-id-list) for more details.
If set to true, the SDK will NOT attempt to parse UserAgents (attached to the user object) into browserName, browserVersion, systemName, systemVersion, and appVersion at evaluation time, when needed for evaluation.
When set to true, the SDK will wait until user agent parsing data is fully loaded during initialization. This may slow down by \~1 second startup but ensures that parsing of the user's userAgent string into fields like browserName, browserVersion, systemName, systemVersion, and appVersion is ready before any evaluations.
If set to true, the SDK will NOT attempt to parse IP addresses (attached to the user object at user.ip) into Country codes at evaluation time, when needed for evaluation.
When set to true, the SDK will wait for country lookup data (e.g., GeoIP or YAML files) to fully load during initialization. This may slow down by \~1 second startup but ensures that IP-to-country parsing is ready at evaluation time.
Environment parameter for evaluation.
Custom adapter for event logging.
How often events are flushed to Statsig servers (in milliseconds).
Maximum number of events to queue before forcing a flush.
* Default is `2000`
* event\_logging\_max\_queue\_size \* event\_logging\_max\_pending\_batch\_queue\_size is the upper limit on how many events are queued
* See also `event_logging_max_pending_batch_queue_size`
Maximum number of event batches to hold in buffer to retry.
* Default is `100`.
* event\_logging\_max\_queue\_size \* event\_logging\_max\_pending\_batch\_queue\_size is the upper limit on how many events are queued
* eg: 2000 \* 100 means the SDK can process 200k event per second before events start getting dropped
* See also `event_logging_max_queue_size`.
Whether to fallback to the Statsig API if custom endpoints fail.
Custom adapter for ID lists.
How often the SDK updates ID lists from Statsig servers (in milliseconds).
Custom URL for fetching ID lists.
Sets the maximum timeout for initialization requests (in milliseconds).
Custom URL for logging events.
Client for collecting observability data.
Controls the verbosity of SDK logs.
Custom adapter for overrides.
Configuration for specification adapters.
Custom adapter for specifications.
How often the SDK updates specifications from Statsig servers (in milliseconds).
Custom URL for fetching feature specifications.
Global custom fields to include with all evaluations.
Configuration for connecting through a proxy server. The `ProxyConfig` struct has the following properties:
* `proxy_host`: Option\ - Specifies the proxy server host
* `proxy_port`: Option\ - Specifies the proxy server port
* `proxy_auth`: Option\ - For proxy authentication (format: `"username:password"`)
* `proxy_protocol`: Option\ - Specifies the protocol (e.g., `"http"`, `"https"`)
* `ca_cert_path`: Option\ - Optional path to a PEM CA bundle for outbound TLS
### Example Usage
```rust theme={null}
use statsig_rust::{Statsig, StatsigOptions};
use std::sync::Arc;
// Initialize StatsigOptions with custom parameters
let mut options = StatsigOptions::default();
options.environment = Some("development".to_string());
options.init_timeout_ms = Some(3000);
options.disable_all_logging = Some(false);
options.enable_id_lists = Some(true);
options.output_log_level = Some(LogLevel::Info); // LogLevel enum, not a string
// Pass the options object into Statsig::new()
let statsig = Statsig::new("server-secret-key", Some(Arc::new(options)));
statsig.initialize().await?;
// Or, use the builder pattern for a more fluent interface
let options = StatsigOptions::builder()
.environment(Some("development".to_string()))
.init_timeout_ms(Some(3000))
.disable_all_logging(Some(false))
.enable_id_lists(Some(true))
.specs_sync_interval_ms(Some(30000))
// Configure proxy settings
.proxy_config(Some(ProxyConfig {
proxy_host: Some("proxy.example.com".to_string()),
proxy_port: Some(8080),
proxy_protocol: Some("https".to_string()),
proxy_auth: None, // Use Some("username:password".to_string()) if authentication is required
ca_cert_path: Some("/etc/ssl/certs/corporate-ca.pem".to_string()),
}))
.build();
// Pass the options object into Statsig::new()
let statsig = Statsig::new("server-secret-key", Some(Arc::new(options)));
statsig.initialize().await?;
```
### Proxy and Custom Network Routing
Use `proxy_config` if your service needs a standard outbound HTTP proxy. If you need to route config sync through [Statsig Forward Proxy](/infrastructure/forward-proxy) or another custom source, use `spec_adapters_config` or `specs_url` instead. Set `ca_cert_path` when your environment requires a custom PEM CA bundle for outbound TLS.
## Shutting Statsig Down
Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call `shutdown()` before your app/server shuts down:
```rust theme={null}
statsig.shutdown().await?;
```
Alternatively, you can manually flush events without shutting down:
```rust theme={null}
// Manually flush events to the server
statsig.flush_events().await;
```
## SDK Event Subscriptions
The Statsig SDK provides an event subscription system that allows you to listen for evaluation events and lifecycle events in real-time. This feature is useful for debugging, analytics, custom logging, and integrating with external systems.
### Supported Events
The SDK supports subscribing to the following evaluation events:
* **`gate_evaluated`** - Fired when a feature gate is evaluated for a user
* **`dynamic_config_evaluated`** - Fired when a dynamic config is retrieved for a user
* **`experiment_evaluated`** - Fired when an experiment is evaluated for a user
* **`layer_evaluated`** - Fired when a layer is evaluated for a user
* **`specs_updated`** - Fired when the SDK updates its cached specs, including where the specs were loaded from
* **`"*"`** - Subscribe to all evaluation events
### SDK Event Data
Each event includes relevant context about the evaluation:
* **Gate Evaluated Events** include: `gate_name`, `value` (boolean), `rule_id`, `reason`
* **Dynamic Config Events** include: the full `dynamic_config` object with values and metadata
* **Experiment Events** include: the full `experiment` object with variant assignment and parameters
* **Layer Events** include: the full `layer` object with allocated experiment and parameters
* **Specs Updated Events** include `source`, `source_api`, and `values` metadata, where `values.time` is the timestamp of the last update to the project in the Statsig console
### Use Cases
Event subscriptions are particularly useful for:
* **Debugging**: Monitor which features are being evaluated and their results
* **Analytics**: Track feature usage patterns and user segments
* **Custom Logging**: Send evaluation data to your own logging systems
* **Integration**: Forward events to external analytics or monitoring tools
* **Testing**: Verify that features are being evaluated as expected
### Best Practices
* **Clean up subscriptions**: Always unsubscribe when you no longer need to listen for events to prevent memory leaks
* **Handle event data carefully**: Event objects may contain sensitive user information depending on your configuration
* **Use specific event types**: Subscribe to specific events rather than "\*" when possible for better performance
* **Avoid heavy processing**: Keep event handlers lightweight to avoid impacting SDK performance
```rust theme={null}
use statsig_rust::{Statsig, StatsigUserBuilder, sdk_event_emitter::SdkEvent};
let statsig = Statsig::new("server-secret-key", None)?;
statsig.initialize().await?;
// Subscribe to gate evaluation events
let gate_sub_id = statsig.subscribe(SdkEvent::GATE_EVALUATED, |event| {
if let SdkEvent::GateEvaluated { gate_name, value, rule_id, reason } = event {
println!("Gate evaluated: {} = {}, rule: {}, reason: {}",
gate_name, value, rule_id, reason);
}
});
// Subscribe to dynamic config evaluation events
let config_sub_id = statsig.subscribe(SdkEvent::DYNAMIC_CONFIG_EVALUATED, |event| {
if let SdkEvent::DynamicConfigEvaluated { dynamic_config } = event {
println!("Config evaluated: {}", dynamic_config.name);
}
});
// Subscribe to experiment evaluation events
let experiment_sub_id = statsig.subscribe(SdkEvent::EXPERIMENT_EVALUATED, |event| {
if let SdkEvent::ExperimentEvaluated { experiment } = event {
println!("Experiment evaluated: {} -> {}",
experiment.name, experiment.group_name);
}
});
// Subscribe to layer evaluation events
let layer_sub_id = statsig.subscribe(SdkEvent::LAYER_EVALUATED, |event| {
if let SdkEvent::LayerEvaluated { layer } = event {
println!("Layer evaluated: {}", layer.name);
}
});
let specs_updated_sub_id = statsig.subscribe(SdkEvent::SPECS_UPDATED, |event| {
if let SdkEvent::SpecsUpdated {
source,
source_api,
values,
} = event
{
println!(
"Specs updated from {} via {} (project last edited at {})",
source, source_api, values.time
);
}
});
// Subscribe to all events
let all_events_sub_id = statsig.subscribe(SdkEvent::ALL, |event| {
println!("Event received: {}", event.get_name());
});
// Unsubscribe from specific event types
statsig.unsubscribe(SdkEvent::GATE_EVALUATED);
statsig.unsubscribe(SdkEvent::SPECS_UPDATED);
// Unsubscribe using subscription ID
statsig.unsubscribe_by_id(&config_sub_id);
// Unsubscribe from all events
statsig.unsubscribe_all();
```
## Local Overrides
Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console.
```Rust theme={null}
// Overrides the given gate to the specified value
statsig.override_gate("test_gate", true, None);
// Overrides the given dynamic config to the provided value
statsig.override_dynamic_config("test_1", my_map.clone(), None); //my_map is HashMap
// Overrides the given experiment to the provided value
statsig.override_experiment("test_xp_1", my_map.clone(), None); //my_map is HashMap
// Overrides the given experiment to a particular groupname, available for experiments only
statsig.override_experiment_by_group_name("test_xp_1", "a_group_name", None);
// Overrides the given layer to the provided value
statsig.override_layer("user_promo_experiments", my_map.clone(), None); //my_map is HashMap
//Alternatively, get the Experiment object for a given groupName
let group_exp = statsig.get_experiment_by_group_name("pricing_experiment", "premium_group");
let premium_price = group_exp.get_double("price", 9.99);
```
## Persistent Storage
The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant.
```rust theme={null}
pub trait PersistentStorageTrait: Send + Sync {
fn load(&self, key: &str) -> Result, PersistentStorageErrorEnum>;
fn save(&self, key: &str, config_name: &str, data: &StickyValues) -> Result<(), PersistentStorageErrorEnum>;
fn delete(&self, key: &str, config_name: &str) -> Result<(), PersistentStorageErrorEnum>;
}
```
## Data Store
The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems.
```rust theme={null}
pub trait DataStoreTrait: Send + Sync {
fn initialize(&self) -> Result<(), DataStoreErrorEnum>;
fn shutdown(&self) -> Result<(), DataStoreErrorEnum>;
fn get(&self, key: &str) -> Result, DataStoreErrorEnum>;
fn set(&self, key: &str, value: &str, time: Option) -> Result<(), DataStoreErrorEnum>;
fn support_polling_updates_for(&self, key: &str) -> Result;
}
pub struct DataStoreResponse {
pub result: String,
pub time: Option,
}
```
## Custom Output Logger
The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity.
```rust theme={null}
pub trait OutputLogProvider: Send + Sync {
fn initialize(&self);
fn debug(&self, tag: &str, msg: String);
fn info(&self, tag: &str, msg: String);
fn warn(&self, tag: &str, msg: String);
fn error(&self, tag: &str, msg: String);
fn shutdown(&self);
}
```
## Observability Client
The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the [Monitoring documentation](/sdk_monitoring).
```rust theme={null}
pub trait ObservabilityClient: Send + Sync {
fn init(&self);
fn increment(&self, metric_name: &str, value: f64, tags: &HashMap);
fn gauge(&self, metric_name: &str, value: f64, tags: &HashMap);
fn dist(&self, metric_name: &str, value: f64, tags: &HashMap);
fn error(&self, tag: &str, error: &str);
}
```
## Fields Needed Methods (Enterprise Only)
This is available for Enterprise contracts. Please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
These methods allow you to retrieve a list of user fields that are used in the targeting rules for gates, configs, experiments, and layers.
### Description
These methods return an array of strings representing the user fields that are referenced in the targeting rules or conditions of the specified feature. This can be useful for understanding which user properties influence a particular feature's behavior.
```rust theme={null}
// Get fields needed for a gate
let fields_needed: Vec = statsig.get_fields_needed_for_gate("gate_name");
// Get fields needed for a dynamic config
let fields_needed: Vec = statsig.get_fields_needed_for_dynamic_config("config_name");
// Get fields needed for an experiment
let fields_needed: Vec = statsig.get_fields_needed_for_experiment("experiment_name");
// Get fields needed for a layer
let fields_needed: Vec = statsig.get_fields_needed_for_layer("layer_name");
```
### Field Mapping
The fields returned by these methods correspond to the following user properties:
```rust theme={null}
// Field mapping between user properties and internal field names
let field_mapping = std::collections::HashMap::from([
("userID", "u"),
("email", "e"),
("ip", "i"),
("userAgent", "ua"),
("country", "c"),
("locale", "l"),
("appVersion", "a"),
("time", "t"),
("stableID", "s"),
("environment", "en"),
("targetApp", "ta"),
]);
// Custom fields are prefixed with "cf:"
// Example: fields.add("cf:" + field_name);
```
## FAQ
See the guide on [device level experiments](/guides/device-level-experiments)
## Reference
### Fields Needed Methods (Enterprise Only)
```rust theme={null}
// Get user fields needed for a gate evaluation
pub fn get_fields_needed_for_gate(&self, gate_name: &str) -> Vec
// Get user fields needed for a dynamic config evaluation
pub fn get_fields_needed_for_dynamic_config(&self, config_name: &str) -> Vec
// Get user fields needed for an experiment evaluation
pub fn get_fields_needed_for_experiment(&self, experiment_name: &str) -> Vec
// Get user fields needed for a layer evaluation
pub fn get_fields_needed_for_layer(&self, layer_name: &str) -> Vec
```
This is available for Enterprise contracts. Please reach out to our support team, your sales contact, or via our [Slack community](https://statsig.com/slack) if you want this enabled.
These methods allow you to retrieve a list of user fields that are used in the targeting rules for gates, configs, experiments, and layers.
#### Description
These methods return an array of strings representing the user fields that are referenced in the targeting rules or conditions of the specified feature. This can be useful for understanding which user properties influence a particular feature's behavior.
#### Field Mapping
The fields returned by these methods correspond to the following user properties:
```
// Field mapping between user properties and internal field names
const fieldMapping = {
userID: 'u',
email: 'e',
ip: 'i',
userAgent: 'ua',
country: 'c',
locale: 'l',
appVersion: 'a',
time: 't',
stableID: 's',
environment: 'en',
targetApp: 'ta',
};
// Custom fields are prefixed with "cf:"
// Example: fields.add('cf:' + field);
```
# Ingesting Cloudflare Logs and Metrics into Statsig
Source: https://docs.statsig.com/server/concepts/cloudflare
Run Statsig server SDK evaluations inside Cloudflare Workers, including configuration, request lifecycle, and how to log exposures from the edge.
## Overview
This guide walks you through setting up the Cloudflare Logpush worker in your Cloudflare account and configuring it to send logs and metrics to Statsig using cURL and the Logpush API
***
## ✅ Prerequisites
* [Cloudflare Logpush enabled for your account](https://developers.cloudflare.com/logs/logpush/)
* [Statsig Server SDK Key](/server-core/)
***
## Configuring Logpush Worker
1. [Create api token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
2. Make sure token has logs edit permissions at the account level
3. [Locate cloudflare account ID](https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/)
4. Run the following command and get the job id
```
ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/logpush/jobs" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"name": "statsig-logpush-job",
"destination_conf": "https://api.statsig.com/v1/log_event/cf_log_drain?header_statsig-api-key=&header_Content-Type=application%2Fjson",
"dataset": "workers_trace_events",
"output_options": {
"field_names": [],
"output_type": "ndjson",
"batch_prefix": "{\"events\":[",
"batch_suffix": "\n]}\n",
"record_prefix": "\n {\"info\":{",
"record_suffix": "}}",
"record_delimiter": ",",
"timestamp_format": "rfc3339"
}
}'
```
* In Cloudflare dashboard, navigate to "Analytics & Logs" -> "Logpush", and enable the logpush job
## Verify Logs on Statsig Console
Explore your Logs and Metrics at [console.statsig.com](http://console.statsig.com) with the Logs Explorer and Metrics Explorer products under Analytics on the sidebar menu 🙂
***
## 🔗 Resources
* [Manage Logpush with cURL](https://developers.cloudflare.com/logs/logpush/examples/example-logpush-curl/)
* [Logpush output types](https://developers.cloudflare.com/logs/logpush/logpush-job/log-output-options/#output-types)
* [Create logpush API docs](https://developers.cloudflare.com/api/resources/logpush/subresources/jobs/methods/create/)
# Server Data Stores / Data Adapter
Source: https://docs.statsig.com/server/concepts/data_store
Configure a custom data store adapter in Statsig server SDKs to cache rule configurations in Redis, DynamoDB, or another store you control.
One common question when configuring Statsig is how to design your integration around handling potential points of failure. For example - in case of a Statsig API outage, can my integration continue to function?
The short answer is yes. Your server SDK will continue to operate normally, serving the most recent set of known values in response to calls like `checkGate`, `getConfig`, `getExperiment`, and `getLayer`.
Once the API is back up and operating normally, your SDK will automatically refetch the most up-to-date version of your project.
But what about spinning up a new server, or a new SDK instance, while Statsig is down?
This is what we built the `DataAdapter`/`DataStore` for.
## DataAdapter (or DataStore)
DataAdapters allow you to plug in your own storage solution as a cache that the Statsig Server SDKs use to load your project configurations (ie; all experiments, configs, gates and their targeting/allocation rules). Some of the key use-cases for Data Adapter are: reducing dependency on Statsig servers for initialization, improving initialization time by loading config from a local data store, and providing customers with controls for minimizing network I/O. Data Adapters define a simple API that you have to implement: `initialize`, `get`, `set`, and `shutdown` for setup, reading, writing, and closing.
### Recommended Implementation
In most cases, **your webservers should only implement the read path (`get`)**.\
Leaving the write path (`set`) empty is the best practice. Otherwise, every SDK instance across all of your servers will attempt to write to the store whenever it sees an update, which is inefficient and can lead to unnecessary contention or duplication.
Instead, you should have a single source of truth that keeps your datastore up-to-date:
* Run a **separate out-of-band service** that implements the SDK and is responsible for writing updates into the datastore via `set`.
* Or, use a **cron job / periodic job** to fetch the config from the Statsig CDN endpoint and update your datastore under the correct cache keys (`statsig.cache`, `statsig.id_lists`, and `statsig.id_lists::{list_name}`).
The Statsig SDK already handles this refresh logic out of the box, so separating the read and write responsibilities is the cleanest and most reliable pattern.
### Data Adapter Logic
* When the Statsig SDK is initialized with a DataAdapter, it will first attempt to load config via `DataAdapter.get`.
* If the entry exists, it will use it.
* If the entry does not exist, and `localMode` is not enabled, it will fetch the config from Statsig servers and (if you have a writer service) persist it via `DataAdapter.set`.
* Post-initialization, the SDK will continue to poll Statsig servers for updates and, when available, save them back to your data store (if you’ve implemented `set` and designated a writer service).
* If the SDK client is initialized with `localMode=true`, this will disable all network fetches from Statsig.
* The cache keys used to be:
* `statsig.cache` → config specs
* `statsig.id_lists` → lookup of id lists
* `statsig.id_lists::{list_name}` → actual id list values
* but in the latest node and server core sdks, the format has changed:
* `statsig|{path}|{format}|{hashedSDKKey}` where `path` is `/v1/download_config_specs` or `/v1/get_id_lists`, format is `plain_text`, and the `djb2` has of the sdk key is the last bit
* the SDK will handle this for you, reach out if you are trying to recreate this path yourself to double check
Most DataAdapters are currently only used for the `initialize` path for getting a project definition.
At the time of this writing, only `Node.js`, `Ruby`, `Go`, `Java` and `.NET` support polling for updates.\
If you're interested in using a DataAdapter as the source of truth indefinitely, please reach out in our [Slack community](https://statsig.com/slack) and let us know which language this would be useful for!
For information on your specific SDK language, see the language-specific docs in the left-hand column.
# Forward Proxy
Source: https://docs.statsig.com/server/concepts/forward_proxy
Use a forward proxy with Statsig server SDKs to route outbound traffic through your network so SDKs can run in restricted environments.
## Statsig Forward Proxy
The Statsig Forward Proxy is a service that we developed to be hosted and run in your own infrastructure. If SDKs are configured to use the forward proxy, it provides a closer, but also more reliable hop for retrieving Statsig dependent configurations from within your infrastructure instead of reaching out to our networks.
The expected benefits of using the proxy are:
1. Reduced dependency on Statsig Infrastructure Availability
2. Improved performance through localization of download\_config\_spec to your cluster
3. Improved cost savings and reduced network overhead through minimizing requests to Statsig Infrastructure
4. Improved consistency of configurations, as the forward proxy becomes an articulation point for serving configs
5. Support for cool features such as a streaming API through GRPC
If you have any questions about how to deploy, or need assistance, feel free to reach out to us on our slack channel or create a new github issue.
### Installation
#### Helm Installation
The recommended way to install Statsig Forward Proxy in a Kubernetes environment is using the official Helm chart. Follow these steps to deploy:
```bash theme={null}
# Add the Statsig Helm repository
helm repo add statsig https://statsig-helm.storage.googleapis.com
helm repo update
# Install the chart
helm install statsig-forward-proxy statsig/statsig-forward-proxy
```
The Helm chart provides extensive configuration options for customizing your deployment. For detailed configuration options, refer to the [Statsig Forward Proxy Helm chart documentation](https://github.com/statsig-io/statsig-forward-proxy/blob/main/chart/README.md).
#### Manual Deployment
For environments where Helm is not available or for more customized deployments, Statsig Forward Proxy can be deployed manually. The proxy is available as a pre-built Docker image, and you can also build your own binary from source.
For detailed instructions on manual deployment options and available configuration parameters, refer to the [Manual Deployment section in the GitHub repository](https://github.com/statsig-io/statsig-forward-proxy/tree/main?tab=readme-ov-file#manual-deployment).
### How Forward Proxy works
The forward proxy works by setting up a local http or grpc server. When requests are made to the forward proxy, only the initial request is blocking, after that, a background loop is spawned which keeps configurations up to date without impacting the hot path for serving configurations.
While providing this capability, the forward proxy also provides other benefits such the ability to enable backup caches and monitoring through technologies such as Redis and Statsd.
## Integration with SDK
`Legacy Java/Kotlin`, `Legacy Python`, `Python Server Core` and `Node Server Core` SDKs provide the option for Forward Proxy integration with GRPC streaming. For other server SDKs, you can integrate with the Forward Proxy via HTTP by overriding the initialize endpoints in StatsigOptions. Feel free to consult us in [Slack](https://statsig.com/slack) on this approach.
You can now configure SDK network using different network protocol to integrate with Statsig Forward Proxy for different endpoints.
There are 3 network endpoints SDK make requests to download\_config\_specs,get\_id\_lists, and log\_events, and you can currently configure the download\_config\_specs to use the proxy. We are actively developing the latter two.
#### Network protocol for different endpoints
For `download_config_specs` endpoint, where we get specs on evaluating gates/layers/experiments/configs
1. `http`: the default protocol. If SDK is initialized with http, it will poll config updates in background thread.
2. `grpc_websocket`: Establish a grpc streaming from SDK to statsig forward proxy, and listen to updates being pushed from proxy servers. You have to use statsig forward proxy or have a similar proxy server in order to use grpc streaming. Note: Not all SDKs support GRPC yet, if you have an SDK you want support for please reach out to our support channel on slack.
3. `grpc`: Unary RPC, behave similarly to HTTP protocol, after initialization, SDK poll changes from forward proxy server in background thread.
#### Listen to Config Change Example
```typescript theme={null}
const statsigOptions = {
proxyConfigs: {
download_config_specs: {
proxyAddress: proxyAddress // Your proxy address
protocol: "grpc_websocket"
}
}
}
Statsig.initialize(server_key, statsigOptions)
// Statsig will use listen for config updates from statsig forward proxy using grpc_websocket protocol. And use http to get idlists and post log events from statsig servers.
```
For information on your specific SDK language, see the language specific docs in the left hand column.
#### Failover behavior
**Initialization**
SDK remains the same behavior when forward proxy is being used. But there are several configurations you can use to improve the data availability during initialization.
Default behavior is SDK will get from forward proxy. If DataAdapter is presented, get from DataAdapter first, and fallback to Forward Proxy if there is no value served from data adapter.
There are several ways you can configure the behavior here.
1. set fallbackToStatsigAPI = true. If you want to fallback to statsig api when initialization or config sync from original sources is false
2. If you want to customize your own order of initialization set initializeSources to have multiple sources,for example initializeSources=\[DataSource.Network, DataSource.DataAdapter, DataSource.StatsigNetwork] will fetch from 3 sources sequentially until it successfully find one
**Config Sync (Post initialization)**
If sdk is using pulling model, `grpc` or `http`
1. Set fallbackToStatsigAPI=true
2. Set configSyncSources to have multiple sources,for example initializeSources=\[DataSource.Network, DataSource.StatsigNetwork] will fetch from 3 sources sequentially until it successfully find one
(Note if you are using streaming, config sync sources does not matter here)
If sdk is using `grpc_websocket` protocol, meaning sdk is in a listening mode for any config changes, by default it will
1. Retry connecting to forward proxy, with exponential backoff, 10s, 50s, 250s, 1250s ... until it reconnects, limit for retry is 10 times.
2. If 4th retry still fails, sdk will start polling from Statsig endpoint. Use StatsigOptions.pollingInterval to control how often it
3. While sdk polling from Statsig endpoint, sdk will keep retrying until it connected,
Everything mentioned above is configurable with StatsigOptions
#### Streaming failover in depth
Within SDK, when exceptions being thrown, for example, connection is dropped or forward proxy server is down, grpc will return error to SDK and we start falling back behavior.
Python will check if the channel is idle every 2 hours to ensure channel is not idle, this is to prevent some unknown corner case behavior within python grpc library.
#### TLS -- Advanced network authentication
Forward proxy support TLS and mTLS when use GRPC server, so all grpc network (streaming and unary call) are encrypted
To enable it:
1. [Setup forward proxy server with valid certifications](https://github.com/statsig-io/statsig-forward-proxy?tab=readme-ov-file#deploying)
2. [Setup SDK with valid certifications (python example)](/server/pythonSDK).
If certifications are misconfigured, SDK will treat as exception and started failing over behavior that you configured.
For example: fallback to Statsig API, retry connection, and start fall back behavior.
#### Coordinate SDK DataAdapter / DataStore with Forward Proxy Cache service
In order to increase reliability of SDK during initialization, setup DataStore will help in case Forward Proxy is not available when initialized. If DataStore is set, the SDK will try to initialize with values from dataStore, and sync (listen or polling depends on setup) from forward proxy in background after initialization. It's recommended for SDK and Forward Proxy to share the same cache service for consistency and reduce cache I/O.
Example on DataStore setup in python:
```py theme={null}
class DataAdapter(IDataStore):
def __init__(self):
self.redis_cache = ExampleCache()
def get(self, key: str):
# IDlist isn't currently supported by proxy, so do normal lookup
if "statsig.id_lists" in key:
return self.cache.get(key)
# This logic must stay in sync with statsig-forward-proxy
else:
hashed_key = "statsig::" + hashlib.sha256(key.encode()).hexdigest()
return self.cache.hget(hashed_key, 'config')
def set(self, key: str):
# Don't implement set method if you are share the same cache between forward proxy and sdk, forward proxy will write to cache
pass
def shutdown(self):
self.cache.shutdown()
```
#### Deployment Notes
Given that every use case for the proxy is different, we don't have strict recommendations. However, we do have general recommendations:
1. Understand what your general QPS to Statsig is. If you need help understanding this, feel free to reach out.
2. If possibly using your payload, get a sense of what throughput can be supported by a single pod and then calculate how much you need to scale out by to support your traffic.
3. Pre-scale the proxy for your max QPS and then begin to gradually rollout the proxy to services.
4. Configure your auto-scaling, for most folks, scaling up at 70% utilization for CPU and memory is typically sufficient, but depending on your usage this might need to be tweaked.
If you are seeing scaling issues that can't be resolved by scaling out horizontally, we recommend fronting it with nginx to help with flow control.
If you need any help, we are happy to collaborate and work closely, just send a message to our [slack channel](https://statsig.com/slack) to get further assistance.
# Ingesting Open Telemetry Data
Source: https://docs.statsig.com/server/concepts/open_telemetry
Instrument Statsig server SDKs with OpenTelemetry to capture spans, metrics, and logs for SDK initialization, evaluation, and event logging.
Setting up OTEL can be tricky, if you have any questions, feel free to reach out to us on slack!
## Overview
This guide walks you through setting up the OpenTelemetry Collector in your Kubernetes environment and configuring it to send telemetry data to Statsig using the official `otlphttp` exporter
***
## ✅ Prerequisites
* A running Kubernetes cluster (e.g., GKE, EKS, Minikube, etc.)
* Helm installed, or another mechanism to apply helm charts to your cluster, like ArgoCD
* API Access to a Statsig project with a Server SDK Secret Key
* Optional: `kubectl` configured and connected to the cluster, for validating and debugging setup
***
## 1. Setup OpenTelemetry Collector on Kubernetes
Our recommend setup follows the official OpenTelemetry Kubernetes guide to install the OpenTelemetry Collector in both **DaemonSet** and **Deployment** modes, using the official Helm Chart. **Note:** You'll find well-tested and ready-to-use `values.yaml` files for both deployments modes in Step 3!
**📘 Official Guide:**
[OpenTelemetry Collector for Kubernetes – Getting Started](https://opentelemetry.io/docs/platforms/kubernetes/getting-started/)
### Why both?
* **DaemonSet Collector**: Runs one instance per node to collect host-level telemetry (e.g., logs, pod and node metrics).
* **Deployment Collector**: Runs one instance per cluster to gather telemetry related to the cluster as a whole.
We recommend configuring these receivers at the minimum, for a useful observability platform for your kubernetes workloads powered by Statsig. We make use of the powerful [Presets](https://opentelemetry.io/docs/platforms/kubernetes/helm/collector/#presets) provided by the official chart, but also customize some components as can be seen in the sample values files in Step 3.
* Minimum for scraping logs:
* [Filelog Receiver](https://opentelemetry.io/docs/platforms/kubernetes/getting-started/#filelog-receiver)
* [Kubernetes Attributes Processor](https://opentelemetry.io/docs/platforms/kubernetes/getting-started/#kubernetes-attributes-processor)
* Minimum for scraping kubernetes metrics
* [KubeletStats Receiver](https://opentelemetry.io/docs/platforms/kubernetes/getting-started/#kubeletstats-receiver)
* [Kubernetes Cluster Receiver](https://opentelemetry.io/docs/platforms/kubernetes/getting-started/#kubernetes-cluster-receiver)
* Minimum for metrics about Otel Collector itself
* [OTLP Receiver](https://opentelemetry.io/docs/platforms/kubernetes/getting-started/#otlp-receiver) for [scraping internal metrics](https://opentelemetry.io/docs/collector/internal-telemetry/#configure-internal-metrics) (alternatively scraped through prometheus receiver)
***
## 2. Configure exporting telemetry to Statsig with OTLP HTTP Exporter
Statsig supports receiving OTLP formatted, JSON encoded telemetry at the endpoint `https://api.statsig.com/otlp`. The OpenTelemetry Collector supports sending the scraped telemetry to the Statsig endpoint via the official `otlphttp` exporter.
### Authentication
Requests are authenticated using request header `statsig-api-key` and a valid SDK Server Secret key generated from [console.statsig.com](http://console.statsig.com) (under Settings > Keys & Environments). It is recommended to keep your secret key secure with a Kubernetes Secret management provider and make it available to access securely from the open telemetry collector pod’s environment.
### Example Exporter Config
```yaml theme={null}
exporters:
otlphttp:
endpoint: https://api.statsig.com/otlp
encoding: json
headers:
statsig-api-key: ${env:STATSIG_SERVER_SDK_SECRET}
```
## 3. Example Helm Chart Values for a quick and correct setup
We provide two complete and tested `values.yaml` configurations for use with the OpenTelemetry Helm charts:
### 🔗 Deployment Collector
👉 [values-gateway.yaml](https://gist.github.com/karan-statsig/d5c70b7fd100ab445985b620dcb7e8c6)
### 🔗 DaemonSet Collector
👉 [values-agent.yaml](https://gist.github.com/karan-statsig/f02ee95fef00aecde402829b5a4c60e8)
Use them with the Helm chart version `0.75.1` like this:
```yaml theme={null}
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
# Install Deployment Collector
helm install otel-deployment open-telemetry/opentelemetry-collector \
--version 0.75.1 \
-f values-gateway.yaml -n otel --create-namespace
# Install DaemonSet Collector
helm install otel-daemonset open-telemetry/opentelemetry-collector \
--version 0.75.1 \
-f values-agent.yaml -n otel
```
## 4. Verify the Setup
Check that all pods are running:
```bash theme={null}
kubectl get pods -n otel
```
Check logs for a specific collector pod and confirm there are errors reported:
```bash theme={null}
kubectl logs -n otel $pod_name
```
## 5. Explore
Explore your Logs and Metrics at [console.statsig.com](http://console.statsig.com) with the Logs Explorer and Metrics Explorer products under Analytics on the sidebar menu 🙂
***
## 🔗 Resources
* [OpenTelemetry Collector Documentation](https://opentelemetry.io/docs/collector/)
* [Important Concepts for Kubernetes](https://opentelemetry.io/docs/platforms/kubernetes/collector/components/)
* [Helm Chart Reference](https://github.com/open-telemetry/opentelemetry-helm-charts)
* [Collector Configuration Reference](https://opentelemetry.io/docs/collector/configuration)
* [OTLP Protocol Specification](https://opentelemetry.io/docs/specs/otlp/)
# Server Persistent Assignment
Source: https://docs.statsig.com/server/concepts/persistent_assignment
Configure persistent assignment in Statsig server SDKs so users stay in the same experiment group across requests, sessions, and devices over time.
Persistent assignment allows you to ensure that a user's variant stays consistent while an experiment is running, regardless of changes to allocation or targeting.
## Persistent Storage Adapter
The persistent storage adapter allows you to plug in your own storage solution that Statsig SDK uses to persist user assignments.
The storage interface consists of just a `load` and `save` API for read/write operations.
Currently only supported in `Go`, `Ruby`, `Legacy Node`, `Node Core`, `Java Core`, `Kotlin`, `.Net`, `Python Core`, `PHP Core`, `Rust Core`
### Persistent Storage Logic
* Providing a storage adapter on Statsig initialization will give the SDK access to read & write on your custom storage
* Providing user persisted values to `get_experiment` will inform the SDK to
* **save** the evaluation of the current user **on first evaluation**
* Will only save when experiment / layer **is active**
* **load** the previously saved evaluation of a persisted user **on subsequent evaluations**
* **CAVEAT** Persisted Value will be deleted when:
* When you provided call `getExperiment` with `user_persisted_values=None`
* or When experiment is not active
### Persistent Assignment Options (Limited SDK Support)
* **Enforce Targeting**: `boolean`, default: `false`
* Whether or not to enforce targeting rules before assigning persisted values
```kotlin theme={null}
val options = GetExperimentOptions(
...
persistentAssignmentOptions = PersistentAssignmentOptions(
enforceTargeting = true,
)
)
```
```ts theme={null}
const options: GetExperimentOptions = {
...
persistentAssignmentOptions: {
enforceTargeting: true,
}
}
```
### Example usage
```ruby theme={null}
Statsig.initialize(
'secret-key',
StatsigOptions.new(
user_persistent_storage: DummyPersistentStorageAdapter.new
)
)
persisted_user = StatsigUser.new({ 'userID' => 'test-123' })
exp = Statsig.get_experiment( # User gets saved to persisted storage
persisted_user,
'active_experiment',
Statsig::GetExperimentOptions.new(
user_persisted_values: Statsig.get_user_persisted_values(persisted_user, 'userID')
)
)
puts exp.group_name # 'Control'
exp = Statsig.get_experiment( # User evaluates using values from persisted storage
StatsigUser.new({'userID' => 'unknown'}),
'active_experiment',
Statsig::GetExperimentOptions.new(
user_persisted_values: Statsig.get_user_persisted_values(persisted_user, 'userID')
)
)
puts exp.group_name # 'Control'
```
```python theme={null}
from statsig_python_core import Statsig, StatsigUser, StatsigOptions, ExperimentEvaluationOptions, PersistentStorage
options = StatsigOptions(persistent_storage = MyPersistentStorage())
statsig = Statsig.initialize(options).wait
user = StatsigUser("a-user")
exp = statsig.get_experiment(StatsigUser("a-user"), ExperimentEvaluationOptions(user_persisted_values= PersistentStorage.get_user_persisted_value(user, "user_id")))
print(f"{exp.group_name}") # control
```
```java theme={null}
PersistentStorage persistentStorage = new MyPersistentStorage(); // See https://docs.statsig.com/server-core/java-core/#persistent-storage on how to implement it
StatsigOptions options = new StatsigOptions.Builder()
.setPersistentStorage(persistentStorage)
.build();
Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();
StatsigUser persistedUser = new StatsigUser.Builder().setUserID("test-123").build();
Map persistedValues = persistentStorage.getValuesForUser(persistedUser, "userID");
if (persistedValues == null) {
persistedValues = new HashMap<>();
}
Experiment exp = statsig.getExperiment(
persistedUser,
"active_experiment",
new GetExperimentOptions(persistedValues)
);
System.out.println(exp.getGroupName()); // "Control"
StatsigUser unknownUser = new StatsigUser.Builder().setUserID("unknown").build();
Map valuesForPersistedUser = persistentStorage.getValuesForUser(persistedUser, "userID");
Experiment persistedExp = statsig.getExperiment(
unknownUser,
"active_experiment",
new GetExperimentOptions(valuesForPersistedUser)
);
System.out.println(persistedExp.getGroupName()); // "Control"
```
```typescript theme={null}
let persistedStorage = new MyPersistentStorage() // See https://docs.statsig.com/server-core/node-core/#persistent-storage on how to implement it
let options = new StatsigOptions(persistentStorage = persistedStorage)
let statsig = new Statsig(secretKye, options)
let user = new StatsigUser("a-user")
let exp = statsig.getExperiment(user, ExperimentEvaluationOptions(userPersistentValues= persistedStorage.getUserPersistedValues(user, "user_id")))
```
```php theme={null}
$persistent_storage = new MyPersistentStorage(); // See https://docs.statsig.com/server-core/php-core/#persistent-storage on how to implement it
$options = new StatsigOptions(persistent_storage: $persistent_storage);
$statsig = new Statsig("secret-key", $options);
$statsig->initialize();
$persisted_user = new StatsigUser("test-123");
$persisted_values = $persistent_storage->getValuesForUser($persisted_user, "userID") ?? [];
$exp = $statsig->getExperiment(
$persisted_user,
"active_experiment",
["user_persisted_values" => $persisted_values],
);
echo $exp->groupName; // "Control"
$unknown_user = new StatsigUser("unknown");
$values_for_persisted_user = $persistent_storage->getValuesForUser($persisted_user, "userID");
$persisted_exp = $statsig->getExperiment(
$unknown_user,
"active_experiment",
["user_persisted_values" => $values_for_persisted_user],
);
echo $persisted_exp->groupName; // "Control"
```
```rust theme={null}
let persistent_storage = Arc::new(MyPersistentStorage::new()); // See https://docs.statsig.com/server-core/rust-core/#persistent-storage on how to implement it
let options = StatsigOptions::builder()
.persistent_storage(Some(persistent_storage.clone()))
.build();
let statsig = Statsig::new("secret-key", Some(Arc::new(options)));
statsig.initialize().await;
let persisted_user = StatsigUser::with_user_id("test-123");
let persisted_values = persistent_storage
.get_values_for_user(&persisted_user, "userID")
.unwrap_or_default();
let exp = statsig.get_experiment_with_options(
&persisted_user,
"active_experiment",
ExperimentEvaluationOptions {
user_persisted_values: Some(persisted_values),
..Default::default()
},
);
println!("{}", exp.group_name.as_deref().unwrap_or("")); // "Control"
let unknown_user = StatsigUser::with_user_id("unknown");
let values_for_persisted_user = persistent_storage.get_values_for_user(&persisted_user, "userID");
let persisted_exp = statsig.get_experiment_with_options(
&unknown_user,
"active_experiment",
ExperimentEvaluationOptions {
user_persisted_values: values_for_persisted_user,
..Default::default()
},
);
println!("{}", persisted_exp.group_name.as_deref().unwrap_or("")); // "Control"
```
```kotlin theme={null}
runBlocking {
Statsig.initialize(
"secret-key",
StatsigOptions(userPersistentStorage = MyPersistentStorageAdapter())
)
}
val persistedUser = StatsigUser("test-123")
var exp = Statsig.getExperimentSync(
persistedUser,
"active_experiment",
GetExperimentOptions(
userPersistedValues = Statsig.getUserPersistedValues(persistedUser, "userID"),
),
)
println(exp.groupName) // "Control"
exp = Statsig.getExperimentSync(
StatsigUser("unknown"),
"active_experiment",
GetExperimentOptions(
userPersistedValues = Statsig.getUserPersistedValues(persistedUser, "userID"),
),
)
println(exp.groupName) // "Control"
```
```ts theme={null}
await Statsig.initialize(
"secret-key",
{
userPersistentStorage: new MyPersistentStorageAdapter()
}
)
const persistedUser: StatsigUser = { userID: "123" }
let exp = Statsig.getExperimentSync(
persistedUser,
"active_experiment",
{
userPersistedValues: Statsig.getUserPersistedValues(user, "userID")
},
)
console.log(exp.getGroupName()) // "Control"
exp = Statsig.getExperimentSync(
{ userID: "unknown" },
"active_experiment",
{
userPersistedValues: Statsig.getUserPersistedValues(user, "userID")
},
)
console.log(exp.getGroupName()) // "Control"
```
```go theme={null}
InitializeWithOptions(
"secret-key",
&Options{
UserPersistentStorage: persistentStorage,
}
)
persistedUser := User{UserID: "123"}
exp := GetExperimentWithOptions(
persistedUser,
"active_experiment",
&GetExperimentOptions{
PersistedValues: GetUserPersistedValues(persistedUser, "userID")
}
)
fmt.Println(exp.GroupName) // "Control"
exp = GetExperimentWithOptions(
User{UserID: "unknown"},
"active_experiment",
&GetExperimentOptions{
PersistedValues: GetUserPersistedValues(persistedUser, "userID")
}
)
fmt.Println(exp.GroupName) // "Control"
```
```csharp theme={null}
var options = new StatsigServerOptions();
options.UserPersistentStorage = new MyPersistentStorageAdapter()
await StatsigServer.Initialize("server-secret-key", options);
var persistedUser = new StatsigUser { UserID = "123" };
var values = await StatsigServer.GetUserPersistedValues(persistedUser, "userID");
var getExpOptions = new StatsigGetExperimentOptions(values);
var exp = StatsigServer.GetExperimentSync(persistedUser, "active_experiment", getExpOptions);
Console.WriteLine(exp.GroupName); // "Control"
var newValues = await StatsigServer.GetUserPersistedValues(persistedUser, "userID");
var newGetExpOptions = StatsigGetExperimentOptions(newValues);
var newExp = StatsigServer.GetExperimentSync(new StatsigUser {UserID = "unknown"}, "active_experiment", newGetExpOptions);
Console.WriteLine(newExp.GroupName); // "Control"
```
# C++ Server SDK
Source: https://docs.statsig.com/server/cpp
Use the Statsig C++ Server SDK to evaluate feature gates, run experiments, and log events from native C++ backend services with low-latency evaluation.
View the C++ SDK source code and releases
## Setup the SDK
If you are using CMake, add the following to a `.cmake` file
```cmake theme={null}
FetchContent_Declare(statsig
GIT_REPOSITORY https://github.com/statsig-io/cpp-server-sdk.git
GIT_TAG v0.1.0
)
FetchContent_MakeAvailable(statsig)
```
And include the following in your `CMakeLists.txt` file
```cmake theme={null}
cmake_minimum_required(VERSION 3.11)
include(FetchContent)
include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/statsig.cmake)
```
Check out the latest versions on [https://github.com/statsig-io/cpp-server-sdk/releases/latest](https://github.com/statsig-io/cpp-server-sdk/releases/latest)
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
```cpp theme={null}
#include
statsig::initialize('server-secret-key');
// Or, if you want to initialize with certain options
statsig::Options options;
options.localMode = true
statsig::initialize('server-secret-key', options)
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```cpp theme={null}
statsig::User user;
user.userID = "some_user_id"
if (statsig::checkGate(user, 'use_new_feature'))
{
// Gate is on, enable new feature
}
else {
// Gate is off
}
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```cpp theme={null}
statsig::DynamicConfig config = statsig::get_config(user, 'awesome_product_details')
auto item_name = config.value['product_name'];
auto price = config.value['price'];
auto shouldDiscount = config.value['discount'];
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```cpp theme={null}
// Values via getLayer
statsig::Layer layer = statsig::getLayer(user, "user_promo_experiments")
auto title = layer.get("title", "Welcome to Statsig!")
auto discount = layer.get("discount")
// or, via getExperiment
statsig::DynamicConfig title_exp = statsig::getExperiment(user, "new_user_promo_title")
statsig::DynamicConfig price_exp = statsig::getExperiment(user, "new_user_promo_price")
title = title_exp.value["title"]
discount = price_exp.value["discount"]
...
price = msrp * (1 - discount)
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```cpp theme={null}
statsig::logEvent(user, 'add_to_cart')
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Statsig Options
`initialize()` takes an optional parameter `options` in addition to the secret key that you can provide to customize the Statsig client. Here are the current options and we are always adding more to the list:
You can specify optional parameters with `options` when initializing.
* **api** string, default `"https://statsigapi.net/v1"`
* The base url to use for network requests from the SDK
* **rulesetsSyncIntervalMs**: int, default `10000`
* The interval to poll for changes to your gate and config definition changes
* **loggingIntervalMs**: int, default `60000`
* The default interval to flush logs to Statsig servers
* **loggingMaxBufferSize**: int, default `1000`, can be set lower but anything over 1000 will be dropped on the server
* The maximum number of events to batch before flushing logs to the server
* **localMode**: bool, default `false`
* Restricts the SDK to not issue any network requests and only respond with default values (or local overrides)
ID Lists are currently not supported in the C++ server SDK
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```cpp theme={null}
statsig::shutdown()
```
## Local Overrides
You can override the values returned by the SDK for testing purposes. This can be useful for local development when you want to test specific scenarios.
```cpp theme={null}
// Adding gate overrides
statsig::overrideGate("a_gate_name", true)
// Adding config overrides
std::unordered_map overrideValue = {
{"overridden key", "overridden field"},
};
statsig::overrideConfig("a_config_name", overrideValue)
```
## FAQ
#### How do I run experiments for logged out users?
See the guide on [device level experiments](/guides/first-device-level-experiment)
## Reference
### User
```cpp theme={null}
struct User
{
std::string userID;
std::string email;
std::string ipAddress;
std::string userAgent;
std::string country;
std::string locale;
std::string appVersion;
std::unordered_map custom;
std::unordered_map privateAttribute;
std::unordered_map statsigEnvironment;
std::unordered_map customIDs;
};
inline bool operator==(User const &a, User const &b)
{
return a.userID == b.userID &&
a.email == b.email &&
a.ipAddress == b.ipAddress &&
a.userAgent == b.userAgent &&
a.country == b.country &&
a.locale == b.locale &&
a.appVersion == b.appVersion &&
a.custom == b.custom &&
a.privateAttribute == b.privateAttribute &&
a.statsigEnvironment == b.statsigEnvironment &&
a.customIDs == b.customIDs;
};
```
### Options
```cpp theme={null}
struct Options
{
std::string api;
bool localMode;
int rulesetsSyncIntervalMs;
int loggingIntervalMs;
int loggingMaxBufferSize;
Options() : api("https://statsigapi.net"),
localMode(false),
rulesetsSyncIntervalMs(10 * 1000),
loggingIntervalMs(60 * 1000),
loggingMaxBufferSize(1000){};
};
```
# Deprecation Notices
Source: https://docs.statsig.com/server/deprecation-notices
Deprecation notices for Statsig server SDKs, including end-of-life versions, breaking changes, and recommended upgrade paths to Server Core SDKs.
## Direct Initialization API Access for Server SDKs, October 31, 2025
#### What's changing?
Until mid-2024, Statsig's Server SDKs downloaded configuration values directly from Statsig servers upon startup. Since then, we've transitioned to hosting these configuration files on a secure CDN, which greatly reduces initialization time and increases reliability (we use Cloudflare, which has near-zero downtime.)
As we've transitioned to this approach, we've made the decision to deprecate direct API access, which is only available in long outdated SDK versions. We're asking all customers to discontinue using these SDK versions, and upgrade to a newer version.
#### Change required
The only change required is a minor SDK version bump, no code changes are needed. You'll need to bump your SDK version to at least:
* **go-sdk** 1.30.3
* **java-server** 1.9.0
* **py-server** 0.28.0
* **ruby-server** 1.29.0
* **statsig-node** 5.25.0
* **.NET** 2.4.1
* **Node-lite** 0.5.0
* **PHP** 3.7.2
We're asking all customers to make this change by October 31st, 2025.
CDN access is only available in a more recent version of the PHP and .NET SDKs, so we won't strictly enforce an upgrade for those 2 SDKs. But we still recommend you upgrade as soon as possible.
## New Method for Country Resolution
Starting December 9th, 2024, Statsig will **switch to a method of resolving IP Addresses to country codes in our client SDKs with greatly improved accuracy**, which may result in different gate behavior for some users. Statsig currently depends on a [homegrown package](https://github.com/statsig-io/ip3country) for country resolution on both Client and Server SDKs, which lacks IPV6 support. To resolve countries without bloating our SDK sizes, we'll begin to rely on our cloud provider's country resolution when serving requests to the /initialize endpoint.
### Potential Changes in Client Evaluations
This may result in different evaluations for some client-side checks, which will be significantly more accurate and complete than the previous method. You may see a greater number of users passing country rules, as this new method will begin to resolve countries for IPV6 users, which now represent a large share of many customers' user base.
### Conflicts with Server-Side Checks
If you check some configs on both the Client and Server side, it is possible that a small number of users may pass targeting on the client side and fail on the server, or vice versa, as we'll continue to rely on [IP3Country](https://github.com/statsig-io/ip3country) for server-side country resolution when a country is not explicitly provided on the `StatsigUser` object. We recommend using your cloud provider's country resolution (often available in a load balancer) and setting that as the "country" field on the `StatsigUser` object. This applies to any evaluations for gates/configs/experiments/layers, and also for `getClientInitializeResponse` if you are generating the payload for your client sdk.
## Async Evaluation Functions
#### Reason
Server SDKs were originally designed for maximum backwards compatibility.
This meant that if a Server SDK did not contain support for an operator or configuration,
it would fallback to hitting Statsig's servers, ensuring a valid result would be returned.
This is why all top level evaluation related functions were asynchronous.
In practice however, this is seldom required, so we no longer feel the trade off
for sync vs async functions is worth it and will be removing the asynchronous functions in newer releases.
#### Example
```java theme={null}
var result = await Statsig.checkGate("my_gate"); // Bad
// For node v6.0.0
var result = Statsig.checkGate("my_gate") // Good
// For .Net and Java
var result = Statsig.checkGateSync("my_gate"); // Good
```
#### SDKs
.NET Server - [v1.20.0](https://github.com/statsig-io/dotnet-sdk/releases/tag/v1.20.0)
NodeJS Server - [v5.10.0](https://github.com/statsig-io/node-js-server-sdk/releases/tag/v5.10.0)
Java/Kotlin Server - [v1.12.0](https://github.com/statsig-io/java-server-sdk/releases/tag/v1.12.0)
# Legacy .NET Server SDK
Source: https://docs.statsig.com/server/dotnet
Statsig's legacy .NET Server SDK for evaluating feature gates, experiments, and dynamic configs in C# backend services. New projects should use .NET Core SDK.
[Github Repository](https://github.com/statsig-io/dotnet-sdk)
## Setup the SDK
The package is hosted on [Nuget](https://www.nuget.org/packages/Statsig/). You can either install it from your Visual Studio's Nuget package manager, or through the NuGet CLI:
```bash theme={null}
nuget install Statsig
```
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
```csharp theme={null}
using Statsig;
using Statsig.Server;
await StatsigServer.Initialize(
"server-secret-key",
// optionally customize the SDKs configuration via StatsigOptions
new StatsigOptions(
environment: new StatsigEnvironment(EnvironmentTier.Development)
)
);
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```csharp theme={null}
var user = new StatsigUser { UserID = "some_user_id", Email = "user@email.com" };
var useNewFeature = await StatsigServer.CheckGate(user, "use_new_feature");
if (useNewFeature)
{
// Gate is on, enable new feature
}
else
{
// Gate is off
}
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```csharp theme={null}
var config = await StatsigServer.GetConfig(user, "awesome_product_details");
var itemName = config.Get("product_name", "Awesome Product v1");
var price = config.Get("price", 10.0);
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```csharp theme={null}
// Values via GetLayer
var layer = await StatsigServer.GetLayer(user, "user_promo_experiments");
var title = layer.Get("title", "Welcome to Statsig!");
var discount = layer.Get("discount", 0.1);
// or, via GetExperiment
var experiment = await StatsigServer.GetExperiment(user, "new_user_promo");
var expTitle = experiment.Get("title", "Welcome to Statsig!");
var expDiscount = experiment.Get("discount", 0.1);
var price = msrp * (1 - discount);
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```csharp theme={null}
StatsigServer.LogEvent(user, "add_to_cart", "SKU_12345",
new Dictionary {
{ "price", "9.99" },
{ "item_name", "diet_coke_48_pack" }
});
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```csharp theme={null}
await StatsigServer.Shutdown();
```
# Legacy Erlang/Elixir Server SDK
Source: https://docs.statsig.com/server/erlang
Statsig's legacy Erlang and Elixir Server SDK for evaluating feature gates, experiments, and dynamic configs in BEAM-based backend services and apps.
Support for the Legacy Erlang SDK ends April 30, 2026. Migrate to the [new Elixir SDK](/server-core/elixir-core) soon.
The erlang SDK repository, and this docs site, are a work in progress. If you are trying to use Statsig in erlang or elixir, please reach out to our support team, your sales contact, or in our [Slack community](https://statsig.com/slack).
[Github Repository](https://github.com/statsig-io/erlang-sdk)
## Setup the SDK
Add a dependency on statsig to your:
**mix.exs**:
```elixir theme={null}
{:statsig, "~> 0.0.1"}
```
**rebar.config**:
```erlang theme={null}
{statsig, "0.0.1"}.
```
**erlang.mk**:
```makefile theme={null}
dep_statsig = hex 0.0.1
```
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
```erlang Erlang theme={null}
statsig:initialize(<<"secret-key">>).
% or with options
Options = #{environment => #{tier => <<"staging">>}},
statsig:initialize(<<"secret-key">>, Options).
```
```elixir Elixir theme={null}
Statsig.initialize("secret-key")
# or with options
options = %{environment: %{tier: "staging"}}
Statsig.initialize("secret-key", options)
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```erlang Erlang theme={null}
User = #{<<"userID">> => <<"user-id">>},
GateValue = statsig:check_gate(User, <<"gate_name">>).
```
```elixir Elixir theme={null}
user = %{"userID" => "user-id"}
gate_value = Statsig.check_gate(user, "gate_name")
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```erlang Erlang theme={null}
Config = statsig:get_config(User, <<"config_name">>),
Value = statsig_config:get(Config, <<"param">>, <<"default">>).
```
```elixir Elixir theme={null}
config = Statsig.get_config(user, "config_name")
value = StatsigConfig.get(config, "param", "default")
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```erlang Erlang theme={null}
Layer = statsig:get_layer(User, <<"layer_name">>),
ParamValue = statsig_layer:get(Layer, <<"param">>, <<"default">>).
```
```elixir Elixir theme={null}
layer = Statsig.get_layer(user, "layer_name")
param_value = StatsigLayer.get(layer, "param", "default")
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```erlang Erlang theme={null}
statsig:log_event(User, <<"event_name">>).
```
```elixir Elixir theme={null}
Statsig.log_event(user, "event_name")
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```erlang Erlang theme={null}
statsig:shutdown().
```
```elixir Elixir theme={null}
Statsig.shutdown()
```
# Legacy Go Server SDK
Source: https://docs.statsig.com/server/go
Statsig's legacy Go Server SDK for evaluating feature gates, experiments, and dynamic configs. New Go projects should use the Go Core SDK instead.
This page covers the legacy Go SDK. For new implementations, use the [Go Core SDK](/server-core/go-core) built on the Server Core framework.
View the Go SDK source code and releases
## Setup the SDK
via the `go get` CLI:
```bash theme={null}
go get github.com/statsig-io/go-sdk
```
Or, add a dependency on the most recent version of the SDK in go.mod:
```go theme={null}
require (
github.com/statsig-io/go-sdk v1.26.0
)
```
See the [Releases tab in GitHub](https://github.com/statsig-io/go-sdk/releases) for the latest versions.
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
```go theme={null}
import (
statsig "github.com/statsig-io/go-sdk"
)
statsig.Initialize("server-secret-key")
// Or, if you want to initialize with certain options
statsig.InitializeWithOptions("server-secret-key", &Options{Environment: Environment{Tier: "staging"}})
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```go theme={null}
user := statsig.User{UserID: "some_user_id"}
feature := statsig.CheckGate(user, "use_new_feature")
if feature {
// Gate is on, enable new feature
} else {
// Gate is off
}
```
## Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```go theme={null}
user := statsig.User{UserID: "some_user_id"}
feature := statsig.GetGate(user, "use_new_feature")
if feature.Value {
// Gate is on, enable new feature
fmt.Print(feature.EvaluationDetails.Reason)
}
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```go theme={null}
config := statsig.GetConfig(user, "awesome_product_details")
// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
itemName := config.GetString("product_name", "Awesome Product v1");
double price = config.GetNumber("price", 10.0);
bool shouldDiscount = config.GetBool("discount", false);
// Or just get the whole json object backing this config if you prefer
json := config.Value
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```go theme={null}
// Values via getLayer
layer := Statsig.GetLayer(user, "user_promo_experiments");
promoTitle := layer.GetString("title", "Welcome to Statsig!");
discount := layer.GetDouble("discount", 0.1);
// or, via getExperiment
titleExperiment := Statsig.GetExperiment(user, "new_user_promo_title");
priceExperiment := Statsig.GetExperiment(user, "new_user_promo_price");
promoTitle := titleExperiment.GetString("title", "Welcome to Statsig!");
discount := priceExperiment.GetNumber("discount", 0.1);
...
price := msrp * (1 - discount);
// getting the layer name that an experiment belongs to
userPromoLayer := Statsig.GetExperimentLayer("new_user_promo_title");
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```go theme={null}
statsig.LogEvent(Event{
User: user,
EventName: "add_to_cart",
Value: "SKU_12345",
Metadata: map[string]string{"price": "9.99","item_name": "diet_coke_48_pack"},
})
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Statsig Options
`initialize()` takes an optional parameter `options` in addition to the secret key that you can provide to customize the Statsig client. Here are the current options and we are always adding more to the list:
You can specify optional parameters with `options` when initializing using `InitializeWithOptions()`
```go theme={null}
type Options struct {
API string `json:"api"`
Environment Environment `json:"environment"`
LocalMode bool `json:"localMode"`
ConfigSyncInterval time.Duration
IDListSyncInterval time.Duration
BootstrapValues string
RulesUpdatedCallback func(rules string, time int64)
}
```
* **Environment**: default nil
* An object you can use to set environment variables that apply to all of your users in the same session and will be used for targeting purposes.
* The most common usage is to set the environment tier (string), and have feature gates pass/fail for specific environments. The accepted values are "production", "staging" and "development".
* **LocalMode**: default false
* Restricts the SDK to not issue any network requests and only respond with default values (or local overrides)
* **ConfigSyncInterval**: default 10 seconds
* The interval to poll for gate/experiment/config changes.
* **IDListSyncInterval**: default 1 minute
* The interval to poll for ID list changes.
* **BootstrapValues**: default nil
* A string that represents all rules for all feature gates, dynamic configs and experiments. It can be provided to bootstrap the Statsig server SDK at initialization in case your server runs into network issue or Statsig server is down temporarily.
* **RulesUpdatedCallback**: default nil
* The callback that gets invoked whenever the rulesets are updated. It's called with a JSON string that represents the rulesets, and a timestamp for when the rules were updated.
* **UserPersistentStorage**: IUserPersistentStorage default nil
* A persistent storage adapter for running sticky experiments.
* **DisableIdList**: default false
* A flag to disable fetching the id list during initialization and background polling for both network and data adapter.
### Client Initialize Response Options
When using `getClientInitializeResponse()`, you can specify additional options through the `GCIROptions` struct:
```go theme={null}
type GCIROptions struct {
IncludeLocalOverrides bool
ClientKey string
TargetAppID string
HashAlgorithm string
IncludeConfigType bool
ConfigTypesToInclude []ConfigType
}
```
* **IncludeLocalOverrides**: default false
* When set to true, local overrides will be included in the client initialize response.
* This allows you to test local changes to configurations without affecting other users.
* Useful for development and testing environments.
* **ClientKey**: default empty string
* The client SDK key to use for the initialize response.
* This key is used to identify the client application and determine which configurations it should receive.
* Required when generating a client initialize response for client SDKs.
* **TargetAppID**: default empty string
* Specifies a target application ID to filter configurations (feature gates, dynamic configs, experiments, and layers).
* When specified, the SDK will only return configurations that are targeted to this application ID.
* This is useful in multi-tenant or multi-application environments where you want to ensure that only configurations relevant to a specific application are evaluated and returned.
* If not specified, the SDK will attempt to determine the target app ID from the provided client key.
* **HashAlgorithm**: default empty string
* Specifies the hashing algorithm to use for generating stable IDs in the client.
* Common values include "djb2" (default if not specified) and "sha256".
* This should match the hashing algorithm used by the client SDK.
* **IncludeConfigType**: default false (deprecated)
* When set to true, the type of each configuration will be included in the response.
* This allows clients to differentiate between different types of configurations (e.g., feature gates, dynamic configs, experiments).
* Note: This option is deprecated and may be removed in future versions.
* **ConfigTypesToInclude**: default empty array
* An array of configuration types to include in the response.
* If specified, only configurations of the specified types will be included.
* Possible values include FeatureGateType, DynamicConfigType, ExperimentType, and LayerType.
* If empty, all configuration types will be included (subject to other filtering options).
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```go theme={null}
statsig.Shutdown()
```
## Local Overrides
You can override the values returned by the SDK for testing purposes. This can be useful for local development when you want to test specific scenarios.
```go theme={null}
func OverrideGate(gate string, val bool)
func OverrideConfig(config string, val map[string]interface{})
```
## Client SDK Bootstrapping
The Statsig server SDK can be used to generate the initialization values for a client SDK. This is useful for server-side rendering (SSR) or when you want to pre-fetch values for a client.
```go theme={null}
user := statsig.User{UserID: "some_user_id"}
options := statsig.GCIROptions{}
options.ClientKey = "client-YOUR_CLIENT_KEY"
result := statsig.GetClientInitializeResponseWithOptions(user, &options)
// You can then pass 'result' into a Statsig Client SDK
```
## Data Store
A data store can be used to synchronize the configuration/value downloads across multiple SDK instances, and to bootstrap the SDK in offline environments.
### Interface
```go theme={null}
type IDataAdapter interface {
/**
* Returns the data stored for a specific key
*/
Get(key string) string
/**
* Updates data stored for each key
*/
Set(key string, value string)
/**
* Startup tasks to run before any get/set calls can be made
*/
Initialize()
/**
* Cleanup tasks to run when statsig is shutdown
*/
Shutdown()
/**
* Determines whether the SDK should poll for updates from
* the data adapter (instead of Statsig network) for the given key
*/
ShouldBeUsedForQueryingUpdates(key string) bool
}
```
### Example Implementation
```go theme={null}
type dataAdapterExample struct {
store map[string]string
mu sync.RWMutex
}
func (d *dataAdapterExample) Get(key string) string {
d.mu.RLock()
defer d.mu.RUnlock()
return d.store[key]
}
func (d *dataAdapterExample) Set(key string, value string) {
d.mu.Lock()
defer d.mu.Unlock()
d.store[key] = value
}
func (d *dataAdapterExample) Initialize() {}
func (d *dataAdapterExample) Shutdown() {}
func (d *dataAdapterExample) ShouldBeUsedForQueryingUpdates(key string) bool {
return false
}
```
## User Persistent Storage
User Persistent Storage is a storage adapter for running sticky experiments. It allows you to persist user assignments across sessions.
### Interface
```go theme={null}
type IUserPersistentStorage interface {
/**
* Returns the data stored for a specific key
*/
Load(key string) (string, bool)
/**
* Updates data stored for a specific key
*/
Save(key string, data string)
}
```
### Example Implementation
```go theme={null}
type userPersistentStorageExample struct {
store map[string]string
loadCalled int
saveCalled int
}
func (d *userPersistentStorageExample) Load(key string) (string, bool) {
d.loadCalled++
val, ok := d.store[key]
return val, ok
}
func (d *userPersistentStorageExample) Save(key string, value string) {
d.saveCalled++
d.store[key] = value
}
```
## Multi-Instance Usage
If you need to create multiple independent instances of the Statsig SDK (for example, to use different API keys or configurations), you can use the instance-based approach:
```go theme={null}
sdkInstance := NewClientWithOptions(sdkKey, &Options{})
```
## FAQ
#### How do I run experiments for logged out users?
See the guide on [device level experiments](/guides/first-device-level-experiment)
#### How can I mock Statsig in tests
We recommend using the [Local Override](#local-overrides) APIs in v1.3.0+, in combination with the `LocalMode` option in `StatsigOptions` to force gate/config values in test environments and remove network access to statsig servers.
For example:
```go theme={null}
c := NewClientWithOptions(secret, &Options{LocalMode: true})
user := User{
UserID: "123",
}
gateDefault := c.CheckGate(user, "any_gate")
// "any_gate" is false by default
c.OverrideGate("any_gate", true)
// "any_gate" is now true
```
See also [https://github.com/statsig-io/go-sdk/blob/main/overrides\_test.go](https://github.com/statsig-io/go-sdk/blob/main/overrides_test.go)
## Reference
### StatsigUser
```go theme={null}
// User specific attributes for evaluating Feature Gates, Experiments, and DynamicConfigs
//
// Learn more why a UserID or a customID is required: https://docs.statsig.com/sdks/user#why-is-an-id-always-required-for-server-sdks
// PrivateAttributes are only used for user targeting/grouping in feature gates, dynamic configs,
// experiments and etc; they are omitted in logs.
type User struct {
UserID string `json:"userID"`
Email string `json:"email,omitempty"`
IpAddress string `json:"ip,omitempty"` // Many jurisdictions categorize this as PII; verify whether you should log this.
UserAgent string `json:"userAgent,omitempty"`
Country string `json:"country,omitempty"`
Locale string `json:"locale,omitempty"`
AppVersion string `json:"appVersion,omitempty"`
Custom map[string]interface{} `json:"custom,omitempty"`
PrivateAttributes map[string]interface{} `json:"privateAttributes,omitempty"`
StatsigEnvironment map[string]string `json:"statsigEnvironment,omitempty"`
CustomIDs map[string]string `json:"customIDs"`
}
```
### StatsigOptions
```go theme={null}
// Advanced options for configuring the Statsig SDK
type Options struct {
API string `json:"api"`
APIOverrides APIOverrides `json:"api_overrides"`
Environment Environment `json:"environment"`
LocalMode bool `json:"localMode"`
ConfigSyncInterval time.Duration
IDListSyncInterval time.Duration
LoggingInterval time.Duration
LoggingMaxBufferSize int
BootstrapValues string
RulesUpdatedCallback func(rules string, time int64)
InitTimeout time.Duration
DataAdapter IDataAdapter
OutputLoggerOptions OutputLoggerOptions
StatsigLoggerOptions StatsigLoggerOptions
EvaluationCallbacks EvaluationCallbacks
DisableCDN bool // Disables use of CDN for downloading config specs
UserPersistentStorage IUserPersistentStorage
IPCountryOptions IPCountryOptions
UAParserOptions UAParserOptions
}
type APIOverrides struct {
DownloadConfigSpecs string `json:"download_config_specs"`
GetIDLists string `json:"get_id_lists"`
LogEvent string `json:"log_event"`
}
type EvaluationCallbacks struct {
GateEvaluationCallback func(name string, result bool, exposure *ExposureEvent)
ConfigEvaluationCallback func(name string, result DynamicConfig, exposure *ExposureEvent)
ExperimentEvaluationCallback func(name string, result DynamicConfig, exposure *ExposureEvent)
LayerEvaluationCallback func(name string, param string, result DynamicConfig, exposure *ExposureEvent)
ExposureCallback func(name string, exposure *ExposureEvent)
IncludeDisabledExposures bool
}
type OutputLoggerOptions struct {
LogCallback func(message string, err error)
EnableDebug bool
DisableInitDiagnostics bool
DisableSyncDiagnostics bool
}
type StatsigLoggerOptions struct {
DisableInitDiagnostics bool
DisableSyncDiagnostics bool
DisableApiDiagnostics bool
DisableAllLogging bool
}
type IPCountryOptions struct {
Disabled bool // Fully disable IP to country lookup
LazyLoad bool // Load in background
EnsureLoaded bool // Wait until loaded when needed
}
type UAParserOptions struct {
Disabled bool // Fully disable UA parser
LazyLoad bool // Load in background
EnsureLoaded bool // Wait until loaded when needed
}
// See https://docs.statsig.com/guides/usingEnvironments
type Environment struct {
Tier string `json:"tier"`
Params map[string]string `json:"params"`
}
// options for getClientInitializeResponse
type GCIROptions struct {
IncludeLocalOverrides bool
ClientKey string
HashAlgorithm string //supports "sha256", "djb2", "none", default "sha256"
}
```
### Event
```go theme={null}
type Event struct {
EventName string `json:"eventName"`
User User `json:"user"`
Value string `json:"value"`
Metadata map[string]string `json:"metadata"`
Time int64 `json:"time"`
}
```
### FeatureGate
```go theme={null}
type FeatureGate struct {
Name string `json:"name"`
Value bool `json:"value"`
RuleID string `json:"rule_id"`
IDType string `json:"id_type"`
GroupName string `json:"group_name"`
EvaluationDetails *EvaluationDetails `json:"evaluation_details"`
}
```
### DynamicConfig
```go theme={null}
type DynamicConfig struct {
Name string `json:"name"`
Value map[string]interface{} `json:"value"`
RuleID string `json:"rule_id"`
IDType string `json:"id_type"`
GroupName string `json:"group_name"`
EvaluationDetails *EvaluationDetails `json:"evaluation_details"`
AllocatedExperimentName string `json:"allocated_experiment_name"`
GetString(key string, fallback string) string
GetNumber(key string, fallback float64) float64
GetBool(key string, fallback bool) bool
GetSlice(key string, fallback []interface{}) []interface{}
GetMap(key string, fallback map[string]interface{}) map[string]interface{}
}
```
# Legacy Java/Kotlin Server SDK
Source: https://docs.statsig.com/server/java
Statsig's legacy Java and Kotlin Server SDK for evaluating feature gates, experiments, and dynamic configs in JVM backend services. New projects use Java Core.
These docs are for using our Java/Kotlin SDK in a multi-user, server side context. For client side android applications, check out our [Android SDK](/client/Android) or one of the other client SDKs for your client side applications.
This SDK is written in Kotlin, but exposes methods and overrides to Java based applications.
[Github Repository](https://github.com/statsig-io/java-server-sdk)
## Setup the SDK
`v1.X.X+` of the SDK is now published only to Maven Central.
To install the SDK, set the Maven Central repository in your `build.gradle`. You probably already have this for other dependencies.
```groovy theme={null}
repositories {
mavenCentral()
}
```
Then add the dependency:
```groovy theme={null}
implementation 'com.statsig:serversdk:1.X.X' // replace with the most up to date version
// For >v1.24.0 If you are not using streaming and want to reduce the package size you can:
implementation 'com.statsig:serversdk:1.X.X' {
exclude(group = "io.grpc", module = "*")
}
```
You can find the versions in the github releases of the [open source sdk repository](https://github.com/statsig-io/java-server-sdk/releases), or from the [maven central repository](https://mvnrepository.com/artifact/com.statsig/serversdk).
### Jitpack Deprecation
`v0.X.X` versions of the SDK are available from jitpack, but newer versions will not be published to jitpack.
If you update Statsig to be pulled from Maven Central instead of jitpack, you can remove `maven { url 'https://jitpack.io' }` if Statsig was the only library you got from jitpack and you previously relied on v0.X.X of the SDK.
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
```java Java theme={null}
import com.statsig.sdk.Statsig;
StatsigOptions options = new StatsigOptions();
// Customize options as needed. For example:
// options.initTimeoutMs = 9999;
Future initFuture = Statsig.initializeAsync("server-secret-key", options);
initFuture.get();
```
```kotlin Kotlin theme={null}
import com.statsig.sdk.Statsig
val options = StatsigOptions().apply {
// Customize options as needed. For example:
initTimeoutMs = 9999
}
async { Statsig.initialize("server-secret-key", options) }.await()
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```java Java theme={null}
StatsigUser user = new StatsigUser("user_id");
Boolean isFeatureOn = Statsig.checkGateSync(user, "use_new_feature");
if (isFeatureOn) {
// Gate is on, use new feature
} else {
// Gate is off
}
```
```kotlin Kotlin theme={null}
val user = StatsigUser("user_id");
val featureOn = Statsig.checkGateSync(user, "use_new_feature")
if (featureOn) {
// Gate is on, use new feature
} else {
// Gate is off
}
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```java Java theme={null}
DynamicConfig config = Statsig.getConfigSync(user, "awesome_product_details");
String itemName = config.getString("product_name", "Awesome Product v1");
double price = config.getDouble("price", 10.0);
```
```kotlin Kotlin theme={null}
val config = Statsig.getConfigSync(user, "awesome_product_details")
val itemName = config.getString("product_name", "Awesome Product v1")
val price = config.getDouble("price", 10.0)
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```java Java theme={null}
// Values via getLayer
Layer layer = Statsig.getLayerSync(user, "user_promo_experiments");
String title = layer.getString("title", "Welcome to Statsig!");
double discount = layer.getDouble("discount", 0.1);
// or, via getExperiment
DynamicConfig experiment = Statsig.getExperimentSync(user, "new_user_promo");
String expTitle = experiment.getString("title", "Welcome to Statsig!");
double expDiscount = experiment.getDouble("discount", 0.1);
```
```kotlin Kotlin theme={null}
// Values via getLayer
val layer = Statsig.getLayerSync(user, "user_promo_experiments")
val title = layer.getString("title", "Welcome to Statsig!")
val discount = layer.getDouble("discount", 0.1)
// or, via getExperiment
val experiment = Statsig.getExperimentSync(user, "new_user_promo")
val expTitle = experiment.getString("title", "Welcome to Statsig!")
val expDiscount = experiment.getDouble("discount", 0.1)
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```java Java theme={null}
Statsig.logEvent(user, "add_to_cart", "SKU_12345",
Map.of("price", "9.99", "item_name", "diet_coke_48_pack"));
```
```kotlin Kotlin theme={null}
Statsig.logEvent(user, "add_to_cart", "SKU_12345",
mapOf("price" to "9.99", "item_name" to "diet_coke_48_pack"))
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```java Java theme={null}
FeatureGate gate = Statsig.getFeatureGateSync(user, "use_new_feature");
boolean value = gate.getValue();
String ruleId = gate.getRuleID();
EvaluationDetails details = gate.getEvaluationDetails();
```
```kotlin Kotlin theme={null}
val gate = Statsig.getFeatureGateSync(user, "use_new_feature")
val value = gate.getValue()
val ruleId = gate.getRuleID()
val details = gate.getEvaluationDetails()
```
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```java Java theme={null}
Statsig.shutdown();
```
```kotlin Kotlin theme={null}
Statsig.shutdown()
```
# Legacy Node.js Server SDK
Source: https://docs.statsig.com/server/nodejsServerSDK
Statsig's legacy Node.js Server SDK for evaluating feature gates, experiments, and dynamic configs in Node backend services. New projects use Node Core.
[Github Repository](https://github.com/statsig-io/node-js-server-sdk)
## Setup the SDK
The Node.js SDK is hosted [here](https://www.npmjs.com/package/statsig-node). You can install the SDK using NPM or Yarn:
```bash npm theme={null}
npm install statsig-node
```
```bash yarn theme={null}
yarn add statsig-node
```
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
```javascript theme={null}
const Statsig = require("statsig-node");
await Statsig.initialize(
"server-secret-key",
{ environment: { tier: "staging" } } // optional, if not set, for >v6.0.0, sdk will default to be production
);
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```javascript theme={null}
const user = {
userID: '12345',
email: '12345@gmail.com',
...
};
const showNewDesign = Statsig.checkGate(user, 'new_homepage_design');
if (showNewDesign) {
// show new design here
} else {
// show old design here
}
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```javascript theme={null}
const config = Statsig.getConfig(user, "awesome_product_details");
// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
const itemName = config.get("product_name", "Awesome Product v1");
const price = config.get("price", 10.0);
const shouldDiscount = config.get("discount", false);
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```javascript theme={null}
// Values via getLayer
const layer = Statsig.getLayer(user, "user_promo_experiments");
const promoTitle = layer.get("title", "Welcome to Statsig!");
const discount = layer.get("discount", 0.1);
// or, via getExperiment
const promoExperiment = Statsig.getExperiment(user, "new_user_promo");
const promoTitle = promoExperiment.get("title", "Welcome to Statsig!");
const discount = promoExperiment.get("discount", 0.1);
...
const price = msrp * (1 - discount);
```
## Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```javascript theme={null}
const gate = Statsig.getFeatureGate(user, 'new_homepage_design');
console.log(gate.name); // 'new_homepage_design'
console.log(gate.value); // true or false
console.log(gate.ruleID); // rule ID that was evaluated
console.log(gate.evaluationDetails); // evaluation metadata
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```javascript theme={null}
Statsig.logEvent(user, "add_to_cart", "SKU_12345", {
price: "9.99",
item_name: "diet_coke_48_pack",
});
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Statsig Options
`initialize()` takes an optional parameter `options` in addition to the secret key that you can provide to customize the Statsig client. Here are the current options and we are always adding more to the list:
`initialize()` takes an optional parameter `options` in addition to the secret key that you can provide to customize the Statsig client. Here are the current options and we are always adding more to the list:
The base url to use for all network requests. Defaults to the statsig API.
An object you can use to set environment variables that apply to all of your users in the same session and will be used for targeting purposes.
The most common usage is to set the environment tier ('production', 'staging' or 'development'), e.g. `{ tier: 'staging' }`, and have feature gates pass/fail for specific environments. Since v6.0.0 default environment tier is production
A string that represents all rules for all feature gates, dynamic configs and experiments. It can be provided to bootstrap the Statsig server SDK at initialization in case your server runs into network issue or Statsig server is down temporarily.
A callback function that's called whenever we have an update for the rules; it's called with a JSON string (used as is for `bootstrapValues` mentioned above) and a timestamp, like below:
```
options.rulesUpdatedCallback(specsString, timeStamp)
```
The logger interface to use for printing to stdout/stderr
Disables all network access, so the SDK will only return default (or overridden) values. Useful in testing.
Sets a maximum time to wait for the config download network request to resolve before considering the SDK initialized and resolving the call to `initialize()`
An adapter with custom storage behavior for config specs. Can be used to bootstrap Statsig server (takes priority over `bootstrapValues`). Can also be used to continuously fetch updates in place of the Statsig network. See [Data Stores](/server/concepts/data_store).
For example, see our 1P implementation via Redis [statsig-node-redis](https://github.com/statsig-io/node-js-server-sdk-redis).
A persistent storage adapter for running sticky experiments. See [examples](/server/nodejsServerSDK#user-persistent-storage).
Sets the polling interval for the SDK to ask Statsig backend for changes on the rulesets.
Sets the polling interval for the SDK to ask Statsig backend for changes on the ID Lists.
Sets the interval for the SDK to periodically flush all logging events to Statsig backend.
Sets the maximum number of events the SDK's logger will batch before flushing them all to Statsig backend.
Disables diagnostics events from being logged and sent to Statsig
Method of initializing IP to country lookup on `statsig.initialize()`.
Method of initializing ID lists on `statsig.initialize()`.
The maximum number of retry attempts when sending `/log_event` requests to Statsig server
A fixed number or callback on the retry attempt number to configure the time in ms to wait between each `/log_event` retry.
If using a fixed number, a 10x multiplier will be applied on each subsequent retry
Provides callback functions for handling custom logic during evaluations of gates, dynamic configs, experiments, or layers. You can provide specific callbacks for each evaluation type to perform tasks such as custom logging (if you prefer not to use Statsig's default logging), or side effects.
**Note:** if you'd like to turn off Statsig's default logging, set `disableExposureLogging: true` when making checks.
Available callbacks:
```
gateCallback?: (gate: FeatureGate, user: StatsigUser, event: LogEvent) => void;
dynamicConfigCallback?: (config: DynamicConfig, user: StatsigUser, event: LogEvent) => void;
experimentCallback?: (config: DynamicConfig, user: StatsigUser, event: LogEvent) => void;
layerCallback?: (layer: Layer, user: StatsigUser) => void;
layerParamCallback?: (layer: Layer, paramName: string, user: StatsigUser, event: LogEvent) => void;
```
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```javascript theme={null}
statsig.shutdown();
```
## Flush
To manually flush logged events:
```javascript theme={null}
await statsig.flush();
```
## Client SDK Bootstrapping
The Statsig server SDK can be used to generate the initialization values for a client SDK. This is useful for server-side rendering (SSR) or when you want to pre-fetch values for a client.
```typescript theme={null}
const values = Statsig.getClientInitializeResponse(user); // Record | null
if (values != null) {
// Bootstrap the Statsig React Client SDK
return
```typescript TypeScript theme={null}
// Overrides the given gate to the specified value
Statsig.overrideGate("a_gate_name", true, "a_user_id");
// Overrides the given config (dynamic config or experiment) to the provided value
Statsig.overrideConfig("a_config_or_experiment_name", { key: "value" }, "a_user_id");
// Overrides the given layer to the provided value
Statsig.overrideLayer("a_layer_name", { key: "value" }, "a_user_id");
```
```javascript JavaScript theme={null}
// Overrides the given gate to the specified value
Statsig.overrideGate("a_gate_name", true, "a_user_id");
// Overrides the given config (dynamic config or experiment) to the provided value
Statsig.overrideConfig("a_config_or_experiment_name", { key: "value" }, "a_user_id");
// Overrides the given layer to the provided value
Statsig.overrideLayer("a_layer_name", { key: "value" }, "a_user_id");
```
These can be used to set an override for a specific user, or for all users (by not providing a specific user ID). Experiments/Autotune are overridden with the `overrideConfig` API.
### Overriding in getClientInitializeResponse
You can also override feature gates, dynamic configs, experiments, and layers when calling `getClientInitializeResponse`. This is useful when you need to provide specific values to the client SDK.
```typescript TypeScript theme={null}
// Get client initialize response with overrides
const response = Statsig.getClientInitializeResponse(user, clientSDKKey, {
overrides: {
// Override feature gates
featureGates: {
'my_gate': true, // Override gate value to true
},
// Override dynamic configs and experiments
dynamicConfigs: {
// Override config value directly
'price_config': {
value: { price: 9.99 }
},
// Override experiment by setting the group assignment
'color_experiment': {
groupName: 'Control' // Uses the value for the Control group
},
// Override both value and group assignment
'spacing_experiment': {
value: { spacing: 64 },
groupName: 'Variant_B'
}
},
// Override layers
layers: {
'my_layer': {
value: { param: 123 }
}
}
}
});
```
```javascript JavaScript theme={null}
// Get client initialize response with overrides
const response = Statsig.getClientInitializeResponse(user, clientSDKKey, {
overrides: {
// Override feature gates
featureGates: {
'my_gate': true, // Override gate value to true
},
// Override dynamic configs and experiments
dynamicConfigs: {
// Override config value directly
'price_config': {
value: { price: 9.99 }
},
// Override experiment by setting the group assignment
'color_experiment': {
groupName: 'Control' // Uses the value for the Control group
},
// Override both value and group assignment
'spacing_experiment': {
value: { spacing: 64 },
groupName: 'Variant_B'
}
},
// Override layers
layers: {
'my_layer': {
value: { param: 123 }
}
}
}
});
```
For experiments, you can override them in two ways:
1. By setting a `value` override on their dynamic config to directly specify the parameter values
2. By setting the `groupName` assignment to use the value for that group name (e.g., "Control" or "Test")
You can also combine both approaches to override both the group assignment and the parameter values.
## Manual Exposures
Statsig SDKs automatically log an exposure event every time a gate/experiment/config is checked. In some scenarios, you may want to control when to log an exposure.
You can disable the automatic logging like this:
### Gates
```javascript theme={null}
const result = Statsig.checkGate(aUser, 'a_gate_name', {disableExposureLogging: true});
```
Then, to manually log the exposure:
```javascript theme={null}
Statsig.manuallyLogGateExposure(aUser, 'a_gate_name');
```
### Dynamic Configs
```javascript theme={null}
const config = Statsig.getConfigWithExposureLoggingDisabledSync(aUser, 'a_dynamic_config_name');
```
Then, to manually log the exposure:
```javascript theme={null}
Statsig.manuallyLogConfigExposure(aUser, 'a_dynamic_config_name');
```
### Experiments
```javascript theme={null}
const experiment = Statsig.getExperimentWithExposureLoggingDisabledSync(aUser, 'an_experiment_name');
```
Then, to manually log the exposure:
```javascript theme={null}
Statsig.manuallyLogExperimentExposure(aUser, 'an_experiment_name');
```
### Layers
```javascript theme={null}
const layer = Statsig.getLayerWithExposureLoggingDisabledSync(aUser, 'a_layer_name');
const paramValue = layer.get('a_param_name', 'fallback_value');
```
Then, to manually log the layer parameter exposure:
```javascript theme={null}
Statsig.manuallyLogLayerParameterExposure(aUser, 'a_layer_name', 'a_param_name');
```
## Cloudflare Workers Setup
### Polling for updates
The SDK cannot poll for updates across requests since Cloudflare does not allow for timers.
To solve for this, a manual sync API is available for independently updating the SDK internal store.
```javascript theme={null}
if (env.lastSyncTime < Date.now() - env.syncInterval) {
env.lastSyncTime = Date.now();
context.waitUntil(Statsig.syncConfigSpecs());
}
```
### Flushing events
The SDK enqueues logged events and flushes them in batches. In order to ensure events are properly flushed, we recommend calling `flush` using [`context.waitUntil`](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil).
This will keep the request handler alive until events are flushed without blocking the response.
```javascript theme={null}
context.waitUntil(Statsig.flush());
```
### Node.JS Compatibility
Many native JavaScript API and Node standard libraries can be accessed in Cloudflare via the [`nodejs_compat`](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) compatibility flag.
The SDK is now compatible with `nodejs_compat` (since v5.16.0). In older versions, manual polyfilling is required.
## User Persistent Storage
User Persistent Storage is a storage adapter for running sticky experiments. It allows you to persist user assignments across sessions.
### Interface
```typescript theme={null}
export interface IUserPersistentStorage {
/**
* Returns the full map of persisted values for a specific user key
* @param key user key
*/
load(key: string): UserPersistedValues;
/**
* Save the persisted values of a config given a specific user key
* @param key user key
* @param configName Name of the config/experiment
* @param data Object representing the persistent assignment to store for the given user-config
*/
save(key: string, configName: string, data: StickyValues): void;
/**
* Delete the persisted values of a config given a specific user key
* @param key user key
* @param configName Name of the config/experiment
*/
delete(key: string, configName: string): void;
}
```
### Example Implementation
```typescript theme={null}
class UserPersistentStorageExample implements IUserPersistentStorage {
public store: Record = {};
load(key: string): UserPersistedValues {
return this.store[key];
}
save(key: string, configName: string, data: StickyValues): void {
if (!(key in this.store)) {
this.store[key] = {};
}
this.store[key][configName] = data;
}
delete(key: string, configName: string): void {
delete this.store[key][configName];
}
}
```
## Multi-Instance Usage
If you need to create multiple independent instances of the Statsig SDK (for example, to use different API keys or configurations), you can use the instance-based approach:
```javascript theme={null}
// Statsig.initialize becomes:
const sdkInstance = new StatsigServer(secretKey, options);
await sdkInstance.initializeAsync();
```
## Forward Proxy Configuration
You can configure the SDK to use a forward proxy for network requests:
```javascript theme={null}
const proxyAddress = "0.0.0.0:50051"
const options = {
proxyConfigs: {
'download_config_specs': {
"proxyAddress": proxyAddress,
"protocol": "grpc_websocket" as NetworkProtocol
}
}
}
await Statsig.initialize(secretKey, options)
```
## FAQs
### How can I use the node SDK for server side rendering?
See [Client SDK Bootstrapping | SSR](#bootstrap)
### How can I mock Statsig for testing?
See [LocalOverrides](#local-overrides)
## Reference
### Type StatsigUser
```typescript theme={null}
export type StatsigUser =
// at least one of userID or customIDs must be provided
({ userID: string } | { customIDs: Record }) & {
userID?: string;
customIDs?: Record;
email?: string;
ip?: string;
userAgent?: string;
country?: string;
locale?: string;
appVersion?: string;
custom?: Record<
string,
string | number | boolean | Array | undefined
>;
privateAttributes?: Record<
string,
string | number | boolean | Array | undefined
> | null;
statsigEnvironment?: StatsigEnvironment;
}
```
### Type StatsigOptions
```typescript theme={null}
export type StatsigOptions = {
api: string;
apiForDownloadConfigSpecs: string;
apiForGetIdLists: string;
bootstrapValues: string | null;
environment: StatsigEnvironment | null;
rulesUpdatedCallback: RulesUpdatedCallback | null;
logger: LoggerInterface;
localMode: boolean;
initTimeoutMs: number;
dataAdapter: IDataAdapter | null;
rulesetsSyncIntervalMs: number;
idListsSyncIntervalMs: number;
loggingIntervalMs: number;
loggingMaxBufferSize: number;
disableDiagnostics: boolean;
initStrategyForIP3Country: InitStrategy;
initStrategyForIDLists: InitStrategy;
postLogsRetryLimit: number;
postLogsRetryBackoff: RetryBackoffFunc | number;
disableRulesetsSync: boolean;
disableIdListsSync: boolean;
disableAllLogging: boolean;
};
export type RulesUpdatedCallback = (rulesJSON: string, time: number) => void;
export type RetryBackoffFunc = (retriesRemaining: number) => number;
export type StatsigEnvironment = {
tier?: 'production' | 'staging' | 'development' | string;
[key: string]: string | undefined;
};
export type InitStrategy = 'await' | 'lazy' | 'none';
export interface LoggerInterface {
debug?(message?: any, ...optionalParams: any[]): void;
info?(message?: any, ...optionalParams: any[]): void;
warn(message?: any, ...optionalParams: any[]): void;
error(message?: any, ...optionalParams: any[]): void;
logLevel: 'none' | 'debug' | 'info' | 'warn' | 'error';
}
```
### Type FeatureGate
```typescript theme={null}
export type FeatureGate = {
readonly name: string;
readonly ruleID: string;
readonly idType: string | null;
readonly value: boolean;
readonly evaluationDetails: EvaluationDetails | null;
readonly groupName: null; // deprecated
};
```
### Type DynamicConfig
```typescript theme={null}
export default class DynamicConfig {
name: string;
value: Record;
get(
key: string,
defaultValue: T,
typeGuard: ((value: unknown) => value is T | null) | null = null,
): T;
getValue(
key: string,
defaultValue?: boolean | number | string | object | Array | null,
): unknown | null;
getRuleID(): string;
getGroupName(): string | null;
getIDType(): string | null;
getEvaluationDetails(): EvaluationDetails | null;
```
### Type Layer
```typescript theme={null}
export default class Layer {
name: string;
public get(
key: string,
defaultValue: T,
typeGuard: ((value: unknown) => value is T) | null = null,
): T;
getValue(
key: string,
defaultValue?: boolean | number | string | object | Array | null,
): unknown | null;
getRuleID(): string;
getGroupName(): string | null;
getAllocatedExperimentName(): string | null;
getEvaluationDetails(): EvaluationDetails | null;
```
### DataAdapter
```typescript theme={null}
export interface IDataAdapter {
get(key: string): Promise;
set(key: string, value: string, time?: number): Promise;
initialize(): Promise;
shutdown(): Promise;
supportsPollingUpdatesFor(key: DataAdapterKey): boolean;
}
```
### EvaluationDetails
```typescript theme={null}
export class EvaluationDetails {
readonly configSyncTime: number;
readonly initTime: number;
readonly serverTime: number;
readonly reason: EvaluationReason;
}
```
### EvaluationReason
```typescript theme={null}
export type EvaluationReason =
| 'Network'
| 'LocalOverride'
| 'Unrecognized'
| 'Uninitialized'
| 'Bootstrap'
| 'DataAdapter'
| 'Unsupported';
```
# Legacy PHP Server SDK
Source: https://docs.statsig.com/server/php
Statsig's legacy PHP Server SDK for evaluating feature gates, experiments, and dynamic configs in PHP backend applications. New projects use PHP Core.
[Github Repository](https://github.com/statsig-io/php-sdk)
## Setup the SDK
You can install the PHP SDK using composer.
```bash theme={null}
composer require statsig/statsigsdk
```
The SDK is also [open source and hosted on github](https://github.com/statsig-io/php-sdk). The package is published to [packagist](https://packagist.org/packages/statsig/statsigsdk).
To successfully use the PHP SDK, you need to:
1. Install it
2. Provide a storage adapter to cache config and event logs (easy default exists)
3. Schedule a Cron job to poll for config changes and flush event logs to Statsig
4. Initialize and use the SDK
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
There is also a parameter `options` that requires you to pass in a storage adapter for storing configurations and event logs. In this below example, we use a local file storage adapter, but you can write your own to plug in Redis or another storage solution.
You should create an adapter that implements `Statsig\Adapters\IConfigAdapter` that hooks up to your caching solution. By default, we provide a local file solution that can be useful for first time setup but is challenging to work with in production settings.
For help with the interface and implementing an adapter, browse the [adapters directory](https://github.com/statsig-io/php-sdk/tree/main/src/Adapters) in the open source SDK repository.
```php theme={null}
require_once __DIR__ . '/vendor/autoload.php'; // path to installation folder
use Statsig\StatsigServer;
use Statsig\StatsigOptions;
use Statsig\Adapters\LocalFileDataAdapter;
use Statsig\Adapters\LocalFileLoggingAdapter;
$config_adapter = new LocalFileDataAdapter();
$logging_adapter = new LocalFileLoggingAdapter();
$options = new StatsigOptions($config_adapter, $logging_adapter);
$this->statsig = new StatsigServer("server-sdk-key", $options);
```
### 🔥 Warning - You need to schedule a job 🔥
#### V3.0+
If you do not configure a job to update the config values, SDK does not fire a network request to fetch the latest config value anymore, instead, config values fetched earlier will be used.
See [Cron Jobs](#cron-jobs)
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```php theme={null}
use Statsig\StatsigUser;
$user = StatsigUser::withUserID("123");
$user->setEmail("testuser@statsig.com");
$this->statsig->checkGate($user, "");
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```php theme={null}
$this->statsig->getConfig($user, "");
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```php theme={null}
// Values via getLayer
$layer = $this->statsig->getLayer($user, "user_promo_experiments");
$title = $layer->get("title", "Welcome to Statsig!");
$discount = $layer->get("discount", 0.1);
// or, via getExperiment
$title_experiment = $this->statsig->getExperiment($user, "new_user_promo_title");
$price_experiment = $this->statsig->getExperiment($user, "new_user_promo_price");
$title = $title_experiment->get("title", "Welcome to Statsig!")
$discount = $price_experiment->get("discount", 0.1)
...
$price = $msrp * (1 - $discount)
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```php theme={null}
$event = new StatsigEvent("purchase");
$event->setUser($user);
$event->setValue("subscription");
$event->setMetadata(array("promotion" => "2022 deals"));
$this->statsig->logEvent($event);
```
At the end of the request, you can flush events to the log file using:
```php theme={null}
$this->statsig->flush();
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Cron Jobs
To keep your configurations up to date, and send event data to Statsig, you can create two jobs. Here, we document them as cron jobs, but you can use any out of band
process to run them. If you are using Laravel, for example, you can use Commands to run them locally and on a schedule.
### Sync
The first job runs `sync.php` to download the latest definition of gates/configs/experiments from Statsig, and save it to a config file locally.
If you do not update this file, your gate/config/experiment values may be stale and will be refetched during a request, which may lead to slower response times.
```bash theme={null}
# Run once
php sync.php --secret
```
```bash theme={null}
# Create a cron job that runs as statsigsync every minute
echo '*/1 * * * * statsigsync php /my/path/to/statsig/sync.php --secret > /dev/null' | sudo tee /etc/cron.d/statsigsync
sudo service cron reload # reload the cron daemon
```
You should provide your own custom adapter that implements Statsig\Adapters\IDataAdapter
```bash theme={null}
php send.php --secret \
--adapter-class Namespace\For\MyConfigAdapter \
--adapter-path /path/to/MyConfigAdapter.php \
--adapter-arg an_argument_for_my_adapter \
--adapter-arg another_argument
```
By default, sync.php will use the Statsig LocalFileDataAdapter which writes to /tmp/statsig.configs
### Send
The second runs `send.php` to send the exposure data and log events to statsig. Without this data, your events will need to be logged during the lifetime of the request, which may lead to slower response times.
```bash theme={null}
# Run once
php send.php --secret
```
```bash theme={null}
# Create a cron job that runs as statsigdata every minute
echo '*/1 * * * * statsigdata php /my/path/to/statsig/send.php --secret > /dev/null' | sudo tee /etc/cron.d/statsigdata
sudo service cron reload # reload the cron daemon
```
You should provide your own custom adapter that implements Statsig\Adapters\ILoggingAdapter
```bash theme={null}
php send.php --secret \
--adapter-class Namespace\For\MyLoggingAdapter \
--adapter-path /path/to/MyLoggingAdapter.php \
--adapter-arg an_argument_for_my_adapter \
--adapter-arg another_argument
```
By default, send.php will use the Statsig LocalFileDataAdapter which writes to /tmp/statsig.logs
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
# Legacy Python Server SDK
Source: https://docs.statsig.com/server/pythonSDK
Statsig's legacy Python Server SDK for evaluating feature gates, experiments, and dynamic configs in Python backend services. New projects use Python Core.
[Github Repository](https://github.com/statsig-io/python-sdk)
## Setup the SDK
Install the sdk using [pip3](https://pypi.org/project/statsig/):
The Statsig SDK is not compatible with python 2. You must be on python 3.7+ to use the Statsig SDK.
```bash theme={null}
pip3 install statsig
```
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
There is also an optional parameter named `options` that allows you to pass in a [StatsigOptions](#statsig-options) to customize the SDK.
```python theme={null}
from statsig import statsig
statsig.initialize("server-secret-key")
# or with StatsigOptions
options = StatsigOptions(tier=StatsigEnvironmentTier.development)
statsig.initialize("server-secret-key", options)
# check if sdk is initialized
initialized = statsig.is_initialized()
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```python theme={null}
from statsig.statsig_user import StatsigUser
...
statsig.check_gate(StatsigUser("user-id"), "gate-name")
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```python theme={null}
config = statsig.get_config(StatsigUser("user-id"), "config-name")
config_json = config.get_value()
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```python theme={null}
# Values via getLayer
layer = statsig.get_layer(user, "user_promo_experiments")
title = layer.get("title", "Welcome to Statsig!")
discount = layer.get("discount", 0.1)
# or, via getExperiment
title_exp = statsig.get_experiment(user, "new_user_promo_title")
price_exp = statsig.get_experiment(user, "new_user_promo_price")
title = title_exp.get("title", "Welcome to Statsig!")
discount = price_exp.get("discount", 0.1)
...
price = msrp * (1 - discount)
```
## Retrieving Feature Gate Metadata
In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:
```python theme={null}
gate = statsig.get_feature_gate(StatsigUser("user-id"), "gate-name")
print(gate.name) # 'gate-name'
print(gate.value) # True or False
print(gate.rule_id) # rule ID that was evaluated
print(gate.evaluation_details) # evaluation metadata
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```python theme={null}
from statsig.statsig_user import StatsigUser
from statsig.statsig_event import StatsigEvent
statsig.log_event(StatsigEvent(StatsigUser("user-id"), "event-name"))
```
Python supports `retry_queue_size`, which allows you to adjust the memory allocated for handling retries.
While service outages are rare, increasing the retry\_queue\_size can help minimize event loss by providing additional memory to buffer events during such occurrences.
This option is generally not needed for typical use but offers added flexibility in exceptional situations.
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Statsig Options
`initialize()` takes an optional parameter `options` in addition to the secret key that you can provide to customize the Statsig client. Here are the current options and we are always adding more to the list:
Create a `StatsigOptions` class to pass in with the following available parameters:
(unit of measure for time related options is seconds)
Sets the environment tier (for gates to evaluate differently in development and production)
You can set an environment tier with the `StatsigEnvironmentTier` enum or just as a `str`
Enforces a minimum timeout on network requests from the SDK
Sets the maximum timeout on download config specs and id lists network requests for initialization
How often the SDK updates rulesets from Statsig servers
How often the SDK updates idlists from Statsig servers
Disables all network requests. SDK returns default values and will not log events. Useful in combination with overrides to mock behavior for tests
a string that represents all rules for all feature gates, dynamic configs and experiments. It can be provided to bootstrap the Statsig server SDK at initialization in case your server runs into network issue or Statsig server is down temporarily.
a callback function that's called whenever we have an update for the rules; it's called with a logical timestamp and a JSON string (used as is for bootstrapValues mentioned above). Note that as of v0.6.0, this will be called from a background thread that the SDK uses to update config values.
The number of events to batch before flushing the queue to the network. Default 500.
Note that events are also batched every minute by a background thread
A data store with custom storage behavior for config specs. Can be used to bootstrap Statsig server (takes priority over `bootstrap_values`).
Configuration network for each endpoint, for example, download\_config\_spec, get\_id\_lists
Fallback to Statsig CDN for download config specs and get id lists if the overridden api failed.
List of sources SDK tries to get download\_config\_specs from when initialize. The list is ordered, SDK tries to get source from first element, and stops when getting dcs successfully
List of sources SDK tries to get download\_config\_specs from when downloading. The list is ordered, SDK tries to get source from first element, and stops when getting dcs successfully
Example:
```python theme={null}
from statsig import statsig, StatsigEnvironmentTier, StatsigOptions
options = StatsigOptions(None, StatsigEnvironmentTier.development)
statsig.initialize("secret-key", options).wait()
```
You can also use the `set_environment_parameter` function, but that takes in string values only:
```python theme={null}
from statsig import statsig, StatsigEnvironmentTier, StatsigOptions
options = StatsigOptions()
options.set_environment_parameter("tier", StatsigEnvironmentTier.development.value)
statsig.initialize("secret-key", options).wait()
```
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```python theme={null}
statsig.shutdown()
```
## Client SDK Bootstrapping
The Statsig server SDK can be used to generate the initialization values for a client SDK. This is useful for server-side rendering (SSR) or when you want to pre-fetch values for a client.
```python theme={null}
values = statsig.get_client_initialize_response(user); # dict() | None
# To apply local overrides, set include_local_overrides = True (python sdk v0.32.0+)
values = statsig.get_client_initialize_response(user=user, include_local_overrides=True); # dict() | None
```
## Local Overrides
You can override the values returned by the SDK for testing purposes. This can be useful for local development when you want to test specific scenarios.
```python theme={null}
# Adding/Removing gate overrides
statsig.override_gate("a_gate_name", true, "a_user_id")
statsig.remove_gate_override("a_gate_name", "a_user_id")
# Adding/Removing config overrides
statsig.override_config("a_config_name", {"key": "value"}, "a_user_id")
statsig.remove_config_override("a_config_name", "a_user_id")
# Adding/Removing experiment overrides
statsig.override_experiment("an_experiment_name", {"key": "value"}, "a_user_id")
statsig.remove_experiment_override("an_experiment_name", "a_user_id")
# Remove All Overrides
statsig.remove_all_overrides()
# You can also override with custom ids
custom_id_user = StatsigUser("a_user_id", custom_ids={"statsigId": "a_statsig_id"})
statsig.override_gate("a_gate_name", true, "a_statsig_id")
# Local overrides will prioritize override with userId, then look up the custom id to override.
# To prevent clashing overrides, it is recommended to not use the same value for userId and customIds for different users.
```
## Multi-Instance Usage
If you need to create multiple independent instances of the Statsig SDK (for example, to use different API keys or configurations), you can use the instance-based approach:
```python theme={null}
sdk_instance = StatsigServer()
sdk_instance.initialize(secret_key, options);
```
## Forward Proxy Configuration
You can configure the SDK to use a forward proxy for network requests:
Basic setup to stream download config spec from forward proxy:
```python theme={null}
proxyAddress = "0.0.0.0:50051" // local address update to your address
Statsig.initialize(secret_key, StatsigOptions(proxy_configs={
NetworkEndpoint.DOWNLOAD_CONFIG_SPECS: ProxyConfig(NetworkProtocol.GRPC_WEBSOCKET, proxyAddress)}))
```
When the SDK is disconnected from forward proxy when use grpc\_websocket, the sdk will retry connection with exponential backoff, after `push_worker_failover_threshold` retries, the sdk will start polling from Statsig until reconnecting to the forward proxy.
You can customize Streaming Failover Behavior. You can also define the sources/endpoints SDK poll from, SDK will try from source at index 0, and stops trying if get a response.
```python theme={null}
statsigOptions = StatsigOptions(
proxy_configs={
NetworkEndpoint.DOWNLOAD_CONFIG_SPECS: ProxyConfig(
protocol=NetworkProtocol.GRPC_WEBSOCKET,
proxy_address=address,
push_worker_failover_threshold=1, # start polling from Statsig endpoint after 1 retry failed
# 1st retry 5000 ms later, 2nd retry 2 * 5000ms = 10 seconds ....
retry_backoff_multiplier=2,
max_retry_attempt=8,
retry_backoff_base_ms=5000
)
},
# Get from network first, which is forward proxy here, if fails, try datastore, if fails try poll from Statsig endpoint
initialize_sources=[
DataSource.NETWORK,
DataSource.DATASTORE,
DataSource.STATSIG_NETWORK,
],
)
```
## FAQs
### How can I mock Statsig for testing?
The python server SDK, starting in version 0.5.1+, supports a few features to make testing easier.
First, there is a `StatsigOption` parameter called `localMode`. Setting `localMode` to true will cause the SDK to never hit the network, and only return default values. This is perfect for dummy environments or test environments that should not access the network.
Next, there are the `overrideGate` and `overrideConfig` APIs on the global `statsig` interface, see [Local Overrides](#local-overrides)
These can be used to set a gate or config override for a specific user, or for all users (by not providing a specific user ID).
We suggest you enable `localMode` and then override gates/configs/experiments to specific values to test the various code flows you are building.
### Can I generate the initialize response for a client SDK using the Python server SDK?
Yes. See [Client Initialize Response](#bootstrap).
## Reference
### StatsigUser
```python theme={null}
@dataclass
class StatsigUser:
"""An object of properties relating to the current user
user_id or customID is required: https://docs.statsig.com/sdks/user#why-is-an-id-always-required-for-server-sdks
Provide as many as possible to take advantage of advanced conditions in the statsig console
A dictionary of additional fields can be provided under the custom field
Set private_attributes for any user property you need for gate evaluation but prefer stripped from logs/metrics
"""
user_id: Optional[str] = None
email: Optional[str] = None
ip: Optional[str] = None
user_agent: Optional[str] = None
country: Optional[str] = None
locale: Optional[str] = None
app_version: Optional[str] = None
custom: Optional[dict] = None # key: string, value: string
private_attributes: Optional[dict] = None # key: string, value: string
custom_ids: Optional[dict] = None # key: string, value: string
```
### StatsigOptions
```python theme={null}
class StatsigOptions:
"""An object of properties for initializing the sdk with additional parameters"""
def __init__(
self,
api: Optional[str] = None,
api_for_download_config_specs: Optional[str] = None,
api_for_get_id_lists: Optional[str] = None,
api_for_log_event: Optional[str] = None,
tier: Union[str, StatsigEnvironmentTier, None] = None,
init_timeout: Optional[int] = None,
timeout: Optional[int] = None,
rulesets_sync_interval: int = DEFAULT_RULESET_SYNC_INTERVAL,
idlists_sync_interval: int = DEFAULT_IDLIST_SYNC_INTERVAL,
local_mode: bool = False,
bootstrap_values: Optional[str] = None,
rules_updated_callback: Optional[Callable] = None,
event_queue_size: Optional[int] = DEFAULT_EVENT_QUEUE_SIZE,
data_store: Optional[IDataStore] = None,
idlists_thread_limit: int = DEFAULT_IDLISTS_THREAD_LIMIT,
logging_interval: int = DEFAULT_LOGGING_INTERVAL, #deprecated
disable_diagnostics: bool = False,
custom_logger: Optional[OutputLogger] = None,
enable_debug_logs = False,
disable_all_logging = False,
evaluation_callback: Optional[Callable[[Union[Layer, DynamicConfig, FeatureGate]], None]] = None,
retry_queue_size: int = DEFAULT_RETRY_QUEUE_SIZE,
proxy_configs: Optional[Dict[NetworkEndpoint, ProxyConfig]] = None,
fallback_to_statsig_api: Optional[bool] = False,
initialize_sources: Optional[List[DataSource]] = None,
config_sync_sources: Optional[List[DataSource]] = None,
):
```
### FeatureGate
```python theme={null}
class FeatureGate:
def get_value(self):
"""Returns the underlying value of this FeatureGate"""
def get_name(self):
"""Returns the name of this FeatureGate"""
def get_evaluation_details(self):
"""Returns the evaluation detail of this FeatureGate"""
```
### DynamicConfig
```python theme={null}
class DynamicConfig:
def get(self, key, default=None):
"""Returns the value of the config at the given key
or the provided default if the key is not found
"""
def get_typed(self, key, default=None):
"""Returns the value of the config at the given key
iff the type matches the type of the provided default.
Otherwise, returns the default value
"""
def get_value(self):
"""Returns the underlying value of this DynamicConfig"""
def get_name(self):
"""Returns the name of this DynamicConfig"""
def get_evaluation_details(self):
"""Returns the evaluation detail of this DynamicConfig"""
```
### Layer
```python theme={null}
class Layer:
def get(self, key, default=None):
"""Returns the value of the layer at the given key
or the provided default if the key is not found
"""
def get_typed(self, key, default=None):
"""Returns the value of the layer at the given key
iff the type matches the type of the provided default.
Otherwise, returns the default value
"""
def get_name(self):
"""Returns the name of this Layer"""
def get_values(self):
"""Returns all the values in this Layer but does not trigger an exposure log"""
def get_evaluation_details(self):
"""Returns the evaluation detail of this Layer"""
```
### EvaluationDetails
```python theme={null}
class EvaluationDetails:
reason: EvaluationReason
config_sync_time: int
init_time: int
server_time: int
class EvaluationReason(str, Enum):
network = "Network"
local_override = "LocalOverride"
unrecognized = "Unrecognized"
uninitialized = "Uninitialized"
bootstrap = "Bootstrap"
data_adapter = "DataAdapter"
unsupported = "Unsupported"
error = "error"
```
### DataStore
```python theme={null}
class IDataStore:
def get(self, key: str) -> Optional[str]:
return None
def set(self, key: str, value: str):
pass
def shutdown(self):
pass
def should_be_used_for_querying_updates(self, key: str) -> bool:
return False
```
### ForwardProxy - ProxyConfig
```python theme={null}
class NetworkProtocol(Enum):
HTTP = "http"
GRPC = "grpc"
GRPC_WEBSOCKET = "grpc_websocket"
class NetworkEndpoint(Enum):
LOG_EVENT = "log_event"
DOWNLOAD_CONFIG_SPECS = "download_config_specs"
GET_ID_LISTS = "get_id_lists"
ALL = "all"
class ProxyConfig:
def __init__(
self,
protocol: NetworkProtocol,
proxy_address: str,
# Websocket worker failover config
max_retry_attempt: Optional[int] = None, # default is 10
retry_backoff_multiplier: Optional[int] = None, # default is # default is 5
retry_backoff_base_ms: Optional[int] = None, # default is 10,000 ms
# Push worker failback to polling threshold, fallback immediate set 0,
# n means fallback after n retry failed
push_worker_failover_threshold: Optional[int] = None, # default is 4, about 30 minutes
):
self.proxy_address = proxy_address
self.protocol = protocol
self.max_retry_attempt = max_retry_attempt
self.retry_backoff_multiplier = retry_backoff_multiplier
self.retry_backoff_base_ms = retry_backoff_base_ms
self.push_worker_failover_threshold = push_worker_failover_threshold
```
# Ruby Server SDK
Source: https://docs.statsig.com/server/ruby
Use the Statsig Ruby Server SDK to evaluate feature gates, experiments, and dynamic configs from Ruby and Ruby on Rails backend applications.
View the Ruby SDK source code and releases
## Setup the SDK
If you are using Bundler, add the [gem](https://rubygems.org/gems/statsig) to your Gemfile from command line:
```shell theme={null}
bundle add statsig
```
or directly include it in your Gemfile and run `bundle install`:
```shell theme={null}
gem "statsig", ">= X.Y.Z"
```
Check out the latest versions on [https://rubygems.org/gems/statsig](https://rubygems.org/gems/statsig)
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
```ruby theme={null}
require 'statsig'
Statsig.initialize('server-secret-key')
```
```ruby theme={null}
# Or, if you want to initialize with certain options
options = StatsigOptions.new({'tier' => 'staging'}, network_timeout: 5)
# And a callback when the initialization network request fails
def error_callback(e)
puts e
end
...
Statsig.initialize('server-secret-key', options, method(:error_callback))
```
### Initializing Statsig in a Rails Application
If your application is using Rails, you should initialize Statsig in `config/initializers/statsig.rb`:
```ruby theme={null}
Statsig.initialize('server-secret-key', options)
```
### Initializing Statsig when using Unicorn, Puma, Passenger, or Sidekiq
For **Unicorn**, you should initialize Statsig within an `after_fork` hook in your `unicorn.rb` config file:
```ruby theme={null}
after_fork do |server,worker|
Statsig.initialize('server-secret-key', options)
end
```
For **Puma**, you should initialize Statsig within an `on_worker_boot` hook in your `puma.rb` config file:
```ruby theme={null}
on_worker_boot do
Statsig.initialize('server-secret-key', options)
end
```
For **Passenger**, you should initialize Statsig in your `config.ru` config file:
```ruby theme={null}
if defined?(PhusionPassenger)
PhusionPassenger.on_event(:starting_worker_process) do |forked|
Statsig.initialize('server-secret-key', options)
end
end
```
For **Sidekiq**, you should initialize Statsig in your `sidekiq.rb`/server configuration file:
```ruby theme={null}
Sidekiq.configure_server do |config|
config.on(:startup) do
Statsig.initialize
end
config.on(:shutdown) do
Statsig.shutdown
end
end
```
If you are using Rails in combination with any of the above, you should be sure to initialize using the specific process lifecycle hooks exposed by the respective tool. You can initialize in multiple places, which should ensure the SDK is fully usable including all background processing.
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```ruby theme={null}
user = StatsigUser.new({'userID' => 'some_user_id'})
if Statsig.check_gate(user, 'use_new_feature')
# Gate is on, enable new feature
else
# Gate is off
end
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```ruby theme={null}
config = Statsig.get_config(user, 'awesome_product_details')
# The 2nd parameter is the default value to be used in case the given parameter name does not exist on
# the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
# value has not been cached on the client.
item_name = config.get('product_name', 'Awesome Product v1');
price = config.get('price', 10.0);
shouldDiscount = config.get('discount', false);
# Or just get the whole json object backing this config if you prefer
json = config.value
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```ruby theme={null}
# Values via getLayer
layer = Statsig.get_layer(user, "user_promo_experiments")
title = layer.get("title", "Welcome to Statsig!")
discount = layer.get("discount", 0.1)
# or, via getExperiment
title_exp = Statsig.get_experiment(user, "new_user_promo_title")
price_exp = Statsig.get_experiment(user, "new_user_promo_price")
title = title_exp.get("title", "Welcome to Statsig!")
discount = price_exp.get("discount", 0.1)
...
price = msrp * (1 - discount)
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```ruby theme={null}
Statsig.log_event(
user,
'add_to_cart',
'SKU_12345',
{
'price' => '9.99',
'item_name' => 'diet_coke_48_pack'
}
)
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Statsig Options
`initialize()` takes an optional parameter `options` in addition to the secret key that you can provide to customize the Statsig client. Here are the current options and we are always adding more to the list:
You can specify optional parameters with `options` when initializing.
* **environment**: Hash, default `nil`
* a Hash you can use to set environment variables that apply to all of your users in the same session and will be used for targeting purposes.
* The most common usage is to set the "tier" (string), and have feature gates pass/fail for specific environments. The accepted values are "production", "staging" and "development", e.g. `StatsigOptions.New({ 'tier' => 'staging' })`.
* **download\_config\_specs\_url**: String, default `"https://api.statsigcdn.com/v2/download_config_specs/"`
* The url used specifically to call download\_config\_specs
* **log\_event\_url**: String, default `"https://statsigapi.net/v1/log_event"`
* The url used specifically to call log\_event
* **get\_id\_lists\_url**: String, default `"https://statsigapi.net/v1/get_id_lists"`
* The url used specifically to call get\_id\_lists
* **rulesets\_sync\_interval**: Number, default `10`
* The interval (in seconds) to poll for changes to your Statsig configuration
* **idlists\_sync\_interval**: Number, default `60`
* The interval (in seconds) to poll for changes to id lists
* **disable\_rulesets\_sync**: Boolean, default `false`
* Disable background syncing for rulesets
* **disable\_idlists\_sync**: Boolean, default `false`
* Disable background syncing for id lists
* **logging\_interval\_seconds**: Number, default `60`
* How often to flush logs to Statsig
* **logging\_max\_buffer\_size**: Number, default `1000`, can be set lower but anything over 1000 will be dropped on the server
* The maximum number of events to batch before flushing logs to the server
* **local\_mode**: Boolean, default `false`
* Restricts the SDK to not issue any network requests and only respond with default values (or local overrides)
* **bootstrap\_values**: String, default `nil`
* A string that represents all rules for all feature gates, dynamic configs and experiments. It can be provided to bootstrap the Statsig server SDK at initialization in case your server runs into network issue or Statsig server is down temporarily.
* **rules\_updated\_callback**: function, default `nil`
* A callback function that will be called anytime the rulesets are updated
* **data\_store**: IDataStore, default `nil`
* A class that extends IDataStore. Can be used to provide values from a common data store (like Redis) to initialize the Statsig SDK.
* **idlist\_threadpool\_size**: Number, default `3`
* The number of threads allocated to syncing IDLists
* **logger\_threadpool\_size**: Number, default `3`
* The number of threads allocated to posting event logs
* **disable\_diagnostics\_logging**: Boolean, default `false`
* Should diagnostics be logged. These include performance metrics for initialize
* **disable\_sorbet\_logging\_handlers**: Boolean, default `false`
* Statsig utilizes Sorbet ([https://sorbet.org](https://sorbet.org)) to ensure type safety of the SDK. This includes logging to console when errors are detected. You can disable this logging by setting this flag to true.
* **network\_timeout**: Number, default `nil`
* Maximum number of seconds to wait for a network call before timing out
* **post\_logs\_retry\_limit**: Number, default `3`
* Number of times to retry sending a batch of failed log events
* **post\_logs\_retry\_backoff**: Number/Function, default `nil`
* The number of seconds, or a function that returns the number of seconds based on the number of retries remaining which overrides the default backoff time between retries
* **user\_persistent\_storage**: IUserPersistentStorage, default `nil`
* A storage adapter for persisted values. Can be used for sticky bucketing users in experiments. Implements Statsig::Interfaces::IUserPersistentStorage.
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```ruby theme={null}
Statsig.shutdown
```
## Client SDK Bootstrapping
The Statsig server SDK can be used to generate the initialization values for a client SDK. This is useful for server-side rendering (SSR) or when you want to pre-fetch values for a client.
```ruby theme={null}
values = Statsig.get_client_initialize_response(user); # Hash[String, Any] | Nil
```
## Local Overrides
You can override the values returned by the SDK for testing purposes. This can be useful for local development when you want to test specific scenarios.
```ruby theme={null}
# Adding gate overrides
Statsig.override_gate("a_gate_name", true)
# Adding config overrides
Statsig.override_config("a_config_name", {"key" => "value"})
```
1. These only apply locally - they do not update definitions in the Statsig console or elsewhere.
2. The local override API is not designed to be a full mock. They are only a convenient way to override the value of the gate/config/etc.
## Manual Exposures
Statsig SDKs automatically log an exposure event every time a gate/experiment/config is checked. In some scenarios, you may want to control when to log an exposure.
**Gates**
```ruby theme={null}
result = Statsig.check_gate(user, 'a_gate_name', CheckGateOptions.new(disable_log_exposure: true))
```
```ruby theme={null}
Statsig.manually_log_gate_exposure(user, 'a_gate_name')
```
**Configs**
```ruby theme={null}
config = Statsig.get_config(user, 'a_dynamic_config_name', GetConfigOptions.new(disable_log_exposure: true))
```
```ruby theme={null}
Statsig.manually_log_config_exposure(user, 'a_dynamic_config_name')
```
**Experiments**
```ruby theme={null}
experiment = Statsig.get_experiment(user, 'an_experiment_name', GetExperimentOptions.new(disable_log_exposure: true))
```
```ruby theme={null}
Statsig.manually_log_experiment_exposure(user, 'an_experiment_name')
```
**Layers**
```ruby theme={null}
layer = Statsig.get_layer(user, 'a_layer_name', GetLayerOptions.new(disable_log_exposure: true))
paramValue = layer.get('a_param_name', 'fallback_value')
```
```ruby theme={null}
Statsig.manually_log_layer_parameter_exposure(user, 'a_layer_name', 'a_param_name')
```
## User Persistent Storage
User Persistent Storage is a storage adapter for running sticky experiments. It allows you to persist user assignments across sessions.
### Interface
### Interface
```ruby theme={null}
class IUserPersistentStorage
def load(key)
nil
end
def save(key, data) end
end
```
### Example Implementation
```ruby theme={null}
class DummyPersistentStorageAdapter < Statsig::Interfaces::IUserPersistentStorage
attr_accessor :store
def initialize
@store = {}
end
def load(key)
return nil unless @store&.key?(key)
@store[key]
end
def save(key, data)
@store[key] = data
end
end
```
## Multi-Instance Usage
If you need to create multiple independent instances of the Statsig SDK (for example, to use different API keys or configurations), you can use the instance-based approach:
```ruby theme={null}
sdk_instance = StatsigDriver.new(secret_key, options, error_callback)
```
## FAQ
#### How do I run experiments for logged out users?
See the guide on [device level experiments](/guides/first-device-level-experiment)
#### How can I mock or override the SDK for testing?
Starting in `v1.12.0+`, the Ruby SDK supports `localMode` and `overrides`, see [Local Overrides](#local-overrides)
* `localMode` is a boolean parameter in `StatsigOptions` when initializing the SDK. It restricts all network traffic,
so the SDK operates offline and only returns default or override values.
#### Can I generate the initialize response for a client SDK using the Ruby server SDK?
Yes. See [Client SDK Bootstrapping](#client-sdk-bootstrapping).
## Reference
### Type StatsigUser
```ruby theme={null}
export type StatsigUser = {
class StatsigUser
attr_accessor :user_id
attr_accessor :email
attr_accessor :ip
attr_accessor :user_agent
attr_accessor :country
attr_accessor :locale
attr_accessor :app_version
attr_accessor :statsig_environment
attr_accessor :custom_ids # Hash of key:string value:string
attr_accessor :private_attributes # Hash of key:string value:string
@custom # Hash of key:string value:string
def initialize(user_hash)
@statsig_environment = Hash.new
if user_hash.is_a?(Hash)
@user_id = user_hash['userID'] || user_hash['user_id']
@user_id = @user_id.to_s unless @user_id.nil?
@email = user_hash['email']
@ip = user_hash['ip']
@user_agent = user_hash['userAgent'] || user_hash['user_agent']
@country = user_hash['country']
@locale = user_hash['locale']
@app_version = user_hash['appVersion'] || user_hash['app_version']
@custom = user_hash['custom'] if user_hash['custom'].is_a? Hash
@statsig_environment = user_hash['statsigEnvironment']
@private_attributes = user_hash['privateAttributes'] if user_hash['privateAttributes'].is_a? Hash
custom_ids = user_hash['customIDs'] || user_hash['custom_ids']
@custom_ids = custom_ids if custom_ids.is_a? Hash
end
end
end
```
### Type StatsigOptions
```ruby theme={null}
class StatsigOptions
attr_accessor :environment
attr_accessor :download_config_specs_url
attr_accessor :log_event_url
attr_accessor :get_id_lists_url
attr_accessor :rulesets_sync_interval
attr_accessor :idlists_sync_interval
attr_accessor :disable_rulesets_sync
attr_accessor :disable_idlists_sync
attr_accessor :logging_interval_seconds
attr_accessor :logging_max_buffer_size
attr_accessor :local_mode
attr_accessor :bootstrap_values
attr_accessor :rules_updated_callback
attr_accessor :data_store
attr_accessor :idlist_threadpool_size
attr_accessor :logger_threadpool_size
attr_accessor :disable_diagnostics_logging
attr_accessor :disable_sorbet_logging_handlers
attr_accessor :network_timeout
attr_accessor :post_logs_retry_limit
attr_accessor :post_logs_retry_backoff
attr_accessor :user_persistent_storage
def initialize(
environment = nil,
download_config_specs_url: nil,
log_event_url: nil,
get_id_lists_url: nil,
rulesets_sync_interval: 10,
idlists_sync_interval: 60,
disable_rulesets_sync: false,
disable_idlists_sync: false,
logging_interval_seconds: 60,
logging_max_buffer_size: 1000,
local_mode: false,
bootstrap_values: nil,
rules_updated_callback: nil,
data_store: nil,
idlist_threadpool_size: 3,
logger_threadpool_size: 3,
disable_diagnostics_logging: false,
disable_sorbet_logging_handlers: false,
network_timeout: nil,
post_logs_retry_limit: 3,
post_logs_retry_backoff: nil,
user_persistent_storage: nil
)
end
end
```
### DataStore
```ruby theme={null}
module Statsig
module Interfaces
class IDataStore
def init
end
def get(key)
nil
end
def set(key, value)
end
def shutdown
end
end
end
end
```
# Legacy Rust Server SDK
Source: https://docs.statsig.com/server/rust
Statsig's legacy Rust Server SDK for evaluating feature gates, experiments, and dynamic configs in Rust backend services. New projects use Rust Core SDK.
Support for the Legacy Rust SDK ends April 30, 2026. Migrate to the [new Rust SDK](/server-core/rust-core) soon.
Rust SDK on Github
## Setup the SDK
To use the SDK, add `statsig` as a dependency in your `Cargo.toml`. The latest version can be found at [crates.io/crates/statsig](https://crates.io/crates/statsig).
```toml theme={null}
[dependencies]
statsig = "X.Y.Z" # <- update version
```
After installation, you will need to initialize the SDK using a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).
Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.
```rust theme={null}
use statsig::{Statsig};
Statsig::initialize("secret-key").await;
// or with StatsigOptions
use statsig::{Statsig, StatsigOptions};
let env = HashMap::from([("tier".to_string(), "staging".to_string())]);
let opts = StatsigOptions {
environment: Some(env),
..StatsigOptions::default()
};
Statsig::initialize_with_options("secret-key", opts).await;
```
`initialize` will perform a network request. After `initialize` completes, virtually all SDK operations will be synchronous (See [Evaluating Feature Gates in the Statsig SDK](https://blog.statsig.com/evaluating-feature-gates-in-the-statsig-sdk-a6f8881a1ad8)). The SDK will fetch updates from Statsig in the background, independently of your API calls.
## Working with the SDK
## Checking a Feature Flag/Gate
Now that your SDK is initialized, let's fetch a [**Feature Gate**](/feature-flags/overview). Feature Gates can be used to 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.
From this point on, all APIs will require you to specify the user (see [Statsig user](#statsig-user)) associated with the request. For example, check a gate for a certain user like this:
```rust theme={null}
let user = StatsigUser::with_user_id("a-user".to_string());
if Statsig::check_gate(&user, "a_gate").ok().unwrap_or(false) {
// Gate is on, enable new feature
} else {
// Gate is off
}
```
## Reading a Dynamic Config
Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, [**Dynamic Configs**](/dynamic-config) can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it.
```rust theme={null}
let config = Statsig::get_config(&user, "a_config").ok().unwrap();
let value = config.get_string("a_key", "default_value");
```
## Getting a Layer/Experiment
Then we have **Layers/Experiments**, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of [layers](/layers) to enable quicker iterations with parameter reuse.
```rust theme={null}
let layer = Statsig::get_layer(&user, "a_layer").ok().unwrap();
let param_value = layer.get_string("a_parameter", "default_value");
// or via get_experiment
let experiment = Statsig::get_experiment(&user, "an_experiment").ok().unwrap();
let exp_value = experiment.get_string("a_parameter", "default_value");
```
## Logging an Event
Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:
```rust theme={null}
let event = StatsigEvent::new("event_name".to_string());
Statsig::log_event(&user, event);
```
Learn more about identifying users, group analytics, and best practices for logging events in the [logging events guide](/guides/logging-events).
## Statsig User
When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. As explained [here](/sdks/user#why-is-an-id-always-required-for-server-sdks), at least one identifier (userID or customID) is required to provide a consistent experience for a given user.
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.
Note that while typing is lenient on the `StatsigUser` object to allow you to pass in numbers, strings, arrays, objects, and potentially even enums or classes, the evaluation operators will only be able to operate on primitive types - mostly strings and numbers. While we attempt to smartly cast custom field types to match the operator, we cannot guarantee evaluation results for other types. For example, setting an array as a custom field will only ever be compared as a string - there is no operator to match a value in that array.
### Private Attributes
Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called `privateAttributes`, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in `privateAttributes` will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.
For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user and that's it!
## Shutdown
To gracefully shutdown the SDK and ensure all events are flushed:
```rust theme={null}
Statsig::shutdown().await;
```
# CLI Session Replay
Source: https://docs.statsig.com/session-replay/cli-session-replay
Use the Statsig CLI to inspect, export, and manage session replay recordings, including filtering by user, session, and time range.
CLI Session Replay allows you to record terminal sessions in your Node.js CLI applications and replay them in the Statsig Console. This enables you to understand how users interact with your command-line tools, diagnose issues, and improve the user experience.
The plugin records terminal output and resize events.
User input is planned for a future version, but given that it's likely to contain sensitive information,
we'll release it after introducing methods to pause, filter or redact recordings.
## Installation
Install the CLI session replay package for Node.js:
```bash theme={null}
npm install @statsig/js-client @statsig/cli-session-replay-node
```
```bash theme={null}
yarn add @statsig/js-client @statsig/cli-session-replay-node
```
```bash theme={null}
pnpm add @statsig/js-client @statsig/cli-session-replay-node
```
## Basic Usage
```javascript theme={null}
import { StatsigClient } from '@statsig/js-client';
import { StatsigCliSessionReplayPlugin } from '@statsig/cli-session-replay-node';
const client = new StatsigClient(
'your-client-key',
{ userID: 'user-123' },
{
loggingEnabled: 'always', // Required for CLI environments
plugins: [new StatsigCliSessionReplayPlugin()],
}
);
// Recording starts here
console.log('Hello from CLI!');
await client.initializeAsync();
// Your CLI application logic here
console.log('Continue');
```
**CLI Logging Requirement**: CLI applications must set `loggingEnabled: 'always'` when initializing the StatsigClient. By default, Statsig only enables logging in browser environments, but CLI session replay requires logging to be enabled in all environments to capture and send session data.
## Configuration Options
The `StatsigCliSessionReplayPlugin` accepts optional configuration:
```javascript theme={null}
import { StatsigCliSessionReplayPlugin } from '@statsig/cli-session-replay-node';
const plugin = new StatsigCliSessionReplayPlugin({
// Override the start timestamp (in milliseconds)
startTimestamp: Date.now(),
// Custom Asciicast header properties
asciicastHeader: {
title: 'My CLI App Session',
command: 'my-cli-tool --verbose',
env: {
TERM: 'xterm-256color',
SHELL: '/bin/bash'
},
}
});
```
### Configuration Properties
* **`startTimestamp`** (optional): Override the recording start time in milliseconds. Defaults to `Date.now()`.
* **`asciicastHeader`** (optional): Custom properties for the Asciicast header. For detailed information, visit the [Asciicast v2 File Format page](https://docs.asciinema.org/manual/asciicast/v2/#header). Common fields include:
* `title`: Human-readable title for the recording
* `command`: The command that was executed
* `env`: Environment variables relevant to the session
* `theme`: Terminal color theme object.
## Recording Limits
* **Duration**: Sessions automatically end after 4 hours
* **Size**: Recording stops if the session data exceeds 1MB
## Viewing Recordings
CLI session recordings appear in the Statsig Console alongside web session replays. The recordings can be played back to see exactly what happened in the terminal, including:
* All terminal output
* Terminal resize events
* Timing information for each interaction
* Session metadata and environment details
## Manual Recording Control
You can access the recording instance for manual control:
```javascript theme={null}
import { CliRecording } from '@statsig/cli-session-replay-node';
// Check if currently recording
if (CliRecording.isRecording()) {
console.log('Session is being recorded');
}
// Get current recording instance
const recording = CliRecording.currentRecording;
// Manually finish recording
CliRecording.finish();
```
## Platform Support
CLI Session Replay is currently supported on:
* Node.js applications
* Linux, macOS, and Windows terminals
* Any terminal that supports standard input/output streams
# Configure Statsig Session Replay
Source: https://docs.statsig.com/session-replay/configure
Configure Statsig Session Replay sampling rates, privacy masking rules, network capture settings, and event triggers across your applications.
## Conditional Recording
In the Statsig Console, you can configure your Session Replay settings under **Project Settings → Analytics & Session Replay**. You must be a project admin to modify these settings.
### Global Targeting Gate
The Global Targeting Gate controls who is *eligible* for session recording. If a user does not pass this gate, their sessions will never be recorded. By default, this is set to Everyone, meaning there are no restrictions—anyone can be recorded. You can think of this as defining the "top of the funnel" for session recording eligibility.
### Global Sampling Rate
The Global Sampling Rate determines what percentage of eligible sessions are recorded from the start. By default, this is set to **100%**, meaning all eligible sessions are recorded automatically. You can lower this if you want to limit session recordings but still ensure a consistent percentage of sessions are always captured. This rate applies only to sessions that begin at the start and does not affect conditional triggers.
### Conditional Triggers: Events and Exposures
Conditional triggers can start a session recording mid-session, even if it wasn’t recorded from the beginning. These triggers respect the Global Targeting Gate but operate independently of the Global Sampling Rate. When triggered, the recording includes the last 30 seconds leading up to the event (if rolling window is enabled).
Types of conditional triggers:
* **Individual Gate Exposures** — Trigger based on exposure to a specific gate, optionally filtered by group (e.g., Pass/Fail).
* **All Gate Exposures** — Trigger based on exposure to any gate, optionally filtered by group (e.g., Pass/Fail). Individual Gate Exposure triggers override All Gate configuration
* **Individual Experiment Exposures** — Trigger based on exposure to a specific experiment, optionally filtered by group (e.g., Test/Control).
* **All Experiment Exposures** — Trigger based on exposure to any experiment, filtered by groups Test/Control. No other group names are supported, if an experiment includes additional groups, individual triggers must be configured for each one. Individual Experiment Exposure triggers override All Experiment configuration
* **Events** — Trigger based on specific logged event, optionally filtered by event values (e.g., "purchase\_event" with value "book").
For each trigger, you can define an individual sampling rate. This rate is evaluated based on session\_id, meaning the result (pass or fail) will remain consistent for the same session, even if the trigger occurs multiple times.
**All Gates** and **All Experiments** conditional triggers are only available in `3.30.1` or higher
Important: If a conditional trigger occurs while a session recording is already in progress, the recording simply continues uninterrupted.
A trigger's sampling rate is consistent for the entire session based on
session\_id. So if `purchase_event` fails the sampling rate once, future
occurrences of the same event in that session will also fail.
### Initialization - StatsigTriggeredSessionReplay
```jsx theme={null}
import { StatsigClient } from "@statsig/js-client";
import { runStatsigTriggeredSessionReplay } from "@statsig/session-replay";
import { runStatsigAutoCapture } from "@statsig/web-analytics";
const client = new StatsigClient(
sdkKey,
{ userID: "some_user_id" },
{ environment: { tier: "production" } } // optional, pass options here if needed
);
runStatsigTriggeredSessionReplay(client, {
autoStartRecording: true,
keepRollingWindow: true,
});
runStatsigAutoCapture(client);
await client.initializeAsync();
```
```jsx theme={null}
import { StatsigProvider, useClientAsyncInit } from "@statsig/react-bindings";
import { StatsigTriggeredSessionReplayPlugin } from "@statsig/session-replay";
import { StatsigAutoCapturePlugin } from "@statsig/web-analytics";
function App() {
return (
Loading...}
options={{
plugins: [
new StatsigTriggeredSessionReplayPlugin({
autoStartRecording: true,
keepRollingWindow: true,
}),
new StatsigAutoCapturePlugin(),
],
}}
>
);
}
```
#### Initialization Options
* `autoStartRecording`
* `true`: Recording *can* start automatically after initialization. Global targeting gate and sample rate are respected
* `false`: You *must* manually start recording using startRecording(). This is helpful if you want to start the recording after a set point and block any auto-recording before then
* `keepRollingWindow`
* `true`: Statsig maintains a local rolling window of the last 30 seconds of the session, allowing recordings to include context leading up to a trigger.
* `false`: If a conditional trigger occurs, recording begins from that moment onward, with no historical context.
If you are utilizing bootstrapping, reach out to the Statsig team to confirm
your server sdk is supported for conditional recording
## Advanced: Forcing a Recording on Demand
You may have a use case where you want to manually start a recording. To do this, we offer the startRecording API which will begin recording as soon as you call it.
* `startRecording`: Respects both the Global Targeting Gate and Global Sampling Rate. This is useful if you still want to start your recordings after a certain point (e.g. after login) but still take advantage of the Global Sampling Rate
* `forceStartRecording`: Respects the Global Targeting Gate but is not subject to the Global Sampling Rate. Useful for debugging or when you don't want to be subjected to the Global Sampling Rate
* `stopRecording`: Stops the current recording, if one is in progress. Calling this method when no recording is active has no adverse effects. After stopRecording is called, conditional recording triggers will **not** automatically restart the recording. Only an explicit call to `startRecording` or `forceStartRecording` will resume recording.
If you have access to your Session Replay client, you can call these functions directly on the client instance.
```
const sessionReplayClient = new SessionReplay(client);
…
if (someCondition) {
sessionReplayClient.startRecording();
}
```
If not, you can import the function from `@Statsig/session-replay` and call it using your SDK key
```
import { startRecording } from '@Statsig/session-replay';
…
startRecording(CLIENT_SDK_KEY)
```
## Additional Options
These are options offered by the rrweb recorder (the open source recording tool we use)
| key | default | description |
| ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| blockClass | 'rr-block' | Use a string or RegExp to configure which elements should be blocked |
| blockSelector | null | Use a string to configure which selector should be blocked |
| ignoreClass | 'rr-ignore' | Use a string or RegExp to configure which elements should be ignored |
| ignoreSelector | null | Use a string to configure which selector should be ignored |
| ignoreCSSAttributes | null | array of CSS attributes that should be ignored |
| maskTextClass | 'rr-mask' | Use a string or RegExp to configure which elements should be masked |
| maskTextSelector | null | Use a string to configure which selector should be masked |
| maskAllInputs | false | mask all input content as \* |
| maskInputOptions | `{ password: true }` | mask some kinds of input \*
```jsx theme={null}
runStatsigSessionReplay(client, {
inlineStylesheet: false,
});
```
```jsx theme={null}
...
options={{
plugins: [
new StatsigSessionReplayPlugin({
inlineStylesheet: false,
}),
],
}}
...
```
2. **Exclude Large Static Elements**\
If certain elements on your page are large but static (e.g., background images or videos), you can exclude them from session capture by adding the `rr-block` class to their `className`. This prevents those elements from being recorded and can significantly reduce session size.
3. **Reach Out for Assistance**\
If you continue to experience large sessions, feel free to reach out in [Slack Community](https://statsig.com/slack). A Statsig team member can review your session and provide tailored recommendations for your setup.
# Install Statsig Session Replay
Source: https://docs.statsig.com/session-replay/install
Install Statsig Session Replay by adding the plugin to your JavaScript or React client SDK and configuring sampling, privacy, and capture options.
Session Replay is supported on the Javascript or React SDKs for both desktop and mobile web users on your web application. See the instructions below to install our SDK and record user sessions.
## Option 1 - No code - Add Javascript Snippet to your website
```html theme={null}
```
Get YOUR\_CLIENT\_KEY from Project Settings -> Keys & Environments. Reveal the Client API Key, copy, and paste it over the \[YOUR-API-KEY] in the snippet above.
And you're done! This will auto initialize the sdk and start recording sessions, no code required.
If you'd like to use your existing Statsig integration, or customize the integration further, see option 2 below. If you still want to use the script tag but also customize the integration, remove your key from the script url and initialize using the javascript code below.
## Option 2 - Custom code - Install via Package Manager
```bash npm theme={null}
npm install @statsig/js-client @statsig/session-replay @statsig/web-analytics
```
```bash yarn theme={null}
yarn add @statsig/js-client @statsig/session-replay @statsig/web-analytics
```
```bash npm theme={null}
npm install @statsig/session-replay @statsig/web-analytics @statsig/react-bindings
```
```bash yarn theme={null}
yarn add @statsig/session-replay @statsig/web-analytics @statsig/react-bindings
```
We recommend using autocapture as a great way to get started, but if you don’t want to automatically log and send events, you can remove the runStatsigAutoCapture option from the Javascript snippet or skip the `@statsig/web-analytics` package installation.
Next, following the [instructions for the Statsig Javascript SDK](/client/javascript-sdk), initialize Statsig with your SDK key, [user](/concepts/user) and options:
```jsx theme={null}
import { StatsigClient } from "@statsig/js-client";
import { runStatsigSessionReplay } from "@statsig/session-replay";
import { runStatsigAutoCapture } from "@statsig/web-analytics";
const client = new StatsigClient(
sdkKey,
{ userID: "some_user_id" },
{ environment: { tier: "production" } } // optional, pass options here if needed
);
runStatsigSessionReplay(client);
runStatsigAutoCapture(client);
await client.initializeAsync();
```
```jsx theme={null}
import { StatsigProvider, useClientAsyncInit } from "@statsig/react-bindings";
import { StatsigSessionReplayPlugin } from "@statsig/session-replay";
import { StatsigAutoCapturePlugin } from "@statsig/web-analytics";
function App() {
return (
Loading...}
options={{
plugins: [
new StatsigSessionReplayPlugin(),
new StatsigAutoCapturePlugin(),
],
}}
>
);
}
```
If you'd like to use Conditional Triggers you must use StatsigTriggeredSessionReplay. See Configure (Next page) for more information
That's it! Continue reading Configure to learn more about controlling who, what, and when you record sessions.
# Session Replay Overview
Source: https://docs.statsig.com/session-replay/overview
Overview of Statsig Session Replay for capturing and replaying real user sessions to debug bugs, study UX, and investigate experiment anomalies.
Session Replay allows you to record users using your website or product, and play back those recorded sessions. This allows you to better understand how users use your service or website, diagnose problems, and uncover insights that help improve conversion and the overall user experience.
A session recording plays back like a video in the Statsig Console, but is actually a serialized representation of your website and all of the events and interactions that occurred while the user was interacting with it. The recordings are captured using the [rrweb open source recording library](https://github.com/rrweb-io/rrweb). Recordings using this strategy are performant and space efficient, with options to apply user privacy filters to what is happening on screen.
I will be part of the black placeholder
I will be part of the black placeholder
```
```js theme={null}
// The closest rule will apply
Masked Text
Unmasked Text
```
```js theme={null}
// With conflicting rules applied at the same level,
// the higher precedence will apply
Masked Text
```
```js theme={null}
// With baseline privacy setting set to Maximum, all text is masked
// by default but this can be overwritten by unmasking
Masked Text
Unmasked Text
```
All selectors must be valid CSS selectors. For details on supported selector syntax, see MDN’s list of CSS selectors
Using selector rules or baseline privacy settings besides Passwords, will
cause `maskTextFn`, `maskInputFn`, `maskTextSelector`, `maskAllInputs`,
`maskInputOptions`, and `blockSelector` options passed in during
initialization to be overwritten
### Global Targeting Gate
The Global Targeting Gate controls who is *eligible* for session recording. If a user does not pass this gate, their sessions will never be recorded. By default, this is set to Everyone, meaning there are no restrictions—anyone can be recorded. You can think of this as defining the "top of the funnel" for session recording eligibility.
If you are utilizing bootstrapping, reach out to the Statsig team to confirm
your server sdk is supported
# Watch Session Replays
Source: https://docs.statsig.com/session-replay/watch
Watch and explore captured sessions in Statsig Session Replay, including event timelines, network activity, console logs, and gate exposures.
Session Replays can be found under the User’s group in the Statsig console’s navigation panel.
` | Deduplicated and stitched (for experiments with ID resolution) first exposure events | Useful for ad-hoc analysis |
| `exposures_summary_` | Timeseries of exposures per group for display in Pulse | |
| `unit_day_metrics_` | User-day level metric aggregations table | Useful for ad-hoc analysis |
| `unit_covariate_metrics_` | User-level pre-experiment aggregations for regression adjustment/CUPED | |
| `funnel_events_` | Staging table for running funnel analysis | |
| `percentile_values_` | Staging table for running percentile analysis | |
| `distinct_values_` | Staging table for running count distinct analysis | |
| `windowed_metrics_` | Staging table for generating running totals when restating Pulse | |
| `ratio_aggregations_` | Staging table for generating running totals when restating Pulse | |
| `results__` | Outputs of Statistical Analysis for different rollups (e.g. daily, days-since-exposure, cumulative, 7-day). Exported to Statsig | Pulse inputs - useful for replicating Statistical analysis |
| `ratio_results__` | Outputs of Statistical Analysis for ratio metrics in different rollups (e.g. daily, days-since-exposure, cumulative, 7-day). Exported to Statsig | Pulse inputs - useful for replicating Statistical analysis |
The high level relationships/contents of these tables are represented below - refer to the Main Steps image below for scheduling details.
This timing behavior only affects precomputed user dimensions. User-triggered dimensional analysis does not experience this delay.
# Entity Properties
Source: https://docs.statsig.com/statsig-warehouse-native/configuration/entity-properties
Use Entity Properties in Statsig Warehouse Native to attach categorical attributes to experiment units for filtering and grouping results in Explore.
You can either provide additional detail about an entity that doesn't typically change (e.g. a user's home country), or a property that may change as part of an experiment (e.g. Subscriber Status : True/False). For the latter, you provide a timestamp field which will be used to identify most recent value prior to the user's exposure. This prevents imbalanced groups and biased results from when an experimental treatment impacts the property, for example if it increased the subscription rate.
FROM
WHERE AND ((weight_lb)/pow(height_inches, 2) > 25)
```
## Settings
Each metric type's page has specific information on settings relevant to that metric. This section is a brief introduction to common settings on metrics.
### Breakdowns
Most aggregation-type metrics (sum, count, count distinct, unit count, means, ratios, percentiles, first/latest, min, max) allow you to generate a breakdown view of any column automatically. You can specify this column in the metric set up, and you will be able to click into the experiment result to see the breakdown.
### Cohorts
Cohort settings allow you to specify a window for data collection after a unit's exposure. For example, a 4-6 day cohort window would only count actions from days 4, 5, and 6 after a unit was exposed to an experiment.
Please refer to the full documentation on cohorts [here](/statsig-warehouse-native/features/cohort-metrics).
### Baking
Many metric types support baking. Statsig will wait to calculate baked metrics, and use "old" data for baked metrics. This is appropriate for cases like credit card chargebacks, where you may adjust your payments dataset to account for chargebacks in a "net revenue" metric. See additional information in the [cohort documentation](/statsig-warehouse-native/features/cohort-metrics).
Statsig will:
* Not calculate baked metrics until the bake period has elapsed since the user's enrollment
* On a given load, Statsig will pull historical data that "just baked" as of that day
* Calculate will only calculate results for users whose bake window has elapsed to avoid diluting metrics
This way incomplete data is not shown in pulse (either incomplete in the warehouse, or incomplete because of the late-landing data)
### Thresholding
Thresholding functionally converts a sum, count, count-distinct, max/min, or first/latest metric into a 1/0 unit metric by converting the user's total value to a specified threshold. For example, you might want to measure the count of users who spent at least \$100 in their first week on the platform. You'd specify this as a 0-6 day cohort metric, summing revenue, with a threshold of \$100.
### CUPED
You can enable/disable CUPED per metric, and also specify the lookback window for which users' pre-exposure data will be pulled and used as an input to the CUPED regression.
### Winsorization
See [winsorization](/stats-engine/methodologies/winsorization). Winsorization is applicable to aggregate metrics and allows you to specify an upper/lower, percentile-based threshold which data above/below will be clamped to. This reduces the incidence of inflated variance or skewed means from outlier data or buggy logging.
### Capping
Capping is an alternate outlier-control method that allows specifying a unit-day cap (specifiable per unit type) that values will be clamped to. For example, you might clamp "total purchase count" to 100 to avoid resellers skewing your metrics on an auction platform, if 100 is a reasonable upper bound for typical users.
# Qualifying Events
Source: https://docs.statsig.com/statsig-warehouse-native/configuration/qualifying-events
Use qualifying events in Statsig Warehouse Native to filter experiment exposures and metric calculations to specific user actions or eligibility windows.
## Using Qualifying Events
Qualifying events are used to simulate exposures for power analysis, and to filter exposures to users who triggered a specific event. Setting up a Qualifying Event is identical to setting up an Assignment Source, except they do not require experimental information.
Please note that the qualifying event must occur after the exposure as indicated by their respective timestamps.
Context columns can be used to filter the qualifying event for power analysis - for example you might have a Qualifying Event for page load, and filter to different page identifiers for power analyses of experiments on different surfaces.
## Filter by Qualifying Events
Statsig has best-in-class controls around using qualifying events to filter exposures in an experiment in cases of over-exposure.
With an IAM Role, Statsig will assume your created IAM Role via a Statsig Service Account. The Statsig Account ID for this service account is provided in your Data Connection settings in the Statsig Console. Statsig will run queries directly on behalf of this IAM Role.
Optionally, you can add an External ID condition for added security ([AWS External ID Docs](https://aws.amazon.com/blogs/security/how-to-use-external-id-when-granting-access-to-your-aws-resources/)). This External ID will be generated by Statsig, and viewable in your Data Connection settings in the Statsig Console.
* In your AWS IAM Dashboard, select the Roles page under the Access Management tab
* Click 'Create role'
* Choose 'AWS account' as the Trusted entity type
* Choose 'Another AWS account' from the options, and copy the Statsig Account ID from your Statsig console
* Optionally, require use of an External ID for connections to this role (also specified in your Statsig console)
* Continue to next step of setup, and select your IAM Permissions Policy from earlier
* Name, review, and create; your Trust Policy JSON should follow the format below:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"AWS": "__STATSIG_ACCOUNT_ID__"
},
"Condition": {
"StringEquals": {
"sts:ExternalId": "__ROLE_EXTERNAL_ID__"
}
}
}
]
}
```
* Add the ARN for this IAM Role to your Data Connection settings in the Statsig Console
With an IAM User, Statsig will use AWS Access Keys to gain access to this IAM User. Statsig will run queries directly on behalf of this IAM User.
* In your AWS IAM Dashboard, select the Users page under the Access Management tab
* Click 'Create user'
* Name your user
* On the next step of setup, choose 'Attach policies directly' and select your newly created Permissions Policy
* Under the Security Credentials tab of this newly created User, find the Access Keys block
* Click 'Create access key', and choose 'Third-party service' from the Use Case options
* Add the Access Key and Secret Access Key to your Data Connection settings in the Statsig Console
## Setup Reading Data from your Events/Exposures Tables
1. Give Statsig read-access to your Glue Database containing any tables you need to Statsig to read from. Do this by adding the following to your AWS IAM Permissions Policy:
```
{
"Effect": "Allow",
"Action": [
"glue:GetTable",
"glue:GetTables",
"glue:GetDatabase",
"glue:GetDatabases",
"glue:GetPartition",
"glue:GetPartitions"
],
"Resource": [
"arn:aws:glue:__REGION__:__YOUR_AWS_ACCOUNT_ID__:database/__YOUR_READONLY_DATABASE__",
"arn:aws:glue:__REGION__:__YOUR_AWS_ACCOUNT_ID__:table/__YOUR_READONLY_DATABASE__/*"
]
}
```
2. Give Statsig read-access to your S3 Bucket locations of the tables you need Statsig to read from. Add this to your AWS IAM Permissions Policy:
```
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::__PATH_TO_YOUR_READONLY_DATA__/*"
}
```
3. Read data in Statsig when setting up Metric/Assignment Sources by selecting from these tables using `"database"."table"` format.
4. Repeat for any additional tables, or whenever you need to read a new table from Statsig.
If your data warehouse is IP protected, you must include allowlisting of Statsig IP ranges in your setup steps.
## Additional Athena Resources
### S3 Bucket Encryption Guide
Statsig supports all accessed S3 Buckets being encrypted. Steps to allow Statsig encrypting S3 Buckets while giving Statsig access are as follows:
1. From the AWS Key Management Service console, create a new KMS Key using the below cryptographic configuration settings: ([AWS SSE KMS Docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html?icmpid=docs_s3_hp_batch_ops_create_job_encryption_key_type))
* Key Type: Symmetric
* Key Usage: Encrypt and Decrypt
* Advanced Options
* Key Material Origin = KMS
* Regionality = Single-Region Key
2. From the Key Policy tab of your newly created KMS Key, find the Key Administrators box. Click Add, and select the AWS IAM Role/User provided to Statsig as an administrator.
3. Navigate to your S3 Bucket. From your S3 Bucket Properties tab, find the Default Encryption box. Click Edit, and select the below default encryption settings:
* Encryption Type: SSE-KMS
* AWS KMS Key: Enter AWS KMS Key ARN
* (enter your newly created KMS Key ARN in the box)
* Bucket Key: Enable
### Statsig Staging Architecture Details
Statsig will create all of its staging tables within the Glue Staging Database that you create and provide. All of the tables created from Statsig will be of table-type `ICEBERG` (with the exception of the forwarded exposures/events tables, which will be regular `EXTERNAL` Athena tables).
Statsig stores all staging data within the `Statsig S3 Folder` of your S3 Bucket. Statsig will handle the creation of the structure within this subfolder. The folder structure is as follows:
* S3 Bucket (you create and provide Statsig the name)
* Statsig S3 Folder (Statsig creates and names, name provided in the Data Connection settings in your Statsig Console)
* Experiment Folder(s) (Statsig will create a subfolder for each unique experiment you run. These will be named `experiment-`)
* Staging Tables Folders (Statsig will put data for each created staging table in its own subfolder. These will be named intuitively after the data they contain)
* `metadata/`
* Iceberg Table Metadata
* `data/`
* Table Data Files (stored as Parquet)
* `statsig_forwarded_exposures/`
* Forwarded Exposures Table Subfolder (named in the Data Connection settings in your Statsig Console)
* Dates in `YYYY-MM-DD` format (This table is partitioned by date, and there will be a subfolder for each date that has exposure data sent through Statsig)
* Forwarded Exposure Data
* `statsig_forwarded_events/`
* Forwarded Events Table Subfolder (named in the Data Connection settings in your Statsig Console)
* Dates in `YYYY-MM-DD` format
* Forwarded Event Data
### What IP addresses will Statsig access data warehouses from?
[See FAQ](/data-warehouse-ingestion/faq#what-ip-addresses-will-statsig-access-data-warehouses-from)
# Bigquery Connection
Source: https://docs.statsig.com/statsig-warehouse-native/connecting-your-warehouse/bigquery
Connect Google BigQuery to Statsig Warehouse Native, including service account setup, dataset permissions, and required IAM roles.
## Overview
To set up a connection with BigQuery, there are two supported methods:
* Grant Permissions to a Statsig-owned Service Account
* Provide Credentials for Your Own First-Party Service Account
In both cases, you'll need:
* Your BigQuery Project ID
* The dataset Statsig will use to save temporary tables and materialized results
Once you’ve chosen your method, start by enabling the BigQuery source in your project settings.
## Grant Permissions to Statsig's Service Account
You need to grant some permissions for Statsig from your Google Cloud console in order for us to access your BigQuery data.
1. In your BigQuery's [IAM & Admin settings](https://console.cloud.google.com/iam-admin/), add the Statsig service account you copied in the Statsig Console as a new principal for your project, and give it the following roles:
* `BigQuery User`
If your data warehouse is IP protected, you must include allowlisting of Statsig IP ranges in your setup steps.
Now the service account should have the required permissions to run queries and materialize results.
## Using a First Party Service Account
This is not a recommended alternative. Using service accounts is the [preferred default for enhanced security](https://docs.cloud.google.com/iam/docs/migrate-from-service-account-keys).
1. On the BQ service accounts page, click 'Manage Keys' for the service account you want to use
If your data warehouse is IP protected, you must include allowlisting of Statsig IP ranges in your setup steps.
### What is Statsig's Customer ID on BigQuery
C01d5f80s
### What IP addresses will Statsig access data warehouses from?
[See FAQ](/data-warehouse-ingestion/faq#what-ip-addresses-will-statsig-access-data-warehouses-from)
### Additional Setup for Warehouse Explorer
Warehouse Explorer makes it easy to find and bring data from any table into Statsig for ad-hoc analysis.
Statsig will read from `INFORMATION_SCHEMA.COLUMNS`, which requires explicit permission to view table metadata. You may provide access by repeating steps 1 and 2 from the [Grant Permission](/statsig-warehouse-native/connecting-your-warehouse/bigquery#grant-permissions-to-statsig%E2%80%99s-service-account) section above for the "BigQuery Metadata Viewer" role.
# Databricks Connection
Source: https://docs.statsig.com/statsig-warehouse-native/connecting-your-warehouse/databricks
Connect Databricks to Statsig Warehouse Native, including service principal setup, SQL warehouse selection, and required Unity Catalog permissions.
## Overview
To set up a connection with Databricks, you will need the following:
* Your Databricks Server Hostname
* An HTTP Path to a Cluster or SQL Warehouse
* A staging database for writing results and intermediate tables into
* An access token with read access on your experiment data and write access to the staging database
* Use either Serverless SQL Warehouse or an always-on cluster. Statsig uses interactive queries during setup (and some analysis) which will fail if the cluster takes several minutes to start up.
Start by enabling the Databricks source in your project settings.
## Note on Databricks Access
For users who use databricks and a dbfs-based deltalake as their primary warehouse, permissions are managed easily for databricks. For customers using databricks as an intermediary to other data sources, you need to make sure that databricks and the Statsig user through databricks has appropriate access to your storage (e.g. S3 for athena tables). Often, permissions are reset at some point which will start to cause errors; to validate this, try creating tables through the Statsig console to verify that the permissions on Statsig's side are sufficient.
## Getting Connection Information
1. Follow the [Databricks documentation](https://docs.databricks.com/integrations/jdbc-odbc-bi.html#get-connection-details-for-a-cluster) to get the hostname and http path of the cluster you'll use to run your experimental analysis. You may want to create a specific cluster for this use case.
'
spark.sql(f"CREATE DATABASE IF NOT EXISTS {staging_database_name}")
```
If your data warehouse is IP protected, you must include allowlisting of Statsig IP ranges in your setup steps.
### What IP addresses will Statsig access data warehouses from?
[See FAQ](/data-warehouse-ingestion/faq#what-ip-addresses-will-statsig-access-data-warehouses-from)
### Additional Setup for Warehouse Explorer
Warehouse Explorer makes it easy to find and bring data from any table into Statsig for ad-hoc analysis.
When Unity Catalog is enabled, Statsig will read from `.information_schema.columns`. You can provide the catalog name in Data Connection settings, under the Advanced section.
Also, you may need to provide read access to the catalog and the `information_schema` schema:
```sql theme={null}
GRANT USE CATALOG ON CATALOG TO ;
GRANT USE SCHEMA ON SCHEMA .information_schema TO ;
```
`` should be the user associated with the access token you have provided to Statsig above.
# Forwarded Data
Source: https://docs.statsig.com/statsig-warehouse-native/connecting-your-warehouse/forwarded-data
Use forwarded data in Statsig Warehouse Native to send events to Statsig and store them in your warehouse for experiment and analytics use.
If you log events or exposures to Statsig's SDK, Statsig will put that data back in your warehouse in near-realtime, on-demand.
## Setting up tables for forwarded data
By default, when setting up a data connection to your warehouse, we'll automatically create tables 'exposures' and 'events' where we'll forward SDK data to.
If you want to change the name of the table that are used for forwarded data, in the data connection page under the 'advanced' tab and you'll find the option to change the name of said tables.
If you've already had data exported and change the table name, future data will be written to the new table.
Non-production exposures or log events are not forwarded to external warehouses
## Exposures
Logging exposures with Statsig means you'll get real-time diagnostics on the Statsig console, as well as real-time aggregations like exposures by hour.
When you run Pulse analysis, raw exposures for the experiment you're loading will be fast-forwarded to catch up with the real-time stream. This means you'll get all of the users in your experiment and see Pulse results as fresh as \~15m (assuming events and metrics come in at the same speed).
Under the covers, we perform a just-in-time update of exposures in your warehouse when Pulse is loaded, for the first 1 million exposures that are logged to the experiment. After that, the exposures are batched, deduplicated and written to your warehouse once a day.
These fast-forwarded exposures are not deduplicated, and will have some fields (`user_dimensions` in particular) missing. These fields will be provided in the subsequent daily load.
Each day, a deduplicated digest will be exported to your warehouse to ensure consistency. This will be deduplicated with the above as part of the standard Pulse Pipeline.
## Note on Duplicates
Because Statsig only holds onto exposure data for 30 days, it cannot dedupe beyond that time on its servers. This means that after 30 days, the "deduplicated" data from Statsig will start to re-send exposures from units who were first exposed over 30 days ago, and were re-exposed on that day. These will be correctly deduplicated during analysis in your warehouse, but it means that you should not expect the table to have unique user records, even after filtering out the fast-forwarded exposures (which can also have duplicate records).
For gates with 0% or 100% rollout, by default we don't forward exposure to your warehouse. If you need them, please contact our support team, your sales contact, or via our [Slack community](https://statsig.com/slack).
## Events
If you're using our SDKs to capture custom events, we'll export these events to your warehouse hourly. You can see Pulse results on metrics derived from those events as fresh as \~1hour.
# Other Warehouses
Source: https://docs.statsig.com/statsig-warehouse-native/connecting-your-warehouse/other
Connect other data warehouses to Statsig Warehouse Native using forwarded data, custom integrations, or supported community connectors.
## Other Warehouses
Statsig's architecture is set up to add new warehouses relatively easily. We are selective with which warehouses we choose to support long-term, but generally we will be happy to discuss your needs and consider building a solution that works for you on your cloud provider.
In general, Statsig will access your warehouse through API calls and will need corresponding information on the address of your cluster and authentication information; very similar to running queries through datagrip, python, or other services.
## Permissions
Statsig will require read permissions on any input tables for your analysis. Statsig also requires full CRUD (create/read/update/delete) permissions on a "sandbox" where staging data and other intermediate data artifacts will be stored as part of experimentation pipelines.
### What IP addresses will Statsig access data warehouses from?
If your data warehouse is IP protected, you must include allowlisting of Statsig IP ranges in your setup steps.
[See FAQ](/data-warehouse-ingestion/faq#what-ip-addresses-will-statsig-access-data-warehouses-from)
# Redshift Connection
Source: https://docs.statsig.com/statsig-warehouse-native/connecting-your-warehouse/redshift
Connect Amazon Redshift to Statsig Warehouse Native, including IAM roles, network access, user setup, and required schema permissions.
## Overview
To set up connection with Redshift, Statsig needs the following information
* Cluster Endpoint
* A service user Username
* A service user Password
* A staging schema that Statsig can write results to
SHA256 passwords are not currently supported, please utilize MD5 to avoid issues.
You can find this information in your aws console within your specific cluster, as shown in the image below. (Open image in new tab for a bigger image). The service user should be able to read necessary experiment data, and be able to write to the Statsig staging schema you specify.
The provided Service Account will require the following attributes:
`enable_case_sensitive_identifier`, `enable_case_sensitive_super_attribute`.
If these are not already set, Statsig will set them to TRUE upon setup completion.
## SSH Tunneling
For Redshift connections, we also allow users to create an SSH tunnel into their Redshift cluster for a more secure and private access to the database.
To enable access, Statsig requires:
* SSH Host
* SSH Port
* SSH User
Statsig will use this information to generate an SSH key. Please add this generated key to your `~/.ssh/authorized_keys` file on your SSH proxy machine to enable SSH tunneling.
### What IP addresses will Statsig access data warehouses from?
If your data warehouse is IP protected, you must include allowlisting of Statsig IP ranges in your setup steps.
[See FAQ](/data-warehouse-ingestion/faq#what-ip-addresses-will-statsig-access-data-warehouses-from)
### Additional Setup for Warehouse Explorer
Warehouse Explorer makes it easy to find and bring data from any table into Statsig for ad-hoc analysis.
To enable the Warehouse Explorer analytics feature, you may need to provide Statsig with additional permission to query the `pg_table_def` metadata. Only schemas that Statsig has read access to will be included in query results. A superuser or admin can grant access to read additional relevant schemas and table metadata in `pg_table_def` by running
```sql theme={null}
GRANT USAGE ON SCHEMA TO ;
GRANT SELECT ON ALL TABLES IN SCHEMA