Frequently Asked Questions

In the Statsig SDKs, there is no functionality to retrieve a user's historical gate pass status.

The SDKs are designed to evaluate the current state of a feature gate for a user at the time of the check, rather than providing historical data. As such, it is not possible to use the SDK to directly query if a user has passed a certain gate in their history.

To track a user's interactions with feature gates over time, it is recommended to log an event each time a user passes through a gate using the Statsig.logEvent function available in the SDKs. These logged events can then be analyzed within the Statsig console to gain insights into the user's history with the feature gates.

It is important to note that when checking a gate or logging an event, comprehensive user information should be provided to leverage the full capabilities of the Statsig platform.

Using multiple SDKs on a site is technically possible, but it can lead to complications. The Statsig JavaScript SDK and the React SDK are designed to be used independently. If you use both on the same site, they will each maintain their own state and won't share information.

This could lead to inconsistencies in feature gate evaluations and experiment assignments.

If your site is primarily in JavaScript but includes a React app, it's recommended to initialize Statsig with the JavaScript SDK and then pass the initialized Statsig object into the React app. This way, you ensure that both parts of your application are using the same Statsig state.

However, if your React app is substantial or complex, it might be more beneficial to use the React SDK for its additional features, like the StatsigProvider and React hooks. In this case, you should ensure that the JavaScript part of your application doesn't also initialize Statsig, to avoid the aforementioned issues.

The React SDK brings in the JS SDK as well, so you don’t need to include it separately. Once that is initialized then you can use the ‘statsig’ object directly.

However, you’ll have to be careful - the react SDK internally keeps track of the state of the user, so if you try to update the user outside the provider, your react component tree won’t rerender with updates. Similarly, if you try to call methods before the react SDK initializes the js sdk instance internally, you could run into issues.

The best approach depends on the specifics of your application and its usage of Statsig.

Statsig does not automatically capture any system events, including the app launch event. However, you have the ability to manually log custom events using the logEvent function provided by the SDK. This function allows you to track any event you deem relevant, including the launch of your app.

Here's an example of how to use it:

For Android:

kotlin Statsig.logEvent("app_launch")

For iOS:

swift Statsig.logEvent("app_launch")

Remember to call this function at the appropriate place in your code to track the app launch event.

The Statsig React.js SDK does not automatically capture app launch events. However, you can manually log custom events, including an app launch event, using the Statsig.logEvent() function.Here's an example of how you might do this:

javascript import { Statsig } from "statsig-react";   // Log an app launch event Statsig.logEvent("app_launch");

Please remember to initialize the SDK before logging events. For more detailed information or assistance, refer to the Statsig documentation.

If you are using the Native Android and ios SDKs of Statsig, you would still need to manually capture the app launch event using statsig.logEvent('app_launch').

The request body for feature gates in the React client SDK is obfuscated and encoded in a specific way that is intended to be processed on the server side by Statsig. This is a security measure implemented to protect the integrity of the data. As such, it is not designed to be decoded on the client side and there is no supported method for doing so.

If you need to inspect the values of your feature gates, it is recommended to do so through the Statsig console. This is the most reliable and secure method to access and manage your feature gates. Please refrain from attempting to decode the obfuscated content on the client side as it may compromise the security and integrity of your data.

When a vulnerability alert is triggered in Snyk for the Statsig Ruby SDK due to the MPL-2.0 license, it is important to understand the implications of the license and how it may affect your organization. The Mozilla Public License 2.0 (MPL-2.0) is a widely accepted open-source license that allows the code to be used in both open-source and proprietary projects.

Under MPL-2.0, if modifications are made to the original code, those changes must be disclosed when the software is distributed. However, the MPL-2.0 license permits the combination of the licensed code with proprietary code, which means that the SDK can be used in closed-source applications without requiring the entire application to be open-sourced.

