@statsviewer/react-native

Privacy-conscious StatsViewer analytics for React Native and Expo. The package uses JavaScript only: there is no custom native module, config plugin, or build step.

Install

Install the SDK and a storage implementation in the application package:

npm install @statsviewer/react-native @react-native-async-storage/async-storage

@react-native-async-storage/async-storage is not bundled. Expo and React Native applications may instead provide any asynchronous storage object with getItem, setItem, and removeItem methods.

Configure

Configure once when the application starts. Each platform selects its own StatsViewer project and publishable client key.

import AsyncStorage from '@react-native-async-storage/async-storage';
import StatsViewer from '@statsviewer/react-native';

await StatsViewer.configure({
    endpoint: 'https://api.statsviewer.com/v1',
    storage: AsyncStorage,
    ios: {
        projectId: 'proj_ios',
        clientKey: 'client_ios',
    },
    android: {
        projectId: 'proj_android',
        clientKey: 'client_android',
    },
    context: {
        app_version: '1.4.0',
        app_build: '72',
    },
});

The SDK uses React Native's global fetch. It automatically flushes the persistent bounded queue when AppState moves to inactive or background.

Track

await StatsViewer.screen('Home');
await StatsViewer.track('article_opened', { article_id: 'intro' });
await StatsViewer.goal('trial_started', { plan: 'starter' });
await StatsViewer.identify('account_123', { account_type: 'business' });
await StatsViewer.flush();

Screen tracking is explicit so it works with any navigation library. Call screen() from the navigation container's route-change callback.

Consent

Pass consent: false when analytics consent has not been granted:

await StatsViewer.configure({
    storage: AsyncStorage,
    consent: false,
    ios: { projectId: 'proj_ios', clientKey: 'client_ios' },
    android: { projectId: 'proj_android', clientKey: 'client_android' },
});

await StatsViewer.setConsent(true);
await StatsViewer.screen('Home');

No install, session, or event identifier is created while consent is denied. Revoking consent clears the pending queue and persisted analytics identifiers.

Behaviour

• A random install identifier persists through the supplied storage adapter.
• Sessions rotate after 30 minutes without tracked activity.
• Every new session emits session_start before the requested event.
• Events use /v1/batch with the selected platform's client key.
• Retryable network failures, 429, and server errors use bounded retries. Retry-After is honoured up to 30 seconds.
• The persistent queue is capped at 100 events by default.
• Native envelopes omit url, path, title, and referrer.
• Context identifies this SDK with sdk_name: "statsviewer-react-native" and sdk_version: "0.1.0".
• identify() accepts namespaced opaque application IDs of at most 128 characters. Email addresses, phone-like numeric values, human-readable names, UUID-shaped device IDs, and advertising/device ID labels are rejected. Use an application namespace such as user_, account_, or customer_.
• Sensitive property names are removed before transport and are also checked by the StatsViewer collector.

Call StatsViewer.dispose() when tearing down an independently mounted application root or during development hot reload. It removes the AppState listener and attempts a final flush.