@nexly/react-native 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @nexly/react-native
+
+React Native SDK for Nexly. Implements [`NexlyBase`](https://www.npmjs.com/package/@nexly/core) with:
+
+- `fetch({ keepalive: true })` transport,
+- visitor/session IDs persisted via `@react-native-async-storage/async-storage`,
+- device metadata via `Platform`, `Dimensions`, `PixelRatio`,
+- engagement tracking driven by `AppState` (active seconds, heartbeat, `session_ping`).
+
+## Install
+
+```bash
+npm install @nexly/react-native @react-native-async-storage/async-storage
+```
+
+`react` and `react-native` must already be installed in your app.
+
+## Usage
+
+```tsx
+import { NexlyProvider, useNexlyClient } from '@nexly/react-native'
+
+export default function App() {
+  return (
+    <NexlyProvider appId="your-app-id" ingestKey="your-ingest-key" autoEngagement initialScreen="Home">
+      <Root />
+    </NexlyProvider>
+  )
+}
+
+function Root() {
+  const client = useNexlyClient()
+
+  useEffect(() => {
+    client?.screenview('Home')
+  }, [client])
+
+  return (
+    <Button
+      title="Upgrade"
+      onPress={() => client?.event({ name: 'upgrade_clicked', type: 'custom', data: { plan: 'pro' } })}
+    />
+  )
+}
+```
+
+## Screens / paths
+
+React Native has no URL, so Nexly uses a manual **screen name** instead:
+
+- `client.setScreen('Settings')` — updates the screen used as `path` on future events.
+- `client.screenview('Settings')` — sets the screen and sends a `pageview`.
+
+Hook it up to your router of choice. Example with `@react-navigation/native`:
+
+```tsx
+<NavigationContainer
+  onStateChange={(state) => {
+    const route = state?.routes[state.index ?? 0]
+    if (route) client?.screenview(route.name)
+  }}
+>
+  ...
+</NavigationContainer>
+```
+
+## Engagement
+
+`autoEngagement` attaches an `AppState` listener that:
+
+- Increments `active_seconds` only while the app is foregrounded.
+- Sends a `heartbeat` every 60 s (lifecycle event for realtime dashboards).
+- Sends `session_ping` when the app goes to background, and `session_end` on provider unmount.
+
+No scroll/click tracking (those are DOM-only); if you want tap analytics, send custom `engagement` events yourself.

package/dist/device-meta.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Session-stable device metadata: OS, screen, locale, timezone.
+ * Collected once per session and sent as `session_context`.
+ */
+export declare function collectSessionMeta(): Record<string, unknown>;
+/**
+ * Per-event volatile metadata: visitor/session IDs (from cache) and current screen.
+ * `path` is set by the client from the current screen name.
+ */
+export declare function collectEventMeta(): Record<string, unknown>;
+//# sourceMappingURL=device-meta.d.ts.map

package/dist/device-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-meta.d.ts","sourceRoot":"","sources":["../src/device-meta.ts"],"names":[],"mappings":"AA2BA;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmC5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO1D"}

package/dist/device-meta.js

@@ -0,0 +1,69 @@
+import { Dimensions, NativeModules, PixelRatio, Platform } from 'react-native';
+import { getCachedSessionId, getCachedVisitorId } from './session.js';
+function safe(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return undefined;
+    }
+}
+function filterEmpty(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== '' && !(Array.isArray(v) && v.length === 0)));
+}
+function resolveLocale() {
+    const settings = NativeModules?.SettingsManager?.settings;
+    const iosLocale = settings?.AppleLocale ||
+        (Array.isArray(settings?.AppleLanguages) ? settings.AppleLanguages[0] : undefined);
+    const androidLocale = NativeModules?.I18nManager?.localeIdentifier;
+    const intlLocale = safe(() => new Intl.Locale(Intl.DateTimeFormat().resolvedOptions().locale).toString());
+    return iosLocale || androidLocale || intlLocale;
+}
+/**
+ * Session-stable device metadata: OS, screen, locale, timezone.
+ * Collected once per session and sent as `session_context`.
+ */
+export function collectSessionMeta() {
+    const out = {};
+    out.platform = safe(() => Platform.OS);
+    out.os_version = safe(() => String(Platform.Version));
+    const screen = safe(() => Dimensions.get('screen'));
+    if (screen) {
+        out.screen_width = Math.round(screen.width);
+        out.screen_height = Math.round(screen.height);
+    }
+    const window_ = safe(() => Dimensions.get('window'));
+    if (window_) {
+        out.viewport_width = Math.round(window_.width);
+        out.viewport_height = Math.round(window_.height);
+    }
+    out.device_pixel_ratio = safe(() => PixelRatio.get());
+    out.font_scale = safe(() => PixelRatio.getFontScale());
+    const locale = resolveLocale();
+    if (locale) {
+        out.language = locale;
+        out.locale = locale;
+    }
+    out.timezone = safe(() => Intl.DateTimeFormat().resolvedOptions().timeZone);
+    out.is_tv = safe(() => Platform.isTV);
+    out.user_agent = safe(() => {
+        const os = Platform.OS;
+        const ver = String(Platform.Version);
+        return `nexly-react-native/${os} ${ver}`;
+    });
+    return filterEmpty(out);
+}
+/**
+ * Per-event volatile metadata: visitor/session IDs (from cache) and current screen.
+ * `path` is set by the client from the current screen name.
+ */
+export function collectEventMeta() {
+    const out = {};
+    const visitorId = getCachedVisitorId();
+    const sessionId = getCachedSessionId();
+    if (visitorId)
+        out.visitor_id = visitorId;
+    if (sessionId)
+        out.session_id = sessionId;
+    return filterEmpty(out);
+}

