@thravic/react-native 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @thravic/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Thravic analytics for React Native and Expo apps. Track screens, sessions, versions and devices, plus your own events, in the same dashboard as your website.
+
+## Install
+
+```bash
+npm install @thravic/react-native @react-native-async-storage/async-storage
+```
+
+With Expo, use `npx expo install @thravic/react-native @react-native-async-storage/async-storage`. You don't need any other native modules or a config plugin, and it works in Expo Go.
+
+On bare React Native, run `npx pod-install` after installing.
+
+## Start tracking
+
+Add the app in your Thravic dashboard (**Add property → Mobile app**) to get its tracking ID. Then call `init` once, as early as you can:
+
+```ts
+import { Thravic } from '@thravic/react-native';
+
+Thravic.init('TF-1A2B3C4D', {
+  bundleId: 'com.acme.shop',
+  appVersion: '1.4.0',
+});
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `bundleId` | `'app'` | The host of screen URLs (`app://com.acme.shop/Home`). |
+| `appVersion` | none | Shown under **Versions**. In Expo, use `Application.nativeApplicationVersion` from `expo-application`. |
+| `apiUrl` | `https://api.thravic.com` | |
+| `sessionTimeoutMinutes` | `30` | Time in the background after which the next open starts a new session. |
+| `flushIntervalSeconds` | `10` | How often queued events are sent. |
+| `debug` | `false` | Log every event to the console. |
+
+## Screens
+
+### React Navigation
+
+```tsx
+import { NavigationContainer, createNavigationContainerRef } from '@react-navigation/native';
+import { Thravic } from '@thravic/react-native';
+
+const navigationRef = createNavigationContainerRef();
+
+export default function App() {
+  return (
+    <NavigationContainer ref={navigationRef} onReady={() => Thravic.trackNavigation(navigationRef)}>
+      {/* ... */}
+    </NavigationContainer>
+  );
+}
+```
+
+### Expo Router
+
+```tsx
+// app/_layout.tsx
+import { Stack, useNavigationContainerRef } from 'expo-router';
+import { useEffect } from 'react';
+import { Thravic } from '@thravic/react-native';
+
+Thravic.init('TF-1A2B3C4D', { bundleId: 'com.acme.shop' });
+
+export default function Layout() {
+  const ref = useNavigationContainerRef();
+  useEffect(() => Thravic.trackNavigation(ref), [ref]);
+  return <Stack />;
+}
+```
+
+### By hand
+
+```ts
+Thravic.screen('Checkout');
+```
+
+## Events and users
+
+```ts
+Thravic.track('purchase', { amount: 49, currency: 'USD' });
+Thravic.identify('user-42');
+```
+
+## Privacy
+
+```ts
+Thravic.optOut(); // stops tracking and drops unsent events; remembered across launches
+Thravic.optIn();
+Thravic.isOptedOut();
+```
+
+The SDK stores a random visitor ID in AsyncStorage. It doesn't read the advertising ID, contacts, location or any other permissioned data. The dashboard gets the country from the request IP and then throws the IP away.
+
+## How it works
+
+- Screen views are sent as page views on `app://<bundleId>/<Screen>`, so Pages (shown as Screens), paths and funnels work the same way they do for a website.
+- A session starts when the app opens (`app_open`). It ends when the app goes to the background (`session_end`, with the duration and the last screen). Coming back within `sessionTimeoutMinutes` continues the same session.
+- Events are queued on the device and sent in batches of up to 50. They are sent every `flushIntervalSeconds`, when 10 are waiting, and when the app goes to the background. If a send fails, it is retried with backoff, including after a restart. Up to 1,000 events are kept offline.
+- Every event carries the OS, OS version, device model (manufacturer and model on Android; iPhone or iPad on iOS), app version, screen size and language.

package/dist/client.d.ts

@@ -0,0 +1,73 @@
+import type { Environment, NavigationRefLike, ThravicOptions } from './types';
+export declare const VISITOR_KEY = "_tf_vid";
+export declare const QUEUE_KEY = "_tf_queue";
+export declare const OPT_OUT_KEY = "_tf_optout";
+export declare const DEFAULT_API_URL = "https://api.thravic.com";
+/** The collector takes at most 50 events per batch. */
+export declare const MAX_BATCH = 50;
+/** Queued events kept while offline; the oldest go first. */
+export declare const MAX_QUEUE = 1000;
+/** A v4-shaped id, like the web tracker's. Not cryptographic: ids only need to be unique. */
+export declare function generateId(): string;
+/**
+ * The SDK. Screen views are sent as `pageview` events on `app://<bundleId>/<Screen>`
+ * URLs, so the dashboard's pages, paths and funnels work for apps as they do for
+ * websites. Events are queued on the device and sent in batches; a batch the API
+ * has not acknowledged stays queued and is retried, including after a restart.
+ */
+export declare class ThravicClient {
+    private env;
+    private trackingId;
+    private options;
+    private initialized;
+    private ready;
+    /** Calls made before storage has loaded, replayed in order once it has. */
+    private pending;
+    private visitorId;
+    private sessionId;
+    private sessionStart;
+    private backgroundAt;
+    private currentScreen;
+    private optedOut;
+    private queue;
+    private sending;
+    private retryAttempt;
+    private retryScheduled;
+    private persistScheduled;
+    private timer;
+    private unsubscribeAppState;
+    constructor(env: Environment);
+    /** Start tracking. Call once, when the app starts; later calls are ignored. */
+    init(trackingId: string, options?: ThravicOptions): Promise<void>;
+    /** Record a screen view. Automatic with `trackNavigation`; call it yourself otherwise. */
+    screen(name: string, params?: Record<string, unknown>): void;
+    /** Record a custom event, e.g. `track('purchase', { amount: 49 })`. */
+    track(event: string, properties?: Record<string, unknown>): void;
+    /** Link this device to your own user id. Sent as the web tracker sends it. */
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /** Stop tracking this device, and drop anything not yet sent. Remembered across launches. */
+    optOut(): void;
+    /** Resume tracking after `optOut`. */
+    optIn(): void;
+    isOptedOut(): boolean;
+    /**
+     * Record a screen view whenever the focused route changes. Pass the ref from
+     * `createNavigationContainerRef()` / `useNavigationContainerRef()` (React
+     * Navigation or Expo Router). Returns a function that stops it.
+     */
+    trackNavigation(ref: NavigationRefLike): () => void;
+    /** Send everything queued now. Resolves when the attempt is done. */
+    flush(): Promise<void>;
+    /** Stop timers and listeners. For tests and hot reload; apps never need it. */
+    shutdown(): void;
+    private startSession;
+    private background;
+    private foreground;
+    private whenReady;
+    private screenUrl;
+    private enqueue;
+    /** Write the queue to storage, at most once a second. */
+    private persist;
+    private scheduleRetry;
+    private debug;
+}

