LiftCanary

SDKs

React Native

Provider and hooks, offline datafile, flush on background.

Install#

Terminal
npm install @liftcanary/react-native @react-native-async-storage/async-storage

Works with bare React Native and Expo. AsyncStorage is optional but recommended (see below); an MMKV wrapper with the same methods works too.

Set up the provider#

App.tsx
import AsyncStorage from "@react-native-async-storage/async-storage";
import { createClient, LiftCanaryProvider } from "@liftcanary/react-native";
import { Platform } from "react-native";
import { version } from "./package.json";

const client = createClient({ sdkKey: "pk_...", storage: AsyncStorage });

export default function App() {
  const { userId, plan } = useSession();
  return (
    <LiftCanaryProvider client={client} user={{ id: userId, attributes: { platform: Platform.OS, app_version: version, plan } }}>
      <Navigation />
    </LiftCanaryProvider>
  );
}

Changing user (login, a new attribute) re-evaluates every hook below the provider. Hooks re-render when a newer datafile arrives, so a kill switch reaches open screens without a restart.

Hooks#

TSX
import { useDecision, useFlag, useTrack, useVariable } from "@liftcanary/react-native";

function Paywall() {
  const showTrial = useFlag("paywall_trial");
  const price = useVariable("paywall", "monthly_price", 9.99);
  const track = useTrack();
  return <PlanCard price={price} trial={showTrial} onBuy={() => track("purchase", { value: price })} />;
}
useDecision(flagKey)
Decision
The full decision. Decides during render without side effects and logs the exposure in an effect, once per user and variation.
useFlag(flagKey)
boolean
Whether the feature is on.
useVariable(flagKey, name, fallback)
T
A typed variable, or the fallback when missing or of another type.
useTrack()
(eventKey, options?) => void
A stable track function for the current user.
useLiftCanaryReady(timeoutMs = 3000)
boolean
False until the first datafile is loaded or the timeout passes. Use it to hold a splash screen.
useLiftCanaryClient()
Client
The client, for anything the hooks don't cover.

App lifecycle#

  • Queued events are flushed when the app goes to the background.
  • The datafile is refreshed when the app returns to the foreground (refreshOnForeground: false turns it off) and polled every minute while open.
  • With storage, queued events survive the app being killed and are sent on the next launch, and the last datafile is kept on the device (see below). Without it both live in memory only.
  • client.close() removes the listeners and flushes remaining events.

Options (in addition to the shared client options)

storage
AsyncStorage-like
Persists queued events, the anonymous id and the last datafile.
refreshOnForeground
boolean
Default true.

Anonymous users#

TypeScript
import { getAnonymousId } from "@liftcanary/react-native";
const anonId = await getAnonymousId(AsyncStorage); // stable across launches

It's a random UUID saved under liftcanary:anonymous_id. Pass the same storage every time: without storage the id lasts only until the app is closed, so the next launch gets a new id and possibly a new variation.

Use the anonymous id until login, then your user id, so people keep one variation across your app and website. Switching ids can change the variation; to prevent that for tests that start before login, keep the anonymous id as bucketingId:

TSX
<LiftCanaryProvider client={client} user={{ id: userId ?? anonId, bucketingId: anonId }}>

See which id decides the variation for the trade-off.

Offline#

With storage, every datafile the app downloads is also saved on the device. On the next launch the SDK still tries the network first, so a fresh configuration (a kill switch, say) always wins; the saved datafile is used only when the download fails or takes longer than ready()'s timeout. An app opened offline therefore decides with the last configuration it saw, and users keep their variations.

On the very first launch there is nothing saved yet, so without network flags return their defaults (reason NOT_READY) until a datafile arrives. To decide immediately even then, ship a datafile in the app bundle and pass it as datafile; newer revisions replace it as soon as they download or are read from storage.

TypeScript
import bundled from "./liftcanary-datafile.json";
const client = createClient({ sdkKey: "pk_...", storage: AsyncStorage, datafile: bundled });

Targeting app versions#

Pass app_version as an attribute and use the version operators (semverGte, semverLt…) in rules: for example, enable a feature only from 2.4.0, or switch off a broken flow in 2.3.x without waiting for store review.