package/dist/engagement.d.ts

@@ -0,0 +1,13 @@
+import { type IngestCredentials } from '@nexly/core';
+type EngagementCreds = {
+    collectUrl: string;
+} & IngestCredentials;
+type StopFn = () => void;
+/**
+ * React Native engagement tracking: active-seconds counter driven by `AppState`
+ * (ticks only while the app is `active`), plus a 60s heartbeat and
+ * a `session_ping` when the app goes to background.
+ */
+export declare function startEngagementTracking(creds: EngagementCreds): StopFn;
+export {};
+//# sourceMappingURL=engagement.d.ts.map

package/dist/engagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engagement.d.ts","sourceRoot":"","sources":["../src/engagement.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAQzE,KAAK,eAAe,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,CAAA;AAoBjE,KAAK,MAAM,GAAG,MAAM,IAAI,CAAA;AAExB;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAyCtE"}

package/dist/engagement.js

@@ -0,0 +1,62 @@
+import { AppState } from 'react-native';
+import { buildCollectPayload } from '@nexly/core';
+import { collectEventMeta, collectSessionMeta } from './device-meta.js';
+import { sendPayloadFetch } from './transport.js';
+import { touchSession } from './session.js';
+const ACTIVE_TICK_MS = 1_000;
+const KEEPALIVE_INTERVAL_MS = 60_000;
+function send(creds, eventName, eventType, data, sessionContext) {
+    const payload = buildCollectPayload({
+        credentials: { appId: creds.appId, apiToken: creds.apiToken },
+        eventName,
+        eventType,
+        context: collectEventMeta(),
+        data,
+        sessionContext,
+    });
+    sendPayloadFetch(creds.collectUrl, payload);
+}
+/**
+ * React Native engagement tracking: active-seconds counter driven by `AppState`
+ * (ticks only while the app is `active`), plus a 60s heartbeat and
+ * a `session_ping` when the app goes to background.
+ */
+export function startEngagementTracking(creds) {
+    let activeSeconds = 0;
+    let sessionContextSent = false;
+    function getSessionContextOnce() {
+        if (sessionContextSent)
+            return undefined;
+        sessionContextSent = true;
+        return collectSessionMeta();
+    }
+    const tickId = setInterval(() => {
+        if (AppState.currentState === 'active')
+            activeSeconds++;
+    }, ACTIVE_TICK_MS);
+    function sendKeepalive() {
+        if (AppState.currentState !== 'active')
+            return;
+        send(creds, 'heartbeat', 'lifecycle', { active_seconds: activeSeconds }, getSessionContextOnce());
+    }
+    sendKeepalive();
+    const keepaliveId = setInterval(sendKeepalive, KEEPALIVE_INTERVAL_MS);
+    const sub = AppState.addEventListener('change', (next) => {
+        if (next === 'background' || next === 'inactive') {
+            if (activeSeconds > 0) {
+                send(creds, 'session_ping', 'lifecycle', { active_seconds: activeSeconds });
+            }
+        }
+        if (next === 'active') {
+            void touchSession();
+        }
+    });
+    return () => {
+        clearInterval(tickId);
+        clearInterval(keepaliveId);
+        sub.remove();
+        if (activeSeconds > 0) {
+            send(creds, 'session_end', 'lifecycle', { active_seconds: activeSeconds });
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * React Native Nexly SDK (public API).
+ */
+export { Nexly } from './nexly.js';
+export { NexlyProvider, useNexlyClient, type NexlyProviderProps } from './nexly-provider.js';
+export { collectEventMeta, collectSessionMeta } from './device-meta.js';
+export { prewarmIds, touchSession, getCachedSessionId, getCachedVisitorId } from './session.js';
+export type { NexlyEventInput, NexlyEventType, NexlyInit } from '@nexly/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC5F,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC/F,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * React Native Nexly SDK (public API).
+ */
+export { Nexly } from './nexly.js';
+export { NexlyProvider, useNexlyClient } from './nexly-provider.js';
+export { collectEventMeta, collectSessionMeta } from './device-meta.js';
+export { prewarmIds, touchSession, getCachedSessionId, getCachedVisitorId } from './session.js';

package/dist/nexly-provider.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+import { Nexly } from './nexly.js';
+export type NexlyProviderProps = {
+    /** Override the ingest endpoint. Defaults to the Nexly production gateway. */
+    collectUrl?: string;
+    appId: string;
+    /** Ingest API token (maps to `key` on {@link Nexly}). Not named `key` — reserved in React. */
+    ingestKey: string;
+    /** Attach AppState-driven engagement tracking (active seconds, heartbeat, session_ping). */
+    autoEngagement?: boolean;
+    /**
+     * Initial screen name used as `path` for events sent before any `setScreen()` call.
+     * Update it later with `client.setScreen(name)` or `client.screenview(name)`.
+     */
+    initialScreen?: string;
+    children: ReactNode;
+};
+/**
+ * Initializes the Nexly client asynchronously (AsyncStorage prewarm) and exposes it
+ * via context. `useNexlyClient()` returns `null` until init completes or if credentials are missing.
+ */
+export declare function NexlyProvider({ collectUrl, appId, ingestKey, autoEngagement, initialScreen, children, }: NexlyProviderProps): import("react/jsx-runtime").JSX.Element;
+/** Returns the configured {@link Nexly} client, or `null` if not yet ready / credentials missing. */
+export declare function useNexlyClient(): Nexly | null;
+//# sourceMappingURL=nexly-provider.d.ts.map

package/dist/nexly-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexly-provider.d.ts","sourceRoot":"","sources":["../src/nexly-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAkD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AACtF,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAIlC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAA;IACjB,4FAA4F;IAC5F,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAC5B,UAAU,EACV,KAAK,EACL,SAAS,EACT,cAAsB,EACtB,aAAa,EACb,QAAQ,GACT,EAAE,kBAAkB,2CA6BpB;AAED,qGAAqG;AACrG,wBAAgB,cAAc,IAAI,KAAK,GAAG,IAAI,CAE7C"}

package/dist/nexly-provider.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useState } from 'react';
+import { Nexly } from './nexly.js';
+const NexlyClientContext = createContext(null);
+/**
+ * Initializes the Nexly client asynchronously (AsyncStorage prewarm) and exposes it
+ * via context. `useNexlyClient()` returns `null` until init completes or if credentials are missing.
+ */
+export function NexlyProvider({ collectUrl, appId, ingestKey, autoEngagement = false, initialScreen, children, }) {
+    const [client, setClient] = useState(null);
+    useEffect(() => {
+        const id = (appId ?? '').trim();
+        const k = (ingestKey ?? '').trim();
+        if (!id || !k) {
+            if (!id)
+                console.warn('[Nexly] Missing appId — tracking is disabled.');
+            if (!k)
+                console.warn('[Nexly] Missing ingestKey — tracking is disabled.');
+            setClient(null);
+            return;
+        }
+        let cancelled = false;
+        Nexly.init({ collectUrl, appId: id, key: k }).then((instance) => {
+            if (cancelled)
+                return;
+            if (initialScreen)
+                instance.setScreen(initialScreen);
+            setClient(instance);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [collectUrl, appId, ingestKey, initialScreen]);
+    useEffect(() => {
+        if (!autoEngagement || !client)
+            return;
+        return client.startEngagement();
+    }, [autoEngagement, client]);
+    return _jsx(NexlyClientContext.Provider, { value: client, children: children });
+}
+/** Returns the configured {@link Nexly} client, or `null` if not yet ready / credentials missing. */
+export function useNexlyClient() {
+    return useContext(NexlyClientContext);
+}

package/dist/nexly.d.ts

@@ -0,0 +1,29 @@
+import { NexlyBase, type NexlyInit } from '@nexly/core';
+/**
+ * React Native Nexly client. Implements transport via `fetch({ keepalive: true })`
+ * and metadata via `Platform` / `Dimensions` / `AsyncStorage`.
+ *
+ * Because `AsyncStorage` is asynchronous, visitor/session IDs are prewarmed during
+ * {@link Nexly.init} before the first event is sent.
+ */
+export declare class Nexly extends NexlyBase {
+    private currentScreen;
+    /**
+     * Creates (or replaces) the singleton **and awaits ID prewarming**.
+     * `NexlyProvider` awaits this before exposing a client via context.
+     */
+    static init(options: NexlyInit): Promise<Nexly>;
+    /** Returns the singleton, or `null` if not yet initialized. */
+    static getInstance(): Nexly | null;
+    constructor(init: NexlyInit);
+    /** Sets the current screen name used as `path` for subsequent events. */
+    setScreen(name: string): void;
+    /** Convenience: set screen and send a pageview in one call. */
+    screenview(name: string): boolean;
+    protected transport(payload: Record<string, unknown>): boolean;
+    protected collectEventContext(): Record<string, unknown>;
+    protected collectSessionContext(): Record<string, unknown>;
+    getDefaultPath(): string;
+    startEngagement(): () => void;
+}
+//# sourceMappingURL=nexly.d.ts.map

package/dist/nexly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexly.d.ts","sourceRoot":"","sources":["../src/nexly.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAMvD;;;;;;GAMG;AACH,qBAAa,KAAM,SAAQ,SAAS;IAClC,OAAO,CAAC,aAAa,CAAM;IAE3B;;;OAGG;WACU,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC;IASrD,+DAA+D;IAC/D,MAAM,CAAC,WAAW,IAAI,KAAK,GAAG,IAAI;gBAItB,IAAI,EAAE,SAAS;IAI3B,yEAAyE;IACzE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK7B,+DAA+D;IAC/D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;cAKd,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;cAIpD,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;cAI9C,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI1D,cAAc,IAAI,MAAM;IAIxB,eAAe,IAAI,MAAM,IAAI;CAQvC"}

package/dist/nexly.js

@@ -0,0 +1,65 @@
+import { NexlyBase } from '@nexly/core';
+import { collectEventMeta, collectSessionMeta } from './device-meta.js';
+import { startEngagementTracking } from './engagement.js';
+import { prewarmIds } from './session.js';
+import { sendPayloadFetch } from './transport.js';
+/**
+ * React Native Nexly client. Implements transport via `fetch({ keepalive: true })`
+ * and metadata via `Platform` / `Dimensions` / `AsyncStorage`.
+ *
+ * Because `AsyncStorage` is asynchronous, visitor/session IDs are prewarmed during
+ * {@link Nexly.init} before the first event is sent.
+ */
+export class Nexly extends NexlyBase {
+    currentScreen = '/';
+    /**
+     * Creates (or replaces) the singleton **and awaits ID prewarming**.
+     * `NexlyProvider` awaits this before exposing a client via context.
+     */
+    static async init(options) {
+        const instance = new Nexly(options);
+        Nexly.setInstance(instance);
+        if (instance.appId && instance.key) {
+            await prewarmIds();
+        }
+        return instance;
+    }
+    /** Returns the singleton, or `null` if not yet initialized. */
+    static getInstance() {
+        return NexlyBase.getInstance() ?? null;
+    }
+    constructor(init) {
+        super(init);
+    }
+    /** Sets the current screen name used as `path` for subsequent events. */
+    setScreen(name) {
+        const trimmed = (name ?? '').trim();
+        this.currentScreen = trimmed || '/';
+    }
+    /** Convenience: set screen and send a pageview in one call. */
+    screenview(name) {
+        this.setScreen(name);
+        return this.pageview(this.currentScreen);
+    }
+    transport(payload) {
+        return sendPayloadFetch(this.collectUrl, payload);
+    }
+    collectEventContext() {
+        return collectEventMeta();
+    }
+    collectSessionContext() {
+        return collectSessionMeta();
+    }
+    getDefaultPath() {
+        return this.currentScreen;
+    }
+    startEngagement() {
+        if (this.disabled)
+            return () => { };
+        return startEngagementTracking({
+            collectUrl: this.collectUrl,
+            appId: this.appId,
+            apiToken: this.key,
+        });
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Loads (or generates) the persistent visitor ID and current session ID from storage.
+ * Call once before sending any event. Subsequent calls are idempotent.
+ */
+export declare function prewarmIds(): Promise<{
+    visitorId: string;
+    sessionId: string;
+}>;
+/** Touch the session timestamp; if the session expired, roll a new session ID. */
+export declare function touchSession(): Promise<void>;
+export declare function getCachedVisitorId(): string | null;
+export declare function getCachedSessionId(): string | null;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAwBA;;;GAGG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAuBpF;AAED,kFAAkF;AAClF,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAYlD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAElD"}

package/dist/session.js

@@ -0,0 +1,63 @@
+import { storageGet, storageSet } from './storage.js';
+const VISITOR_KEY = 'trk_visitor_id';
+const SESSION_KEY = 'trk_session_id';
+const SESSION_TS_KEY = 'trk_session_ts';
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+function generateId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+/** In-memory cache prewarmed by {@link prewarmIds}; safe to read sync after init. */
+let cachedVisitorId = null;
+let cachedSessionId = null;
+/**
+ * Loads (or generates) the persistent visitor ID and current session ID from storage.
+ * Call once before sending any event. Subsequent calls are idempotent.
+ */
+export async function prewarmIds() {
+    const now = Date.now();
+    let visitorId = cachedVisitorId ?? (await storageGet(VISITOR_KEY));
+    if (!visitorId) {
+        visitorId = generateId();
+        await storageSet(VISITOR_KEY, visitorId);
+    }
+    cachedVisitorId = visitorId;
+    const [existing, tsRaw] = await Promise.all([storageGet(SESSION_KEY), storageGet(SESSION_TS_KEY)]);
+    const lastTs = tsRaw ? Number(tsRaw) : 0;
+    let sessionId;
+    if (existing && lastTs && now - lastTs < SESSION_TIMEOUT_MS) {
+        sessionId = existing;
+    }
+    else {
+        sessionId = generateId();
+        await storageSet(SESSION_KEY, sessionId);
+    }
+    await storageSet(SESSION_TS_KEY, String(now));
+    cachedSessionId = sessionId;
+    return { visitorId, sessionId };
+}
+/** Touch the session timestamp; if the session expired, roll a new session ID. */
+export async function touchSession() {
+    const now = Date.now();
+    const tsRaw = await storageGet(SESSION_TS_KEY);
+    const lastTs = tsRaw ? Number(tsRaw) : 0;
+    if (cachedSessionId && lastTs && now - lastTs < SESSION_TIMEOUT_MS) {
+        await storageSet(SESSION_TS_KEY, String(now));
+        return;
+    }
+    const id = generateId();
+    cachedSessionId = id;
+    await storageSet(SESSION_KEY, id);
+    await storageSet(SESSION_TS_KEY, String(now));
+}
+export function getCachedVisitorId() {
+    return cachedVisitorId;
+}
+export function getCachedSessionId() {
+    return cachedSessionId;
+}

package/dist/storage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Thin wrapper around `@react-native-async-storage/async-storage` with an in-memory fallback
+ * so the SDK does not hard-crash if the peer dependency is missing (e.g. in tests).
+ */
+export declare function storageGet(key: string): Promise<string | null>;
+export declare function storageSet(key: string, value: string): Promise<void>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8CH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOpE;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1E"}

package/dist/storage.js

@@ -0,0 +1,56 @@
+/**
+ * Thin wrapper around `@react-native-async-storage/async-storage` with an in-memory fallback
+ * so the SDK does not hard-crash if the peer dependency is missing (e.g. in tests).
+ */
+let storage = null;
+let loadAttempted = false;
+const memory = new Map();
+const memoryStorage = {
+    async getItem(key) {
+        return memory.get(key) ?? null;
+    },
+    async setItem(key, value) {
+        memory.set(key, value);
+    },
+    async removeItem(key) {
+        memory.delete(key);
+    },
+};
+async function loadAsyncStorage() {
+    if (storage)
+        return storage;
+    if (loadAttempted)
+        return memoryStorage;
+    loadAttempted = true;
+    try {
+        const mod = (await import('@react-native-async-storage/async-storage'));
+        if (mod?.default) {
+            storage = mod.default;
+            return storage;
+        }
+    }
+    catch {
+        // peer dep not installed — fall through
+    }
+    console.warn('[Nexly] @react-native-async-storage/async-storage is not installed; visitor/session IDs will not persist.');
+    storage = memoryStorage;
+    return storage;
+}
+export async function storageGet(key) {
+    const s = await loadAsyncStorage();
+    try {
+        return await s.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+export async function storageSet(key, value) {
+    const s = await loadAsyncStorage();
+    try {
+        await s.setItem(key, value);
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Fire-and-forget JSON POST to the collector. Uses `fetch` with `keepalive: true`
+ * so requests survive app backgrounding on supported runtimes; errors are swallowed
+ * (analytics must not crash the host app).
+ */
+export declare function sendPayloadFetch(url: string, payload: Record<string, unknown>): boolean;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAavF"}

package/dist/transport.js

@@ -0,0 +1,21 @@
+/**
+ * Fire-and-forget JSON POST to the collector. Uses `fetch` with `keepalive: true`
+ * so requests survive app backgrounding on supported runtimes; errors are swallowed
+ * (analytics must not crash the host app).
+ */
+export function sendPayloadFetch(url, payload) {
+    if (!url)
+        return false;
+    try {
+        void fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+            keepalive: true,
+        }).catch(() => { });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nexly/react-native",
+  "version": "0.9.0",
+  "description": "React Native bindings for Nexly: fetch transport, AsyncStorage IDs, AppState engagement on top of @nexly/core",
+  "license": "MIT",
+  "keywords": [
+    "nexly",
+    "react-native",
+    "analytics",
+    "tracking",
+    "mobile",
+    "ingest"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.21.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "dependencies": {
+    "@nexly/core": "0.9.0"
+  },
+  "devDependencies": {
+    "@react-native-async-storage/async-storage": "^2.1.2",
+    "@types/react": "^19.2.14",
+    "react": "^19.1.0",
+    "react-native": "^0.76.5",
+    "typescript": "~6.0.2"
+  }
+}