Skip to main content

iOS SDK for Statsig

Statsig client side SDK for iOS applications. This SDK is open source and hosted on github, and usable in both Swift and Objective-C codebases.

Getting started#

Statsig is a singleton class which you can initialize with Statsig.start() function:

Statsig.start(sdkKey: "my_client_sdk_key", user: StatsigUser(userID: "my_user_id"))

You can also optionally use a completion block to wait for it to finish initializing:

Statsig.start(sdkKey: "my_client_sdk_key", user: StatsigUser(userID: "my_user_id")) { errorMessage in
// Statsig client is ready;
// You can also check errorMessage for any debugging information.

To check the value of a feature gate for the current user, use the checkGate() function. Note that if the gate_name provided does not exist, or if the device is offline, we will return false as the default value.

let showNewDesign = Statsig.checkGate("show_new_design")

To retrieve a Dynamic Config for the current user, use the getConfig() function:

let localizationConfig = Statsig.getConfig("localization_config")

which will return a DynamicConfig object that you can then call getValue() on to retrieve specific values within the Dynamic Config. The defaultValue will be returned when the user if offline or the key does not exist.

let buttonText = localizationConfig.getValue(forKey: "button_text", defaultValue: "Check out")

Sometimes the logged in user might switch to a different user, or you just received more information about the user and wish to update them, you can call the updateUser() function to notify Statsig so it can retrieve the correct values for the updated user:

let newUser = StatsigUser(userID: "new_user_id", email: "", country: "US")
Statsig.updateUser(newUser) { errorMessage in
// Statsig has fetched the values for the new user

You can also use the same optional completion block to be notified when Statsig is done fetching values for the new user, just like in start().


The StatsigUser class is what we use to help you with targeting. You can provide userID, email, ip, country, and even custom, which is a dictionary of String values for your own choices of targeting criteria. userID is highly recommended, and we will try to use device ID to identify the same user in the absence of a userID. You are also encouraged to provide as much custom info as you know about the user, all of which can be used by you in our console for feature gating and Dynamic Config's targeting.


Statsig.start() takes an optional 3rd parameter options in addition to sdkKey and user that you can provide to customize the Statsig client. Currently there are 3 options:

  1. initTimeout: double, default 3.0
    • 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.
  2. disableCurrentVCLogging: boolean, default false
    • 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.
  3. environment: StatsigEnvironment, default nil
    • 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.
  4. enableAutoValueUpdate: boolean, default false
    • by default, feature values for a user is fetched once during Statsig.start and don't change throughout the session. Setting this value to true will turn on the feature for Statsig to periodically fetch updated values for the current user.

Logging custom events#

The logEvent() API can be used to log custom events for your application, which will be shown in your Statsig dashboard and used for metrics calculation for A/B testing:

Statsig.logEvent(withName: "purchase", value: 2.99, metadata: ["item_name": "remove_ads"])

Shut down#

When your application is shutting down, call shutdown() so we can make sure any event logs are being sent for logging properly and all resources are released.