package/dist/client.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThravicClient = exports.MAX_QUEUE = exports.MAX_BATCH = exports.DEFAULT_API_URL = exports.OPT_OUT_KEY = exports.QUEUE_KEY = exports.VISITOR_KEY = void 0;
+exports.generateId = generateId;
+exports.VISITOR_KEY = '_tf_vid';
+exports.QUEUE_KEY = '_tf_queue';
+exports.OPT_OUT_KEY = '_tf_optout';
+exports.DEFAULT_API_URL = 'https://api.thravic.com';
+/** The collector takes at most 50 events per batch. */
+exports.MAX_BATCH = 50;
+/** Queued events kept while offline; the oldest go first. */
+exports.MAX_QUEUE = 1000;
+/** Send without waiting for the timer once this many are queued. */
+const FLUSH_AT = 10;
+const MAX_RETRY_DELAY_MS = 30000;
+const PERSIST_DELAY_MS = 1000;
+const DEFAULTS = {
+    apiUrl: exports.DEFAULT_API_URL,
+    sessionTimeoutMinutes: 30,
+    flushIntervalSeconds: 10,
+    debug: false,
+};
+/** A v4-shaped id, like the web tracker's. Not cryptographic: ids only need to be unique. */
+function generateId() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        return (c === 'x' ? r : (r & 3) | 8).toString(16);
+    });
+}
+/**
+ * The SDK. Screen views are sent as `pageview` events on `app://<bundleId>/<Screen>`
+ * URLs, so the dashboard's pages, paths and funnels work for apps as they do for
+ * websites. Events are queued on the device and sent in batches; a batch the API
+ * has not acknowledged stays queued and is retried, including after a restart.
+ */
+class ThravicClient {
+    constructor(env) {
+        this.trackingId = '';
+        this.options = { ...DEFAULTS };
+        this.initialized = false;
+        this.ready = false;
+        /** Calls made before storage has loaded, replayed in order once it has. */
+        this.pending = [];
+        this.visitorId = '';
+        this.sessionId = '';
+        this.sessionStart = 0;
+        this.backgroundAt = null;
+        this.currentScreen = null;
+        this.optedOut = false;
+        this.queue = [];
+        this.sending = false;
+        this.retryAttempt = 0;
+        this.retryScheduled = false;
+        this.persistScheduled = false;
+        this.timer = null;
+        this.unsubscribeAppState = null;
+        this.env = env;
+    }
+    /** Start tracking. Call once, when the app starts; later calls are ignored. */
+    async init(trackingId, options = {}) {
+        if (this.initialized)
+            return;
+        if (!trackingId) {
+            this.env.log('[Thravic] init needs your tracking ID, e.g. Thravic.init("TF-1A2B3C4D").');
+            return;
+        }
+        this.initialized = true;
+        this.trackingId = trackingId;
+        this.options = { ...DEFAULTS, ...stripUndefined(options) };
+        this.options.apiUrl = this.options.apiUrl.replace(/\/+$/, '');
+        const { storage } = this.env;
+        try {
+            this.optedOut = (await storage.getItem(exports.OPT_OUT_KEY)) === '1';
+            this.visitorId = (await storage.getItem(exports.VISITOR_KEY)) || '';
+            if (!this.visitorId) {
+                this.visitorId = generateId();
+                await storage.setItem(exports.VISITOR_KEY, this.visitorId);
+            }
+            this.queue = parseQueue(await storage.getItem(exports.QUEUE_KEY));
+        }
+        catch (err) {
+            // Storage unavailable: track this run only.
+            this.visitorId = this.visitorId || generateId();
+            this.debug('storage unavailable', err);
+        }
+        this.startSession();
+        this.unsubscribeAppState = this.env.onAppStateChange((active) => active ? this.foreground() : this.background());
+        this.timer = this.env.setInterval(() => void this.flush(), this.options.flushIntervalSeconds * 1000);
+        this.ready = true;
+        const pending = this.pending;
+        this.pending = [];
+        pending.forEach((call) => call());
+        void this.flush();
+    }
+    /** Record a screen view. Automatic with `trackNavigation`; call it yourself otherwise. */
+    screen(name, params) {
+        this.whenReady(() => {
+            const screen = String(name || '').trim().replace(/^\/+/, '');
+            if (!screen)
+                return;
+            this.currentScreen = screen;
+            this.enqueue('pageview', params && Object.keys(params).length ? { params } : undefined);
+        });
+    }
+    /** Record a custom event, e.g. `track('purchase', { amount: 49 })`. */
+    track(event, properties) {
+        this.whenReady(() => {
+            if (!event)
+                return;
+            this.enqueue('custom', { ...properties, event });
+        });
+    }
+    /** Link this device to your own user id. Sent as the web tracker sends it. */
+    identify(userId, traits) {
+        this.whenReady(() => {
+            if (!userId)
+                return;
+            this.enqueue('custom', { ...traits, event: 'identify', userId: String(userId) });
+        });
+    }
+    /** Stop tracking this device, and drop anything not yet sent. Remembered across launches. */
+    optOut() {
+        this.optedOut = true;
+        this.queue = [];
+        void this.env.storage.setItem(exports.OPT_OUT_KEY, '1').catch(() => undefined);
+        void this.env.storage.removeItem(exports.QUEUE_KEY).catch(() => undefined);
+    }
+    /** Resume tracking after `optOut`. */
+    optIn() {
+        this.optedOut = false;
+        void this.env.storage.removeItem(exports.OPT_OUT_KEY).catch(() => undefined);
+    }
+    isOptedOut() {
+        return this.optedOut;
+    }
+    /**
+     * Record a screen view whenever the focused route changes. Pass the ref from
+     * `createNavigationContainerRef()` / `useNavigationContainerRef()` (React
+     * Navigation or Expo Router). Returns a function that stops it.
+     */
+    trackNavigation(ref) {
+        let last = null;
+        const onState = () => {
+            if (ref.isReady && !ref.isReady())
+                return;
+            const route = ref.getCurrentRoute();
+            if (!route || route.name === last)
+                return;
+            last = route.name;
+            this.screen(route.name);
+        };
+        const unsubscribe = ref.addListener('state', onState);
+        onState();
+        return unsubscribe;
+    }
+    /** Send everything queued now. Resolves when the attempt is done. */
+    async flush() {
+        if (!this.ready || this.sending || this.optedOut || this.queue.length === 0)
+            return;
+        this.sending = true;
+        const batch = this.queue.slice(0, exports.MAX_BATCH);
+        const sent = new Set(batch.map((e) => e.eventId));
+        let more = false;
+        try {
+            const response = await this.env.fetch(`${this.options.apiUrl}/api/collect/${encodeURIComponent(this.trackingId)}/batch`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ events: batch }),
+            });
+            // A 4xx other than 429 will never succeed: drop the batch rather than
+            // retrying it forever, as the web tracker does.
+            const rejected = response.status >= 400 && response.status < 500 && response.status !== 429;
+            if (!response.ok && !rejected)
+                throw new Error(`HTTP ${response.status}`);
+            if (rejected)
+                this.debug(`batch rejected with ${response.status}`);
+            this.queue = this.queue.filter((e) => !sent.has(e.eventId));
+            this.retryAttempt = 0;
+            this.persist();
+            more = this.queue.length > 0;
+        }
+        catch (err) {
+            this.debug('send failed, will retry', err);
+            this.scheduleRetry();
+        }
+        finally {
+            this.sending = false;
+        }
+        if (more)
+            await this.flush();
+    }
+    /** Stop timers and listeners. For tests and hot reload; apps never need it. */
+    shutdown() {
+        if (this.timer !== null)
+            this.env.clearInterval(this.timer);
+        this.unsubscribeAppState?.();
+        this.timer = null;
+        this.unsubscribeAppState = null;
+    }
+    // ── Sessions ─────────────────────────────────────────────────────────────
+    startSession() {
+        this.sessionId = generateId();
+        this.sessionStart = this.env.now();
+        this.backgroundAt = null;
+        this.enqueue('custom', { event: 'app_open' });
+    }
+    background() {
+        if (!this.ready || this.backgroundAt !== null)
+            return;
+        this.backgroundAt = this.env.now();
+        this.enqueue('session_end', {
+            duration: Math.round((this.backgroundAt - this.sessionStart) / 1000),
+            lastPage: this.screenUrl(),
+        });
+        void this.flush();
+    }
+    foreground() {
+        if (!this.ready || this.backgroundAt === null)
+            return;
+        const away = this.env.now() - this.backgroundAt;
+        this.backgroundAt = null;
+        if (away < this.options.sessionTimeoutMinutes * 60000)
+            return;
+        // Long enough away that this is a new visit; it starts on the screen in view.
+        this.startSession();
+        if (this.currentScreen)
+            this.enqueue('pageview');
+    }
+    // ── Queue ────────────────────────────────────────────────────────────────
+    whenReady(call) {
+        if (this.ready)
+            call();
+        else if (this.initialized)
+            this.pending.push(call);
+        else
+            this.env.log('[Thravic] Call Thravic.init before tracking.');
+    }
+    screenUrl() {
+        const host = this.options.bundleId || 'app';
+        return `app://${host}/${encodeURI(this.currentScreen || '')}`;
+    }
+    enqueue(type, data) {
+        if (this.optedOut)
+            return;
+        const device = this.env.device();
+        const event = {
+            eventId: generateId(),
+            type,
+            url: this.screenUrl(),
+            visitorId: this.visitorId,
+            sessionId: this.sessionId,
+            ...stripUndefined({
+                os: device.os,
+                osVersion: device.osVersion,
+                deviceModel: device.deviceModel,
+                appVersion: this.options.appVersion,
+                screenWidth: device.screenWidth,
+                screenHeight: device.screenHeight,
+                language: device.language,
+                data,
+            }),
+        };
+        this.queue.push(event);
+        if (this.queue.length > exports.MAX_QUEUE)
+            this.queue = this.queue.slice(-exports.MAX_QUEUE);
+        this.debug(type, event.url, data ?? '');
+        this.persist();
+        if (this.queue.length >= FLUSH_AT)
+            void this.flush();
+    }
+    /** Write the queue to storage, at most once a second. */
+    persist() {
+        if (this.persistScheduled)
+            return;
+        this.persistScheduled = true;
+        this.env.setTimeout(() => {
+            this.persistScheduled = false;
+            const write = this.queue.length === 0
+                ? this.env.storage.removeItem(exports.QUEUE_KEY)
+                : this.env.storage.setItem(exports.QUEUE_KEY, JSON.stringify(this.queue));
+            void write.catch(() => undefined);
+        }, PERSIST_DELAY_MS);
+    }
+    scheduleRetry() {
+        if (this.retryScheduled)
+            return;
+        this.retryScheduled = true;
+        const delay = Math.min(1000 * 2 ** this.retryAttempt, MAX_RETRY_DELAY_MS);
+        this.retryAttempt += 1;
+        this.env.setTimeout(() => {
+            this.retryScheduled = false;
+            void this.flush();
+        }, delay);
+    }
+    debug(...args) {
+        if (this.options.debug)
+            this.env.log('[Thravic]', ...args);
+    }
+}
+exports.ThravicClient = ThravicClient;
+function parseQueue(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .filter((e) => e && typeof e === 'object' && typeof e.eventId === 'string')
+            .slice(-exports.MAX_QUEUE);
+    }
+    catch {
+        return [];
+    }
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined && v !== null && v !== ''));
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { ThravicClient } from './client';
+export { ThravicClient } from './client';
+export type { CollectEvent, DeviceInfo, Environment, NavigationRefLike, Storage, ThravicOptions, } from './types';
+/**
+ * Thravic for React Native.
+ *
+ * ```ts
+ * import { Thravic } from '@thravic/react-native';
+ *
+ * Thravic.init('TF-1A2B3C4D', { appVersion: '1.4.0', bundleId: 'com.acme.shop' });
+ * Thravic.trackNavigation(navigationRef);     // screen views, automatically
+ * Thravic.track('purchase', { amount: 49 });  // your own events
+ * ```
+ */
+export declare const Thravic: ThravicClient;
+export default Thravic;

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Thravic = exports.ThravicClient = void 0;
+const client_1 = require("./client");
+const react_native_1 = require("./react-native");
+var client_2 = require("./client");
+Object.defineProperty(exports, "ThravicClient", { enumerable: true, get: function () { return client_2.ThravicClient; } });
+/**
+ * Thravic for React Native.
+ *
+ * ```ts
+ * import { Thravic } from '@thravic/react-native';
+ *
+ * Thravic.init('TF-1A2B3C4D', { appVersion: '1.4.0', bundleId: 'com.acme.shop' });
+ * Thravic.trackNavigation(navigationRef);     // screen views, automatically
+ * Thravic.track('purchase', { amount: 49 });  // your own events
+ * ```
+ */
+exports.Thravic = new client_1.ThravicClient(react_native_1.reactNativeEnvironment);
+exports.default = exports.Thravic;

