React Native SDK

@cohorly/react-native is a standalone React Native client. It has no hard dependency on react-native or any storage library - it works out of the box with an in-memory store and upgrades to persistent storage when you inject one.

Install

bash
pnpm add @cohorly/react-native
# recommended, for persistence across app restarts
pnpm add @react-native-async-storage/async-storage

Initialize

Call init() once near app launch. Inject AsyncStorage so the distinct id, queued events, and super properties survive restarts.

ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { init, track, identify, people } from "@cohorly/react-native";
init({
  token: "YOUR_PROJECT_TOKEN",
  storage: AsyncStorage, // omit to fall back to in-memory storage
});
track("Screen Viewed", { screen: "Home" });
identify("user_123");
people.set({ plan: "pro" });

API

Member	Signature	Notes
`init`	`(options) => CohorlyClient`	All optional: `token`, `apiHost` (defaults to the hosted API), `storage`, `flushInterval`, `flushAt`, `fetch`, `disabled`, `loadFeatureFlags`, `sendExposureEvents`, `flagPersistence`, `flagCacheTtlMs`.
`track`	`(event, properties?) => void`	Queue an event.
`identify`	`(distinctId) => void`	Switches identity synchronously, then posts `/alias` (best effort) when the previous id was anonymous.
`reset`	`() => void`	Clears identity, super properties, and un-flushed events.
`register` / `unregister`	`(props)` / `(key)`	Super properties merged into every event.
`people.*`	`set / setOnce / increment / unset / deleteUser`	Queued and sent to /engage.
`flush`	`() => Promise<void>`	Manual flush.
`getDistinctId`	`() => string`	Current distinct id.
`getFeatureFlag` / `isFeatureEnabled`	`(key, fallback?)`	Flag reads; optional fallback for unknown/unloaded flags (never an exposure).
`getFeatureFlagDetails`	`(key, fallback?) => FlagDetails`	Full result with `source` (`"network"` / `"persistence"` / `"fallback"`) plus `ttlMs` - and `persistedAt` when the cache carries `stored_at` - when served from the cache.
`getFeatureFlagPayload`	`(key) => unknown \| null`	Variant payload.
`reloadFeatureFlags` / `onFeatureFlags`	`() => Promise<void>` / `(cb) => unsub`	Re-evaluate; subscribe to updates.

Flags are persisted per identity (cohorly:flags, scoped by distinct_id) and bounded by flagCacheTtlMs (default 86400000 ms, 24 h). flagPersistence selects the policy - "persistenceUntilNetworkSuccess" (default, still serves an expired cache up to 7 days stale), "networkFirst" (strictly within the TTL), or "networkOnly" (never touches the cache). A legacy cache without stored_at is served indefinitely until a successful reload rewrites it. See Feature flags.

Note the People delete method here is people.deleteUser() (not delete). identify() applies the identity switch synchronously and then fires an /alias post in the background: it is never awaited, and a failure is swallowed rather than retried. That is safe because every event already carries $device_id and, once identified, $user_id, so the server links the anonymous and identified ids implicitly from the next track() call even if the /alias post never lands. See Identity. Call reset() on logout so a shared device doesn't carry one person's identity into the next session.

Batching

Events are queued and flushed automatically every 5 seconds or once 20 events have accumulated - both configurable via flushInterval and flushAt. Queued events are persisted to storage, so nothing is lost if the app closes before a flush. You can also construct new CohorlyClient(options) directly for multiple instances or dependency injection.