It is important to note that while the MPL-2.0 license is generally compatible with other licenses, it may be flagged by security tools like Snyk because it requires review and understanding of its terms. Organizations should consult with their legal team or open-source compliance experts to ensure that the use of MPL-2.0 licensed software aligns with their policies and legal obligations.

If your organization has made no modifications to the original code, there should be no concerns regarding the need to disclose changes. Ultimately, the decision to use software under the MPL-2.0 license should be made by the decision-makers within the organization after careful consideration of the license terms and compliance requirements.

In scenarios where there is a need to check feature flags for entities rather than individual users within the Statsig SDK, a workaround can be implemented using dynamic configs.

Dynamic configs in Statsig allow for the evaluation of different values for different IDs, which can be used as a substitute for feature flags by substituting user-specific checks with entity-specific checks. While dynamic configs do not support pulse, they share a common definition and evaluation method with feature flags, returning a JSON value instead of a boolean at the end of the evaluation process.

This approach can be particularly useful when dealing with long-lived sessions or when there is a need to frequently update the cache to reflect the latest configurations.

It is important to note that implementing a new SDK to handle this use case would be a more substantial undertaking, and utilizing dynamic configs as described may provide a viable solution without the need for such an investment.

In order to implement StatSig tracking on Shopify Custom Pixels, you need to ensure that the StatSig SDK is properly initialized and that events are logged correctly. Here's a step-by-step guide on how to do this:

1. First, create a script element and set its source to the StatSig SDK. Append this script to the document head.

javascript const statsigScript = document.createElement('script'); statsigScript.setAttribute('src', 'https://cdn.jsdelivr.net/npm/statsig-js/build/statsig-prod-web-sdk.min.js'); document.head.appendChild(statsigScript);

2. Next, initialize the StatSig SDK. This should be done within an asynchronous function that is called when the StatSig script has loaded.

javascript const statsigInit = new Promise(async (resolve) => {    statsigScript.onload = async () => {      await statsig.initialize("client-sdk-key", { userID: "user-id" });      resolve();    } })

3. Subscribe to the event you want to track and log it with StatSig. Make sure to wait for the StatSig SDK to initialize before logging the event.

javascript analytics.subscribe("checkout_started", async () => {    await statsigInit;    statsig.logEvent("checkout_started"); });

Remember that statsig will be the global, you want to wait for initialization before logging, no need to require.Please note that the SDK accumulates events within, and flushes periodically. Ensure that Statsig.logEvent() was ever called, and that the application didn’t exit right away after that so the SDK has enough time to flush the events.

Inspect the network requests and see what requests were made and what their responses were to verify if the events are being sent correctly.

Integrating the Statsig SDK server-side in a Next.js application without a custom server or Vercel deployment can be achieved by utilizing the register API to initialize the SDK on server startup.

This method allows for the SDK to be set up before serving requests, ensuring that feature flags and configurations are available for server-side rendering. However, it is important to note that the register API may only trigger on the first request received by the server.

To ensure the SDK is initialized, a health check or similar request may be necessary to activate the register process.

Additionally, depending on the hosting solution for the Next.js app, writing a data adapter to read Statsig configurations from a cache could be a viable alternative. This approach would involve creating a custom adapter that interfaces with a caching mechanism to retrieve the necessary configurations for Statsig.

For more detailed guidance on implementing feature flags with Next.js, refer to the official Statsig documentation.

When setting up the Statsig SDK in an Electron/Vite(React) app, it's important to note that no user properties are required. You do not need to pass a userID or an email. If you are just getting the SDK setup and running, an empty object will suffice for now.

If you're using React in your application, the React SDK would be a good fit. However, if you're not using React, the JS SDK will be the best choice. Even if your application is running on Electron, using the React SDK should not pose any issues.

In case you encounter issues with the analytics onboarding page, such as a blank page or undefined keys, please report it to our support team. We strive to resolve such issues as quickly as possible.

In TypeScript React-Native, the get<T> method in the DynamicConfig typing class is used to retrieve a specific parameter from a Dynamic Config. Here's how to use it:

1. **Passing the Key**: The key you should pass in is the name of the parameter you want to retrieve from the Dynamic Config. This parameter is defined in the Statsig Console when you create or edit a Dynamic Config.

2. **Understanding the Return Value**: The get method will return the defaultValue you provide if the parameter name does not exist in the Dynamic Config object. This can happen if there's a typo in the parameter name, or if the client is offline and the value has not been cached. If you're always getting the defaultValue, it's likely that the parameter name doesn't match what's in the Dynamic Config, or the client hasn't successfully fetched the latest config values. Please double-check your parameter names and your network status. If the issue persists, it might be a good idea to log this issue for further debugging.

3. **Retrieving the Entire Object**: If you want to get the entire object, you can use the getValue() method. For example, if you call config.getValue(), you will get the entire object.

4. **Example Usage**: The argument passed into getConfig will be the dynamic config key itself which returns a config object that implements the get method. You pass a top-level object key into that get method. For instance, if the top level key is clothing, you would pass that into the get method accordingly, like so: statsig.getConfig('max_discount').get('clothing');

Remember, the get<T> method is designed to access individual properties of the dynamic config, not the entire object. For accessing the entire object, use the getValue() method.

At present, we do not provide a downloadable JSON version of our OpenAPI/Swagger documentation for the Console API. However, we appreciate your suggestion and have added it to our backlog for consideration. We will prioritize this feature request along with the rest. Please stay tuned for updates on this feature.

The statsig::app_error event is an automatic log created by the Statsig SDK when it encounters an uncaught exception on your webpage. This event is not necessarily related to your Statsig implementation, but rather, it is associated with any error on your webpage.

The statsig::app_error event can be particularly useful when you navigate to the Event Logstream and inspect the details. Depending on the nature of the error, the SDK may be able to capture the line and error message.

It's important to note that the occurrence of this event on iOS devices could be due to a specific condition or issue unique to the iOS environment. However, without more specific information, it's difficult to provide a definitive answer.

For further assistance with this issue, it is recommended to reach out to the Statsig team directly. They may be able to provide more insight into this specific event and why it's being triggered on iOS devices.

When integrating the Statsig Node.js SDK, developers often inquire about the initialization time required on the server. The initialization process involves a network request, and the time taken for this process can vary based on several factors.

A key consideration is the geographical distance between the server where the SDK is being initialized and Statsig's data centers. Typically, the server latency for handling initialize calls is in the range of 200 milliseconds to 1 second.

It is important to note that project size can influence initialization time, particularly when using large ID list based segments, which require downloading during the initialization phase. Without such segments, the aforementioned latency range is a reasonable expectation for initialization time.

The waitForInitialization option in Statsig's React SDK is used to delay the rendering of your components until the SDK has finished initializing. This ensures that the correct feature gate values are available when your components are rendered. If you're seeing users in the "uninitialized" group, it could mean that the SDK initialization is not yet complete when the feature gate check is being made. This could be due to a slow network connection or other issues that delay the initialization process.

To resolve this, you could consider increasing the initTimeoutMS value, which gives the SDK more time to complete the network roundtrip before falling back to cached values. You could also use the init callback for debugging to check when it's returning. If the issue persists, it might be worth considering using a server SDK on one of your servers to bootstrap with. This way, if you already have a network request serving stuff to your clients, you can have it evaluate the user and pass those values back without needing a roundtrip to the SDK.

Remember, the initCalled: true value doesn't necessarily mean the initialization succeeded. It's important to check for any errors thrown from the initialization method. If you're trying to avoid unnecessary updateUser calls, consider building a statsigUser and only call for update if the local statsigUser is different from the one saved in the SDK instance.

If you set waitForInitialization off, you should get the uninitialized check, and then once SDK initialization completes (within 3 seconds), you should get another check with the actual value (assuming the network request was successful for initialization).