package/dist/react-native.d.ts

@@ -0,0 +1,2 @@
+import type { Environment } from './types';
+export declare const reactNativeEnvironment: Environment;

package/dist/react-native.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reactNativeEnvironment = void 0;
+const async_storage_1 = __importDefault(require("@react-native-async-storage/async-storage"));
+const react_native_1 = require("react-native");
+function language() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().locale;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** What React Native itself knows about the device, with no native module to install. */
+function device() {
+    const constants = (react_native_1.Platform.constants || {});
+    const screen = react_native_1.Dimensions.get('screen');
+    const base = {
+        screenWidth: Math.round(screen.width),
+        screenHeight: Math.round(screen.height),
+        language: language(),
+    };
+    if (react_native_1.Platform.OS === 'android') {
+        return {
+            ...base,
+            os: 'Android',
+            // `Platform.Version` is the API level on Android; Release is "14".
+            osVersion: constants.Release || String(react_native_1.Platform.Version),
+            deviceModel: [constants.Manufacturer, constants.Model].filter(Boolean).join(' ') || undefined,
+        };
+    }
+    if (react_native_1.Platform.OS === 'ios') {
+        return {
+            ...base,
+            os: 'iOS',
+            osVersion: String(react_native_1.Platform.Version),
+            // iOS does not expose the model without a native module.
+            deviceModel: constants.interfaceIdiom === 'pad' ? 'iPad' : 'iPhone',
+        };
+    }
+    return { ...base, os: react_native_1.Platform.OS };
+}
+exports.reactNativeEnvironment = {
+    storage: async_storage_1.default,
+    device,
+    fetch: (...args) => fetch(...args),
+    now: () => Date.now(),
+    onAppStateChange(listener) {
+        // 'inactive' is iOS passing through (Control Center, a call banner): not a
+        // departure. Only 'background' ends the visit and only 'active' resumes it.
+        const subscription = react_native_1.AppState.addEventListener('change', (state) => {
+            if (state === 'active')
+                listener(true);
+            else if (state === 'background')
+                listener(false);
+        });
+        return () => subscription.remove();
+    },
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (handle) => clearInterval(handle),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    log: (...args) => console.warn(...args),
+};

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+/** Options for `Thravic.init`. */
+export interface ThravicOptions {
+    /** Where the Thravic API lives. The dashboard's install snippet fills this in. */
+    apiUrl?: string;
+    /** Your app's version, e.g. `Application.nativeApplicationVersion` (Expo) or
+     *  `DeviceInfo.getVersion()` (react-native-device-info). Shown under Versions. */
+    appVersion?: string;
+    /** Your app's bundle ID, used as the host of screen URLs (`app://<bundleId>/Home`). */
+    bundleId?: string;
+    /** Minutes in the background after which the next open starts a new session. */
+    sessionTimeoutMinutes?: number;
+    /** Seconds between automatic sends of queued events. */
+    flushIntervalSeconds?: number;
+    /** Log what the SDK does to the console. */
+    debug?: boolean;
+}
+/** One event as `POST /api/collect/{trackingId}/batch` takes it. */
+export interface CollectEvent {
+    eventId: string;
+    type: 'pageview' | 'custom' | 'session_end';
+    url: string;
+    visitorId: string;
+    sessionId: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    language?: string;
+    os?: string;
+    osVersion?: string;
+    appVersion?: string;
+    deviceModel?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    data?: Record<string, unknown>;
+}
+/** What the device reports about itself. */
+export interface DeviceInfo {
+    os: string;
+    osVersion?: string;
+    deviceModel?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    language?: string;
+}
+/** Key-value storage that survives app restarts (AsyncStorage's shape). */
+export interface Storage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/** Everything the client needs from its platform, so it can run outside React Native. */
+export interface Environment {
+    storage: Storage;
+    device: () => DeviceInfo;
+    fetch: typeof fetch;
+    now: () => number;
+    /** Calls `listener(true)` when the app comes to the foreground and `listener(false)`
+     *  when it leaves; returns an unsubscribe. */
+    onAppStateChange: (listener: (active: boolean) => void) => () => void;
+    setInterval: (fn: () => void, ms: number) => unknown;
+    clearInterval: (handle: unknown) => void;
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    log: (...args: unknown[]) => void;
+}
+/** The parts of a React Navigation container ref the screen tracker uses. Expo
+ *  Router's `useNavigationContainerRef()` returns one too. */
+export interface NavigationRefLike {
+    addListener(event: 'state', listener: () => void): () => void;
+    getCurrentRoute(): {
+        name: string;
+        params?: object;
+    } | undefined;
+    isReady?(): boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@thravic/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Thravic analytics for React Native and Expo apps: screens, sessions and custom events.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "react-native": "src/index.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "README.md"
+  ],
+  "keywords": [
+    "analytics",
+    "react-native",
+    "expo",
+    "thravic"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.17.0",
+    "react-native": ">=0.70.0"
+  },
+  "devDependencies": {
+    "@react-native-async-storage/async-storage": "^2.1.0",
+    "react-native": "^0.76.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.18"
+  }
+}

