React Native SDK

@traffical/react-native is the SDK for iOS and Android apps built with React Native. It handles the constraints mobile imposes — cold starts, offline use, app suspension, device context — and ships with sensible defaults so most apps don’t have to think about them.

Why mobile is different

Mobile has constraints web and backend don’t:

Cold start. On first launch there’s no cached bundle and no network response yet. The user sees the app before any policy can resolve.
Offline use. Users open the app on planes and in subways. Resolution must work without connectivity.
App store latency. Code changes take days. Parameter changes via Traffical are instant — this is the whole point of having a remote configuration system at all.
Background suspension. The app may be paused for hours and resumed. Cached assignments need refreshing.

Use evaluationMode: "bundle" for mobile. The SDK fetches the config bundle once and resolves on-device, so every subsequent decision is local — no per-decision network call, and it keeps working offline. This is also the only mode that works with a publishable key, which is the key type that belongs in a mobile binary. The package’s own default is still evaluationMode: "server", where each resolution is evaluated for that call’s context on the edge and the response is persisted to AsyncStorage across launches. Because getParams/decide are synchronous, a call returns the last-good cached response and converges as fresh resolves land. Server mode requires a server-side SDK key, so on mobile it means proxying through your own backend.

Installation

npm install @traffical/react-native @react-native-async-storage/async-storage

pnpm add @traffical/react-native @react-native-async-storage/async-storage

yarn add @traffical/react-native @react-native-async-storage/async-storage

For iOS, run pod install in the ios/ directory after adding @react-native-async-storage/async-storage.

Setup

import { TrafficalRNProvider } from "@traffical/react-native";

function App() {
  return (
    <TrafficalRNProvider config={{
      orgId: "org_acme",
      projectId: "proj_marketplace",
      env: "production",
      apiKey: "traffical_pk_...",
      evaluationMode: "bundle",
    }}>
      <Navigator />
    </TrafficalRNProvider>
  );
}

Use a publishable SDK key (traffical_pk_...) — it is safe to ship in a mobile binary. The SDK auto-registers the AsyncStorage cache and lifecycle hooks for foreground/background transitions.

Set evaluationMode: "bundle" with a publishable key.This SDK defaults to evaluationMode: "server", which resolves through /v1/resolve. That endpoint accepts only server-side SDK keys, so leaving the default in place with a traffical_pk_... key returns 403 on every resolution.Bundle mode fetches the config bundle once and resolves on-device — no per-decision network call, and it works offline. It is the recommended mode for mobile regardless of key type.Server-evaluated mode needs a server-side SDK key (traffical_sk_...), which must never ship in a mobile binary. If you need it, proxy resolution through your own backend.

Resolving parameters

Same hook as the React SDK:

import { useTraffical } from "@traffical/react-native";

function Onboarding() {
  const { params } = useTraffical({
    defaults: {
      "mobile.onboarding_steps": 3,
      "mobile.onboarding_style": "carousel",
    },
  });

  return (
    <OnboardingCarousel
      steps={params["mobile.onboarding_steps"]}
      style={params["mobile.onboarding_style"]}
    />
  );
}

Cold start strategy

Resolution checks three sources in order:

Priority	Source	When available	Staleness
1	Cached assignments (AsyncStorage)	After first successful resolve	Refreshed per session
2	`localConfig` bundle (baked into the app binary)	Always (compiled in)	As of the last app build
3	Caller `defaults` from `getParams`	Always	Hardcoded fallback

First launch, no localConfig: the user sees defaults until the first network call returns. If your first-launch onboarding is a critical test, embed a localConfig bundle built during CI:

<TrafficalRNProvider config={{
  orgId: "org_acme",
  projectId: "proj_marketplace",
  env: "production",
  apiKey: "traffical_pk_...",
  evaluationMode: "bundle",
  localConfig: require("./traffical-bundle.json"),    // generated by CI
}}>

Returning user: the SDK reads cached assignments from AsyncStorage synchronously before the first render. The user immediately sees their previous-session assignment. A background refresh updates for next time. Returning user after long absence (cache expired): falls back to localConfig, then to caller defaults.

Device-info enrichment

The SDK can enrich context with device info — useful for OS-specific targeting and analytics. You supply the data through a deviceInfoProvider: any object implementing the DeviceInfoProvider interface. The returned fields merge into context on every resolution, so they’re available for policy conditions.

The default provider

defaultDeviceInfoProvider derives device metadata from React Native’s Platform and Dimensions plus Intl — no native modules. It is opt-in: nothing is added to your context unless you pass it.

import { TrafficalRNProvider, defaultDeviceInfoProvider } from "@traffical/react-native";

<TrafficalRNProvider config={{ orgId, projectId, env, apiKey, deviceInfoProvider: defaultDeviceInfoProvider }}>