Statsig is working on the metadata around these cases to make it easier to debug. In new SDK versions, it will be possible to differentiate them a bit more. There are also plans to make a change to React that won't even render the children until initialization has at least started so there won't be uninitialized checks at first. This is due to the ordering of effects, where SDK hooks will run before the SDK initialization path in the provider.

There are two main methods for performing A/B tests for static pages in Next.js using Statsig.

The first method involves using getClientInitializeResponse and storing the initializeValues in a cookie. This approach is suitable if you want to avoid generating separate static pages for each variant. However, the cookie size is limited to 4KB, so this method might not be suitable if the initializeValues are large.

The second method involves generating a separate static page for each experiment's variant. This approach is suitable if you have a small number of variants and want to avoid the cookie size limitation. However, this method might require more setup and maintenance if you have a large number of variants.

If you're unsure which method to use, you can start with the method that seems easier to implement and switch to the other method if you encounter issues.

If you're concerned about the size of initializeValues, there are a couple of ways to bring down the response size. One way is to use target apps to limit the gates/experiments/etc included in the response. Another way is to add an option to getClientInitializeResponse to specify which gates/experiments/etc to include in the response.

If you plan on stitching together multiple cookies, a simple string splice might be easier. An alternative that doesn't involve stitching together multiple initializeValues is to use multiple client SDK instances. This wouldn't be supported in react, but using the js SDK, you could have multiple statsig instances each with its own set of configs. You would have to keep track of which instance to use for which experiment but this may be a "cleaner" approach.

The JS SDK can be synchronously loaded using initializeValues similarly to how the StatsigSynchronousProvider works. So you should be able to just call statsig.initialize(..., {initializeValues}) without needing to worry about awaiting.

Finally, you can also use the local evaluation SDK to fetch the whole config before the page becomes interactive and then pass it to the synchronous SDK. This is a client SDK, but it solves the "flickering" issues because you don't need to wait for the experiment(s) data to be fetched on the fly.

When deploying to an environment in Statsig, if you encounter an issue where the RULE is always Default and the REASON is Unrecognized, it typically means that the SDK was initialized, but the config or feature gate you're trying to evaluate did not exist in the set of values. This could be due to a few reasons:

1. The feature gate or dynamic config you're trying to evaluate does not exist or is not correctly spelled in your code. Please double-check the spelling and case-sensitivity.

2. The SDK might not have been able to fetch the latest rules from the Statsig server. This could be due to network issues or if the SDK initialization did not complete successfully.

3. If you're using a server SDK, it's possible that the SDK is outdated and doesn't recognize new types of gate conditions. In this case, upgrading the SDK might resolve the issue.

Remember, the Unrecognized reason is only given when the SDK is initialized, but the config or feature gate did not exist in the set of values.

It's also important to ensure that you are waiting for initialize to finish before making evaluations. For instance, calling checkGate inside the callback or after you are sure the callback has been triggered.

Additionally, check if the environment you've deployed to is able to make requests to the relevant URLs. In some cases, these requests might be blocked by the client in your production environment.

If you're still having trouble, please provide more details about your setup and the issue, and a Statsig team member will assist you shortly.

The "Uninitialized" assignments in Statsig could be due to the initTimeoutMs parameter in the Provider. This parameter determines how long the Statsig client waits for the initial network request to respond before proceeding. If this timeout is too short, it could lead to an "Uninitialized" status if the initialization network request doesn't complete within the specified time.

In some cases, a 400ms timeout might be too short, causing the initialization to not complete in time, especially if network conditions are not optimal. It is recommended to consider increasing this timeout value to allow more time for initialization.

However, for Server Side Rendering (SSR) pages using the StatsigSynchronousProvider, there is no concept of initTimeoutMs. Therefore, the initialization happens on the server and there should be minimal uninitialized cases. If you are seeing a notable number of uninitialized cases for an experiment on an SSR page, it could be due to other factors not related to the initTimeoutMs parameter.

Please note that the initialization process involves a network request, and depending on the network condition and location of the users, a short timeout like 400ms might not be sufficient for many users.