package/src/client.ts

@@ -0,0 +1,340 @@
+import type {
+  CollectEvent,
+  Environment,
+  NavigationRefLike,
+  ThravicOptions,
+} from './types';
+
+export const VISITOR_KEY = '_tf_vid';
+export const QUEUE_KEY = '_tf_queue';
+export const OPT_OUT_KEY = '_tf_optout';
+
+export const DEFAULT_API_URL = 'https://api.thravic.com';
+/** The collector takes at most 50 events per batch. */
+export const MAX_BATCH = 50;
+/** Queued events kept while offline; the oldest go first. */
+export const MAX_QUEUE = 1000;
+/** Send without waiting for the timer once this many are queued. */
+const FLUSH_AT = 10;
+const MAX_RETRY_DELAY_MS = 30_000;
+const PERSIST_DELAY_MS = 1_000;
+
+const DEFAULTS = {
+  apiUrl: DEFAULT_API_URL,
+  sessionTimeoutMinutes: 30,
+  flushIntervalSeconds: 10,
+  debug: false,
+};
+
+type Resolved = typeof DEFAULTS & ThravicOptions;
+
+/** A v4-shaped id, like the web tracker's. Not cryptographic: ids only need to be unique. */
+export function generateId(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    return (c === 'x' ? r : (r & 3) | 8).toString(16);
+  });
+}
+
+/**
+ * The SDK. Screen views are sent as `pageview` events on `app://<bundleId>/<Screen>`
+ * URLs, so the dashboard's pages, paths and funnels work for apps as they do for
+ * websites. Events are queued on the device and sent in batches; a batch the API
+ * has not acknowledged stays queued and is retried, including after a restart.
+ */
+export class ThravicClient {
+  private env: Environment;
+  private trackingId = '';
+  private options: Resolved = { ...DEFAULTS };
+  private initialized = false;
+  private ready = false;
+  /** Calls made before storage has loaded, replayed in order once it has. */
+  private pending: Array<() => void> = [];
+
+  private visitorId = '';
+  private sessionId = '';
+  private sessionStart = 0;
+  private backgroundAt: number | null = null;
+  private currentScreen: string | null = null;
+  private optedOut = false;
+
+  private queue: CollectEvent[] = [];
+  private sending = false;
+  private retryAttempt = 0;
+  private retryScheduled = false;
+  private persistScheduled = false;
+  private timer: unknown = null;
+  private unsubscribeAppState: (() => void) | null = null;
+
+  constructor(env: Environment) {
+    this.env = env;
+  }
+
+  /** Start tracking. Call once, when the app starts; later calls are ignored. */
+  async init(trackingId: string, options: ThravicOptions = {}): Promise<void> {
+    if (this.initialized) return;
+    if (!trackingId) {
+      this.env.log('[Thravic] init needs your tracking ID, e.g. Thravic.init("TF-1A2B3C4D").');
+      return;
+    }
+    this.initialized = true;
+    this.trackingId = trackingId;
+    this.options = { ...DEFAULTS, ...stripUndefined(options) };
+    this.options.apiUrl = this.options.apiUrl.replace(/\/+$/, '');
+
+    const { storage } = this.env;
+    try {
+      this.optedOut = (await storage.getItem(OPT_OUT_KEY)) === '1';
+      this.visitorId = (await storage.getItem(VISITOR_KEY)) || '';
+      if (!this.visitorId) {
+        this.visitorId = generateId();
+        await storage.setItem(VISITOR_KEY, this.visitorId);
+      }
+      this.queue = parseQueue(await storage.getItem(QUEUE_KEY));
+    } catch (err) {
+      // Storage unavailable: track this run only.
+      this.visitorId = this.visitorId || generateId();
+      this.debug('storage unavailable', err);
+    }
+
+    this.startSession();
+    this.unsubscribeAppState = this.env.onAppStateChange((active) =>
+      active ? this.foreground() : this.background(),
+    );
+    this.timer = this.env.setInterval(
+      () => void this.flush(),
+      this.options.flushIntervalSeconds * 1000,
+    );
+
+    this.ready = true;
+    const pending = this.pending;
+    this.pending = [];
+    pending.forEach((call) => call());
+    void this.flush();
+  }
+
+  /** Record a screen view. Automatic with `trackNavigation`; call it yourself otherwise. */
+  screen(name: string, params?: Record<string, unknown>): void {
+    this.whenReady(() => {
+      const screen = String(name || '').trim().replace(/^\/+/, '');
+      if (!screen) return;
+      this.currentScreen = screen;
+      this.enqueue('pageview', params && Object.keys(params).length ? { params } : undefined);
+    });
+  }
+
+  /** Record a custom event, e.g. `track('purchase', { amount: 49 })`. */
+  track(event: string, properties?: Record<string, unknown>): void {
+    this.whenReady(() => {
+      if (!event) return;
+      this.enqueue('custom', { ...properties, event });
+    });
+  }
+
+  /** Link this device to your own user id. Sent as the web tracker sends it. */
+  identify(userId: string, traits?: Record<string, unknown>): void {
+    this.whenReady(() => {
+      if (!userId) return;
+      this.enqueue('custom', { ...traits, event: 'identify', userId: String(userId) });
+    });
+  }
+
+  /** Stop tracking this device, and drop anything not yet sent. Remembered across launches. */
+  optOut(): void {
+    this.optedOut = true;
+    this.queue = [];
+    void this.env.storage.setItem(OPT_OUT_KEY, '1').catch(() => undefined);
+    void this.env.storage.removeItem(QUEUE_KEY).catch(() => undefined);
+  }
+
+  /** Resume tracking after `optOut`. */
+  optIn(): void {
+    this.optedOut = false;
+    void this.env.storage.removeItem(OPT_OUT_KEY).catch(() => undefined);
+  }
+
+  isOptedOut(): boolean {
+    return this.optedOut;
+  }
+
+  /**
+   * Record a screen view whenever the focused route changes. Pass the ref from
+   * `createNavigationContainerRef()` / `useNavigationContainerRef()` (React
+   * Navigation or Expo Router). Returns a function that stops it.
+   */
+  trackNavigation(ref: NavigationRefLike): () => void {
+    let last: string | null = null;
+    const onState = () => {
+      if (ref.isReady && !ref.isReady()) return;
+      const route = ref.getCurrentRoute();
+      if (!route || route.name === last) return;
+      last = route.name;
+      this.screen(route.name);
+    };
+    const unsubscribe = ref.addListener('state', onState);
+    onState();
+    return unsubscribe;
+  }
+
+  /** Send everything queued now. Resolves when the attempt is done. */
+  async flush(): Promise<void> {
+    if (!this.ready || this.sending || this.optedOut || this.queue.length === 0) return;
+    this.sending = true;
+    const batch = this.queue.slice(0, MAX_BATCH);
+    const sent = new Set(batch.map((e) => e.eventId));
+    let more = false;
+    try {
+      const response = await this.env.fetch(
+        `${this.options.apiUrl}/api/collect/${encodeURIComponent(this.trackingId)}/batch`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ events: batch }),
+        },
+      );
+      // A 4xx other than 429 will never succeed: drop the batch rather than
+      // retrying it forever, as the web tracker does.
+      const rejected =
+        response.status >= 400 && response.status < 500 && response.status !== 429;
+      if (!response.ok && !rejected) throw new Error(`HTTP ${response.status}`);
+      if (rejected) this.debug(`batch rejected with ${response.status}`);
+
+      this.queue = this.queue.filter((e) => !sent.has(e.eventId));
+      this.retryAttempt = 0;
+      this.persist();
+      more = this.queue.length > 0;
+    } catch (err) {
+      this.debug('send failed, will retry', err);
+      this.scheduleRetry();
+    } finally {
+      this.sending = false;
+    }
+    if (more) await this.flush();
+  }
+
+  /** Stop timers and listeners. For tests and hot reload; apps never need it. */
+  shutdown(): void {
+    if (this.timer !== null) this.env.clearInterval(this.timer);
+    this.unsubscribeAppState?.();
+    this.timer = null;
+    this.unsubscribeAppState = null;
+  }
+
+  // ── Sessions ─────────────────────────────────────────────────────────────
+
+  private startSession(): void {
+    this.sessionId = generateId();
+    this.sessionStart = this.env.now();
+    this.backgroundAt = null;
+    this.enqueue('custom', { event: 'app_open' });
+  }
+
+  private background(): void {
+    if (!this.ready || this.backgroundAt !== null) return;
+    this.backgroundAt = this.env.now();
+    this.enqueue('session_end', {
+      duration: Math.round((this.backgroundAt - this.sessionStart) / 1000),
+      lastPage: this.screenUrl(),
+    });
+    void this.flush();
+  }
+
+  private foreground(): void {
+    if (!this.ready || this.backgroundAt === null) return;
+    const away = this.env.now() - this.backgroundAt;
+    this.backgroundAt = null;
+    if (away < this.options.sessionTimeoutMinutes * 60_000) return;
+
+    // Long enough away that this is a new visit; it starts on the screen in view.
+    this.startSession();
+    if (this.currentScreen) this.enqueue('pageview');
+  }
+
+  // ── Queue ────────────────────────────────────────────────────────────────
+
+  private whenReady(call: () => void): void {
+    if (this.ready) call();
+    else if (this.initialized) this.pending.push(call);
+    else this.env.log('[Thravic] Call Thravic.init before tracking.');
+  }
+
+  private screenUrl(): string {
+    const host = this.options.bundleId || 'app';
+    return `app://${host}/${encodeURI(this.currentScreen || '')}`;
+  }
+
+  private enqueue(type: CollectEvent['type'], data?: Record<string, unknown>): void {
+    if (this.optedOut) return;
+    const device = this.env.device();
+    const event: CollectEvent = {
+      eventId: generateId(),
+      type,
+      url: this.screenUrl(),
+      visitorId: this.visitorId,
+      sessionId: this.sessionId,
+      ...stripUndefined({
+        os: device.os,
+        osVersion: device.osVersion,
+        deviceModel: device.deviceModel,
+        appVersion: this.options.appVersion,
+        screenWidth: device.screenWidth,
+        screenHeight: device.screenHeight,
+        language: device.language,
+        data,
+      }),
+    };
+    this.queue.push(event);
+    if (this.queue.length > MAX_QUEUE) this.queue = this.queue.slice(-MAX_QUEUE);
+    this.debug(type, event.url, data ?? '');
+    this.persist();
+    if (this.queue.length >= FLUSH_AT) void this.flush();
+  }
+
+  /** Write the queue to storage, at most once a second. */
+  private persist(): void {
+    if (this.persistScheduled) return;
+    this.persistScheduled = true;
+    this.env.setTimeout(() => {
+      this.persistScheduled = false;
+      const write =
+        this.queue.length === 0
+          ? this.env.storage.removeItem(QUEUE_KEY)
+          : this.env.storage.setItem(QUEUE_KEY, JSON.stringify(this.queue));
+      void write.catch(() => undefined);
+    }, PERSIST_DELAY_MS);
+  }
+
+  private scheduleRetry(): void {
+    if (this.retryScheduled) return;
+    this.retryScheduled = true;
+    const delay = Math.min(1000 * 2 ** this.retryAttempt, MAX_RETRY_DELAY_MS);
+    this.retryAttempt += 1;
+    this.env.setTimeout(() => {
+      this.retryScheduled = false;
+      void this.flush();
+    }, delay);
+  }
+
+  private debug(...args: unknown[]): void {
+    if (this.options.debug) this.env.log('[Thravic]', ...args);
+  }
+}
+
+function parseQueue(raw: string | null): CollectEvent[] {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((e) => e && typeof e === 'object' && typeof e.eventId === 'string')
+      .slice(-MAX_QUEUE);
+  } catch {
+    return [];
+  }
+}
+
+function stripUndefined<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, v]) => v !== undefined && v !== null && v !== ''),
+  ) as Partial<T>;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+import { ThravicClient } from './client';
+import { reactNativeEnvironment } from './react-native';
+
+export { ThravicClient } from './client';
+export type {
+  CollectEvent,
+  DeviceInfo,
+  Environment,
+  NavigationRefLike,
+  Storage,
+  ThravicOptions,
+} from './types';
+
+/**
+ * Thravic for React Native.
+ *
+ * ```ts
+ * import { Thravic } from '@thravic/react-native';
+ *
+ * Thravic.init('TF-1A2B3C4D', { appVersion: '1.4.0', bundleId: 'com.acme.shop' });
+ * Thravic.trackNavigation(navigationRef);     // screen views, automatically
+ * Thravic.track('purchase', { amount: 49 });  // your own events
+ * ```
+ */
+export const Thravic = new ThravicClient(reactNativeEnvironment);
+
+export default Thravic;

