Client-side feature gating
Step 1: Get the Statsig client SDK key
To get the Statsig client SDK key,
-
Log into the Statsig console at https://console.statsig.com
-
Click on the Project Settings gear icon next to your account settings at the top right corner of the page as shown below
-
Click on the API Keys tab
-
Copy the active Client API Key
Step 2: Install the SDK
You can install the statsig SDK via npm or yarn:
- Javascript
- React
- React Native
- iOS
- Android
- .NET
Install using npm or yarn:
npm install statsig-js
yarn add statsig-js
You can also use jsdelivr, an open source CDN that we use on www.statsig.com. To access the current primary JavaScript bundle, include the following in your client application:
https://cdn.jsdelivr.net/npm/statsig-js/build/statsig-prod-web-sdk.min.js
To access specific versions and files, use the following format:
http://cdn.jsdelivr.net/npm/statsig-js@{version}/{file}
Install using npm or yarn:
npm install statsig-react
yarn add statsig-react
Install using npm or yarn:
npm install statsig-react-native
yarn add statsig-react-native
Add Statsig as a dependency through Swift Package Manager. In Xcode, select File > Swift Packages > Add Package Dependency and enter the URL:
https://github.com/statsig-io/ios-sdk.git
// Include Statsig as a dependency in your project's Package.swift:
//...
dependencies: [
.package(url: "https://github.com/statsig-io/ios-sdk.git", .upToNextMinor("1.3.0")),
],
//...
targets: [
.target(
name: "YOUR_TARGET",
dependencies: ["Statsig"]
)
],
//...
// If you are using CocoaPods, add the 'Statsig' pod
use_frameworks!
target 'TargetName' do
//...
pod 'Statsig', '~> 1.3.0' // Add this line
end
In build.gradle
include the Statsig dependency directly from the github source (via jitpack) as follows.
In your root build.gradle, at the end of repositories, add:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
Then, add the dependency:
implementation 'com.github.statsig-io:android-sdk:v2.0.0'
Finally, run a gradle sync so that the Intellij/Android Studio recognizes the Statsig library.
For more information on including a jitpack library as a dependency, see https://jitpack.io/
The Statsig package is hosted on Nuget. You can either install it from your Visual Studio's Nuget package manager, or through .NET CLI:
dotnet add package Statsig --version 1.1.0
Step 3: Initialize the SDK
To initialize the SDK, copy the following in your client application:
- Javascript
- React
- iOS - Swift
- iOS - Objective C
- Android - Java
- Android - Kotlin
- .NET
const statsig = require('statsig-js');
await statsig.initialize(
'<CLIENT_SDK_KEY>',
{ userID: '<LOGGED_IN_USER_ID>' },
{ environment: { tier: 'staging' } }, // optional, pass options here if needed
);
import { StatsigProvider } from 'statsig-react';
...
<StatsigProvider
sdkKey="<CLIENT_SDK_KEY>"
user={{
userID: <LOGGED_IN_USER_ID>,
email: session?.user?.email ?? undefined,
... // other user parameters
}}
waitForInitialization={true}>
<Component />
</StatsigProvider>
Statsig.start(
sdkKey: "<CLIENT_SDK_KEY>",
user: StatsigUser(userID: "<LOGGED_IN_USER_ID>"),
options: StatsigOptions(environment: StatsigEnvironment(tier: .Staging)))
{ errorMessage in
// Statsig client is ready; you can also check errorMessage for any debugging information.
}
StatsigUser *user = [[StatsigUser alloc] initWithUserID:@"<LOGGED_IN_USER_ID>"];
[Statsig startWithSDKKey:@"<CLIENT_SDK_KEY>", user:user, completion:^(NSString * errorMessage) {
// Statsig client is ready
// errorMessage can be used for debugging purposes. Statsig client still functions when errorMessage
// is present, e.g. when device is offline, either cached or default values will be returned by Statsig APIs.
}];
import com.statsig.androidsdk.*;
...
Application app = getApplication();
StatsigUser user = new StatsigUser("<LOGGED_IN_USER_ID>");
CompletableFuture future = Statsig.initializeAsync(app, "<CLIENT_SDK_KEY>", user);
future.thenApply(this::onStatsigReady);
...
private Object onStatsigReady(Object empty) {
// use your gates and feature configs now
}
import com.statsig.androidsdk.*
...
val callback = object : StatsigCallback {
override fun onStatsigReady() {
// check gates/configs and log events
}
}
Statsig.initialize(
this.application,
"<CLIENT_SDK_KEY>",
StatsigUser("<LOGGED_IN_USER_ID>"),
callback,
)
using Statsig;
using Statsig.Client;
await StatsigClient.Initialize(
"<CLIENT_SDK_KEY>",
new StatsigUser { UserID = "<LOGGED_IN_USER_ID>", Email = "user@email.com" },
new StatsigOptions(new StatsigEnvironment(EnvironmentTier.Development)) // optional, use when needed to customize certain behaviors
);
You must provide a user ID at a minimum to initialize the SDK. Statsig also provides built-in user attributes such as email, IP address, user agent, country, locale, and client version that you can also pass as part of a user object to create targeting rules based on any of these dimensions.
- Javascript
- React
- iOS
- Android
- .NET
const user = {
userID: <LOGGED_IN_USER_ID>,
ip: currentIP,
custom: {
new_user: true,
level: 2
}
};
await statsig.initialize('<CLIENT_SDK_KEY>', user);
import { StatsigProvider } from 'statsig-react';
...
<StatsigProvider
sdkKey="<CLIENT_SDK_KEY>"
user={{
userID: <LOGGED_IN_USER_ID>,
email: session?.user?.email ?? undefined,
... // other user parameters
}}
waitForInitialization={true}>
<Component />
</StatsigProvider>
Step 4: Check the feature gate
To implement a feature gate, you must include a feature gate check in your application code.
A feature gate check returns a Boolean value. A feature gate is closed/off and a gate check returns false by default. After you have created a rule to target a set of users, the feature gate check returns true when you perform a check for an eligible user. You can use this return value to expose the eligible user to the feature as shown below.
- Javascript
- React
- iOS - Swift
- iOS - Objective C
- Android - Java
- Android - Kotlin
- .NET
if (statsig.checkGate('<FEATURE_GATE_NAME>')) {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
import { useGate } from 'statsig-react';
...
export default function MyComponent(): JSX.Element {
// only call hooks at the top level of a functional component
const featureOn = useGate(<FEATURE_GATE_NAME>).value;
return {featureOn ? <MyComponent /> : null;
}
if Statsig.checkGate("<FEATURE_GATE_NAME>") {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
if ([Statsig checkGateForName:@"<FEATURE_GATE_NAME>"]) {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
if (Statsig.checkGate("<FEATURE_GATE_NAME>")) {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
if (Statsig.checkGate("<FEATURE_GATE_NAME>")) {
// Gate is on, show new home page
} else {
// Gate is off, show old home page
}
if (StatsigClient.CheckGate("<FEATURE_GATE_NAME>"))
{
// Gate is on, show new home page
}
else
{
// Gate is off, show old home page
}
Step 5 (Optional): Log an event
You can optionally log an event to capture any metrics that show the impact of your feature.
- Javascript
- React
- iOS - Swift
- iOS - Objective C
- Android - Java
- Android - Kotlin
- .NET
statsig.logEvent('<EVENT_NAME>', '<EVENT_VALUE>', {'price': '<KEY>', 'item_name': '<VALUE>'});
export default function MyComponent(): JSX.Element {
const statsig = useStatsig();
return
<Button
onClick={() => {
statsig.logEvent('<EVENT_NAME>');
}}
/>;
}
Statsig.logEvent(withName: "<EVENT_NAME>", value: "<EVENT_VALUE>", metadata: ["<KEY>": "<VALUE>"])
[Statsig logEvent:@"<EVENT_NAME>" doubleValue:<EVENT_VALUE> metadata:@{@"<KEY>" : @"<VALUE>"}];
Statsig.logEvent("<EVENT_NAME>", "<EVENT_VALUE>", Map.of("<KEY>", "<VALUE>"));
Statsig.logEvent("<EVENT_NAME>", "<EVENT_VALUE>", Map.of("<KEY>" to "<VALUE>"))
StatsigClient.LogEvent("<EVENT_NAME>", "<EVENT_VALUE>", new Dictionary<string, string>() { { "<KEY>", "<VALUE>" } });