It emits the $-prefixed system attributes shared by every Traffical SDK — registered in every project, so you can target them straight from the condition editor — plus un-prefixed fields for compatibility with existing conditions:

Key	Type	Value
`$os`	enum	`ios`, `android`, `macos`, `windows`, or `other` (from `Platform.OS`)
`$os_version`	string	`Platform.Version` as a string
`$device_type`	enum	iOS: `Platform.isPad` → `tablet`, else `mobile`; Android: shortest side ≥ 600dp → `tablet`, else `mobile`; other platforms: width `< 768` mobile, `< 1024` tablet, else `desktop`
`$device_model`	string	Android only (`Platform.constants.Model`). iOS exposes no model without a native module.
`$locale`, `$timezone`	string	`Intl.DateTimeFormat().resolvedOptions()`
`$app_version`	string	Only when you supply it — React Native has no app version without a native module
`osName`, `osVersion`, `locale`, `timezone`, `screenWidth`, `screenHeight`, `pixelRatio`, `deviceModel`, `appVersion`, `appBuildNumber`		Compatibility fields, same values

Values are re-read on every call, so rotation and locale changes are picked up on the next decision. To populate $app_version, build the provider with the version from your own source (expo-constants, react-native-device-info, or a generated constant):

import { createDefaultDeviceInfoProvider } from "@traffical/react-native";

const deviceInfoProvider = createDefaultDeviceInfoProvider({ appVersion: "2.3.1", appBuildNumber: "451" });

Your own provider

Implement DeviceInfoProvider yourself to add fields the default cannot read, typically backed by react-native-device-info:

import { TrafficalRNProvider, type DeviceInfoProvider } from "@traffical/react-native";
import { Platform, Dimensions } from "react-native";
import DeviceInfo from "react-native-device-info";

const deviceInfoProvider: DeviceInfoProvider = {
  getDeviceInfo() {
    const { width, height } = Dimensions.get("window");
    return {
      $app_version: DeviceInfo.getVersion(),
      $os: Platform.OS === "ios" ? "ios" : "android",
      $os_version: String(Platform.Version),
      $device_model: DeviceInfo.getModel(),
      screenWidth: width,
      screenHeight: height,
    };
  },
};

<TrafficalRNProvider config={{ orgId, projectId, env, apiKey, deviceInfoProvider }}>

Use the $ keys in new conditions — e.g. $os eq "ios" for an iOS-only policy.

Version-string targeting is a known gap. The numeric comparison operators (gt/gte/lt/lte) only compare numbers — a condition like appVersion gte "2.0.0" won’t match, because "2.0.0" is a string. To gate on a minimum version today, target an exact set of versions with in, or expose a numeric build number (appBuildNumber) and compare that. Semver-aware version conditions are not yet supported.

Tracking events

import { useTrafficalTrack } from "@traffical/react-native";

function PaywallScreen() {
  const track = useTrafficalTrack();
  return <Button onPress={() => track("paywall_purchase_started")} title="Subscribe" />;
}

Events are batched in memory and flushed on background or app close.

Foreground refresh

When the app returns to the foreground after being suspended, the SDK checks whether the cache is stale and refreshes silently if so. Existing assignments stay stable — the refresh only matters for new parameters or next-session resolutions.

Options

Option	Type	Default	Description
`orgId`, `projectId`, `env`, `apiKey`	—	required	Same as other SDKs
`evaluationMode`	`"bundle" \| "server"`	`"server"`	Mobile-friendly default
`localConfig`	`ConfigBundle`	—	Embedded bundle for cold-start
`deviceInfoProvider`	`DeviceInfoProvider`	—	Device-context enrichment — pass the built-in `defaultDeviceInfoProvider` or your own
`cacheMaxAgeMs`	`number`	`86400000`	Max age of the persisted server response before it’s treated as expired (24h)
`refreshIntervalMs`	`number`	`60000`	Background refresh cadence

Persistence is backed by AsyncStorage automatically — the provider registers it for you, so there’s no storage option to set. The provider also accepts the common options shared with the other SDKs (trackDecisions, exposureSessionTtlMs, eventBatchSize, eventFlushIntervalMs, disableCloudEvents, assignmentLogger, unitKeyFn, contextFn, plugins).

Overview

Server SDKs

Client SDKs

Integrations

Patterns

Why mobile is different

Installation

Setup

Resolving parameters

Cold start strategy

Device-info enrichment

The default provider

Your own provider

Tracking events

Foreground refresh

Options

Next steps

Mobile app pattern

How it works

​Why mobile is different

​Installation

​Setup

​Resolving parameters

​Cold start strategy

​Device-info enrichment

​The default provider

​Your own provider

​Tracking events

​Foreground refresh

​Options

​Next steps

Mobile app pattern

How it works

Why mobile is different

Installation

Setup

Resolving parameters

Cold start strategy

Device-info enrichment

The default provider

Your own provider

Tracking events

Foreground refresh

Options

Next steps