package/src/react-native.ts

@@ -0,0 +1,71 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { AppState, Dimensions, Platform } from 'react-native';
+
+import type { DeviceInfo, Environment } from './types';
+
+type Constants = {
+  Release?: string;
+  Model?: string;
+  Manufacturer?: string;
+  osVersion?: string;
+  interfaceIdiom?: string;
+};
+
+function language(): string | undefined {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+    return undefined;
+  }
+}
+
+/** What React Native itself knows about the device, with no native module to install. */
+function device(): DeviceInfo {
+  const constants = (Platform.constants || {}) as Constants;
+  const screen = Dimensions.get('screen');
+  const base = {
+    screenWidth: Math.round(screen.width),
+    screenHeight: Math.round(screen.height),
+    language: language(),
+  };
+
+  if (Platform.OS === 'android') {
+    return {
+      ...base,
+      os: 'Android',
+      // `Platform.Version` is the API level on Android; Release is "14".
+      osVersion: constants.Release || String(Platform.Version),
+      deviceModel: [constants.Manufacturer, constants.Model].filter(Boolean).join(' ') || undefined,
+    };
+  }
+  if (Platform.OS === 'ios') {
+    return {
+      ...base,
+      os: 'iOS',
+      osVersion: String(Platform.Version),
+      // iOS does not expose the model without a native module.
+      deviceModel: constants.interfaceIdiom === 'pad' ? 'iPad' : 'iPhone',
+    };
+  }
+  return { ...base, os: Platform.OS };
+}
+
+export const reactNativeEnvironment: Environment = {
+  storage: AsyncStorage,
+  device,
+  fetch: (...args) => fetch(...args),
+  now: () => Date.now(),
+  onAppStateChange(listener) {
+    // 'inactive' is iOS passing through (Control Center, a call banner): not a
+    // departure. Only 'background' ends the visit and only 'active' resumes it.
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') listener(true);
+      else if (state === 'background') listener(false);
+    });
+    return () => subscription.remove();
+  },
+  setInterval: (fn, ms) => setInterval(fn, ms),
+  clearInterval: (handle) => clearInterval(handle as ReturnType<typeof setInterval>),
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  log: (...args) => console.warn(...args),
+};

