SDKs
React Native
Provider and hooks, offline datafile, flush on background.
Install#
npm install @liftcanary/react-native @react-native-async-storage/async-storageWorks 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#
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#
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: falseturns 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)
storageAsyncStorage-like | Persists queued events, the anonymous id and the last datafile. |
refreshOnForegroundboolean | Default true. |
Anonymous users#
import { getAnonymousId } from "@liftcanary/react-native";
const anonId = await getAnonymousId(AsyncStorage); // stable across launchesIt'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:
<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.
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.