Using SpecsDataAdapter

Learn how to use and customize the StatsigSpecsDataAdapter for on-device evaluation clients.

The StatsigSpecsDataAdapter is the default SpecsDataAdapter used by a StatsigOnDeviceEvalClient instance.

It handles fetching and caching values from Statsig's servers. If required, you can create your own custom SpecsDataAdapter and pass it to the Statsig client through StatsigOptions.dataAdapter.

How StatsigSpecsDataAdapter works

Synchronous behavior (cache)

When calling StatsigOnDeviceEvalClient.initializeSync, the StatsigSpecsDataAdapter loads values from cache and provides them to the client. The client also calls refresh in the background through StatsigSpecsDataAdapter.getDataAsync, causing values to lag until the next initializeSync call.

In practice, the very first session has no cached values. Cached values are available starting from the second session.

Asynchronous behavior (network)

When calling StatsigOnDeviceEvalClient.initializeAsync, the StatsigSpecsDataAdapter loads values from cache and provides them to the client. The client then blocks on a call to StatsigSpecsDataAdapter.getDataAsync, allowing the latest values from Statsig to be awaited.

If you want the latest values but don't want to await the asynchronous call, call initializeAsync and .catch the promise. This can cause values to change mid-session as newer values arrive from the network.

Advanced Usage

Getting the Data Adapter

You can access the data adapter from your Statsig on-device client instance:

typescript

const client = new StatsigOnDeviceEvalClient('client-key');
await client.initializeAsync();

const dataAdapter = client.dataAdapter;

View full example on GitHub

Bootstrapping

Bootstrapping allows you to provide the required data without a network call. This is useful when you want to avoid network calls during startup.

If you build a mobile app and want to bundle values with your application, load the values from a local file at startup and provide them to the data adapter.

typescript

import { StatsigOnDeviceEvalClient } from '@statsig/js-on-device-eval-client';

const client = new StatsigOnDeviceEvalClient('client-key');

// Bootstrap with specs data from local file or bundle
const specsData = /* data from local file */;
await client.dataAdapter.setData(specsData);

await client.initializeAsync();

View full example on GitHub

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

Custom Implementation

To customize when and how data is fetched, and where it is stored, create your own class that conforms to the SpecsDataAdapter type.

The SpecsDataAdapter type defines the following functions.

attach - Called when the SpecsDataAdapter is passed into a StatsigOnDeviceEvalClient through StatsigOptions. This lets the SpecsDataAdapter use the same SDK Key and StatsigOptions as the StatsigOnDeviceEvalClient instance.
- typescript
```
attach: (sdkKey: string, options: StatsigOptionsCommon | null) => void
```
getDataSync - Synchronously get evaluation data for the given user. Called during initializeSync. Also called during async update operations before StatsigDataAdapter.getDataAsync is called.
- typescript
```
getDataSync: () => DataAdapterResult | null;
```
getDataAsync - Asynchronously get evaluation data for the given user. Called during initializeAsync.
- typescript
```
getDataAsync: (current: DataAdapterResult | null) => Promise<DataAdapterResult | null>;
```
prefetchData - Manually trigger a fetch for new specs data.
- typescript
```
prefetchData: () => Promise<void>;
```
setData - Manually set specs data.
- typescript
```
setData: (data: string) => Promise<void>;
```

Was this helpful?