package/src/types.ts

@@ -0,0 +1,76 @@
+/** Options for `Thravic.init`. */
+export interface ThravicOptions {
+  /** Where the Thravic API lives. The dashboard's install snippet fills this in. */
+  apiUrl?: string;
+  /** Your app's version, e.g. `Application.nativeApplicationVersion` (Expo) or
+   *  `DeviceInfo.getVersion()` (react-native-device-info). Shown under Versions. */
+  appVersion?: string;
+  /** Your app's bundle ID, used as the host of screen URLs (`app://<bundleId>/Home`). */
+  bundleId?: string;
+  /** Minutes in the background after which the next open starts a new session. */
+  sessionTimeoutMinutes?: number;
+  /** Seconds between automatic sends of queued events. */
+  flushIntervalSeconds?: number;
+  /** Log what the SDK does to the console. */
+  debug?: boolean;
+}
+
+/** One event as `POST /api/collect/{trackingId}/batch` takes it. */
+export interface CollectEvent {
+  eventId: string;
+  type: 'pageview' | 'custom' | 'session_end';
+  url: string;
+  visitorId: string;
+  sessionId: string;
+  screenWidth?: number;
+  screenHeight?: number;
+  language?: string;
+  os?: string;
+  osVersion?: string;
+  appVersion?: string;
+  deviceModel?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  data?: Record<string, unknown>;
+}
+
+/** What the device reports about itself. */
+export interface DeviceInfo {
+  os: string;
+  osVersion?: string;
+  deviceModel?: string;
+  screenWidth?: number;
+  screenHeight?: number;
+  language?: string;
+}
+
+/** Key-value storage that survives app restarts (AsyncStorage's shape). */
+export interface Storage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+/** Everything the client needs from its platform, so it can run outside React Native. */
+export interface Environment {
+  storage: Storage;
+  device: () => DeviceInfo;
+  fetch: typeof fetch;
+  now: () => number;
+  /** Calls `listener(true)` when the app comes to the foreground and `listener(false)`
+   *  when it leaves; returns an unsubscribe. */
+  onAppStateChange: (listener: (active: boolean) => void) => () => void;
+  setInterval: (fn: () => void, ms: number) => unknown;
+  clearInterval: (handle: unknown) => void;
+  setTimeout: (fn: () => void, ms: number) => unknown;
+  log: (...args: unknown[]) => void;
+}
+
+/** The parts of a React Navigation container ref the screen tracker uses. Expo
+ *  Router's `useNavigationContainerRef()` returns one too. */
+export interface NavigationRefLike {
+  addListener(event: 'state', listener: () => void): () => void;
+  getCurrentRoute(): { name: string; params?: object } | undefined;
+  isReady?(): boolean;
+}