Layers React Native SDK

@layers/react-native is the Layers analytics SDK for React Native apps. It provides event tracking, screen tracking, user identification, App Tracking Transparency (ATT), SKAdNetwork (SKAN), deep link handling, clipboard-based deferred deep links, consent management, and automatic lifecycle and connectivity handling.

Use this package for bare React Native projects. For Expo managed workflow projects, use @layers/expo instead.

Requirements

• React Native 0.70.0+
• React 18.0+
• iOS 14.0+ / Android API 21+

Installation

npm install @layers/react-native
# or
yarn add @layers/react-native

Recommended Peer Dependencies

npm install @react-native-async-storage/async-storage @react-native-community/netinfo

These are optional but strongly recommended:

• @react-native-async-storage/async-storage (>=1.21.0) -- Enables persistent event storage across app restarts. Without it, events are stored in memory only.
• @react-native-community/netinfo (>=11.0.0) -- Enables automatic flush when the device reconnects to the network.
• @react-native-clipboard/clipboard (>=1.13.0) -- Enables clipboard attribution for iOS deferred deep links.

AsyncStorage version compatibility

| @react-native-async-storage/async-storage | Supported by @layers/react-native | | ------------------------------------------- | ----------------------------------- | | 1.21.0 -- 1.x | All versions | | 2.x | All versions | | 3.x | 3.2.10 and newer |

async-storage 3.x has been npm's latest since its release, so npm install @react-native-async-storage/async-storage installs it by default. Two separate defects have affected that combination; both are fixed in @layers/react-native 3.2.10.

Batch read (fixed in 3.2.8). async-storage 3.0.0 replaced its batch read (multiGet) with a new one (getMany). SDK versions before 3.2.8 called the old name unconditionally, so on async-storage 3.x the SDK saved state it could never read back: every launch came up with a fresh anonymous_id and device_id, re-sent the first-open event, and reported session_number as 1 forever. Writes kept succeeding throughout, which is why the app looked healthy.

Identity split on offline-first installs (3.2.8 and 3.2.9, fixed in 3.2.10). async-storage 3.0.0 also dropped the serial executor v1/v2 ran every storage operation through, so two writes to the same key issued in the same tick can commit in either order. The SDK wrote its identity record twice while starting up, and when the wrong one committed last, an install whose first launch had no network could come back under a second anonymous_id and device_id with a duplicate first-open event -- measured on roughly one in four such installs. 3.2.10 writes the record once, with the identity its events actually carry, so no commit order can produce a different one.

Both defects are fixed as of 3.2.10, so async-storage 3.x needs no version pin on this release. Earlier @layers/react-native releases still do.

Expo managed projects are unaffected by either: npx expo install picks the async-storage version pinned to your Expo SDK, which is 2.x.

iOS Setup

cd ios && pod install

If your app calls requestTrackingPermission() or requestTrackingAuthorization(), add a non-empty NSUserTrackingUsageDescription to the app's Info.plist:

<key>NSUserTrackingUsageDescription</key>
<string>Your app-specific explanation for requesting tracking permission.</string>

Without this key, the SDK rejects the request with ATT_USAGE_DESCRIPTION_MISSING and does not invoke Apple's ATT prompt.

Quick Start

import { LayersReactNative } from '@layers/react-native';

// Create and initialize
const layers = new LayersReactNative({
  appId: 'your-app-id',
  environment: 'production'
});
await layers.init();

// Track events
layers.track('button_tapped', { button_name: 'signup' });

// Track screen views
layers.screen('Home');

// Identify users
layers.setAppUserId('user_123');

Configuration

LayersRNConfig

interface LayersRNConfig {
  appId: string;
  environment: 'development' | 'staging' | 'production';
  appUserId?: string;
  enableDebug?: boolean; // default: false
  baseUrl?: string; // default: "https://in.layers.com"
  flushIntervalMs?: number; // default: 30000
  flushThreshold?: number; // default: 10
  maxQueueSize?: number; // default: 1000
  autoTrackAppOpen?: boolean; // default: true
  autoTrackDeepLinks?: boolean; // default: true
  autoTrackExceptions?: boolean; // default: true
  appState?: AppStateLike; // default: the SDK's own require('react-native').AppState
}

| Option | Type | Default | Description | | --------------------- | -------------- | ------------------------- | ------------------------------------------------ | | appId | string | required | Your Layers application identifier. | | environment | Environment | required | 'development', 'staging', or 'production'. | | appUserId | string | undefined | Optional user ID to set at construction time. | | enableDebug | boolean | false | Enable verbose console logging. | | baseUrl | string | "https://in.layers.com" | Custom ingest API endpoint. | | flushIntervalMs | number | 30000 | Automatic flush interval in milliseconds. | | flushThreshold | number | 10 | Queue size that triggers an automatic flush. | | maxQueueSize | number | 1000 | Maximum events in the queue before dropping. | | autoTrackAppOpen | boolean | true | Automatically track app_open on init. | | autoTrackDeepLinks | boolean | true | Automatically track deep_link_opened events. | | autoTrackExceptions | boolean | true | Track uncaught JS errors as $exception. | | appState | AppStateLike | SDK's own AppState | Your app's AppState. See below. |

One copy of react-native

Your bundle must contain exactly one react-native. React Native hands native events to a single copy of the module — the one whose RCTDeviceEventEmitter was registered as a callable module, which is the copy your app's entry file imported. Code running in any other copy still reads Platform, calls native modules and gets a real subscription object back from addEventListener; it just never receives an event.

If the SDK ends up in a second copy, $app_background, $app_foreground, the background crash-safety snapshot and deep-link events all go silently dead while the app looks healthy. The SDK detects this and reports it through your on('error') handler and console.warn.

Duplicates come from the bundler, so that is where to fix them. In a monorepo, make Metro resolve react-native from one place regardless of which file imports it:

// metro.config.js
config.resolver.resolveRequest = (context, moduleName, platform) => {
  if (moduleName === 'react-native' || moduleName.startsWith('react-native/')) {
    return context.resolveRequest(
      {
        ...context,
        nodeModulesPaths: [path.resolve(workspaceRoot, 'node_modules')],
        disableHierarchicalLookup: true
      },
      moduleName,
      platform
    );
  }
  return context.resolveRequest(context, moduleName, platform);
};

If you cannot change the bundler, hand the SDK your app's module directly:

import { AppState } from 'react-native';

const layers = new LayersReactNative({ appId, environment, appState: AppState });

Core API

Constructor & Initialization

const layers = new LayersReactNative(config: LayersRNConfig);
await layers.init();

The constructor creates the SDK instance with an in-memory queue. Calling init() upgrades to AsyncStorage-backed persistence, collects device info, fetches remote config, reads clipboard attribution (iOS), fires app_open, and sets up auto-tracking.

You can call track() and screen() before init() completes -- events are queued in memory.

Event Tracking

track(eventName: string, properties?: EventProperties): void

layers.track('purchase_completed', {
  product_id: 'sku_123',
  price: 9.99,
  currency: 'USD'
});

Screen Tracking

screen(screenName: string, properties?: EventProperties): void

layers.screen('ProductDetail', { product_id: 'sku_123' });

User Identity

// Set the app user ID (set-user-once: ignored if already set)
setAppUserId(appUserId: string): void

// Clear the current user ID (allows setting a new one)
clearAppUserId(): void

// Get the current user ID
getAppUserId(): string | undefined

// Set user properties
async setUserProperties(properties: UserProperties): Promise<void>

// After login
layers.setAppUserId('user_123');
await layers.setUserProperties({
  email: '[email protected]',
  plan: 'premium'
});

// On logout
layers.clearAppUserId();

Set-user-once semantics: Once setAppUserId() is called, subsequent calls are ignored until clearAppUserId() is called. This prevents accidental user ID changes.

Consent Management

async setConsent(consent: ConsentState): Promise<void>
getConsentState(): ConsentState

interface ConsentState {
  analytics?: boolean;
  advertising?: boolean;
}

// User accepts all tracking
await layers.setConsent({ analytics: true, advertising: true });

// User denies advertising
await layers.setConsent({ analytics: true, advertising: false });

// Read current consent
const consent = layers.getConsentState();

Flush & Shutdown

// Flush queued events to the server
async flush(): Promise<void>

// Shut down the SDK (removes listeners, stops timers)
shutdown(): void

Session & Device

// Get the current session ID
getSessionId(): string

// Override device context fields
setDeviceInfo(deviceInfo: DeviceContext): void

Error Handling

// Register an error listener
on(event: 'error', listener: (error: Error) => void): this

// Remove an error listener
off(event: 'error', listener: (error: Error) => void): this

layers.on('error', (error) => {
  console.error('Layers error:', error.message);
  // Forward to your crash reporting service
});

App Tracking Transparency (ATT) -- iOS

Integrated ATT (Recommended)

The requestTrackingPermission() method on the SDK instance handles the ATT prompt and records its result:

const status = await layers.requestTrackingPermission();
// Returns: 'authorized' | 'denied' | 'restricted' | 'not_determined'

This method:

1. Shows the ATT dialog (or uses expo-tracking-transparency if available)
2. Records the ATT status while preserving the existing device context
3. Collects IDFA only when ATT is authorized

ATT controls IDFA availability only. It does not change Layers consent. Call layers.setConsent(...) separately when your app's own consent flow changes Layers collection or delivery policy.

Attribution continues when IDFA is unavailable using the other signals the SDK has collected, including its install/device context and available click or deep link identifiers.

Standalone ATT Functions

For more granular control, use the exported functions:

import {
  getATTStatus,
  getAdvertisingId,
  getVendorId,
  isATTAvailable,
  requestTrackingAuthorization
} from '@layers/react-native';

const status = await getATTStatus();
const isAvailable = await isATTAvailable();
const idfa = await getAdvertisingId(); // null if not authorized
const idfv = await getVendorId(); // does not require ATT; null if unavailable

ATTStatus

type ATTStatus = 'not_determined' | 'restricted' | 'denied' | 'authorized';

Important: Complete the Info.plist setup before requesting ATT authorization.

SKAdNetwork (SKAN) -- iOS

SKAN is auto-configured from the server's remote config. The SDK creates a SKANManager instance and automatically forwards every track() call through the SKAN rule engine.

Required: Info.plist setup

Bare React Native projects must add these keys to ios/<App>/Info.plist themselves. Without NSAdvertisingAttributionReportEndpoint, Apple never delivers SKAdNetwork postbacks to Layers and the rule engine's conversion values never reach attribution. (Using @layers/expo? The config plugin adds both automatically — skip this.)

<!-- Tells Apple to copy SKAdNetwork postbacks to Layers. REQUIRED. -->
<key>NSAdvertisingAttributionReportEndpoint</key>
<string>https://layers.click</string>

<!-- One <dict> per ad network you run campaigns on. (Meta shown as an example.) -->
<key>SKAdNetworkItems</key>
<array>
  <dict>
    <key>SKAdNetworkIdentifier</key>
    <string>v9wttpbfk9.skadnetwork</string>
  </dict>
</array>

Apple appends /.well-known/skadnetwork/report to the endpoint and allows only one NSAdvertisingAttributionReportEndpoint per app.

Accessing the Auto-Configured Manager

const skanManager = layers.getSkanManager();
if (skanManager) {
  const metrics = skanManager.getMetrics();
  console.log('SKAN value:', metrics.currentValue);
  console.log('SKAN preset:', metrics.currentPreset);
}

Manual SKAN Configuration

If you need to configure SKAN manually instead of relying on remote config:

import { SKANManager } from '@layers/react-native';

const skan = new SKANManager((data) => {
  console.log(`Conversion value updated: ${data.previousValue} -> ${data.newValue}`);
});

// Use a built-in preset
skan.setPreset('subscriptions'); // or 'engagement' or 'iap'
await skan.initialize();

// Or define custom rules
skan.setCustomRules([
  {
    eventName: 'purchase_success',
    conditions: { revenue: { '>=': 10 } },
    conversionValue: 63,
    coarseValue: 'high',
    priority: 10
  },
  {
    eventName: 'trial_start',
    conversionValue: 20,
    priority: 5
  }
]);
await skan.initialize();

// Process events manually
await skan.processEvent('purchase_success', { revenue: 49.99 });

SKANConversionRule

interface SKANConversionRule {
  eventName: string;
  conditions?: Record<string, unknown>; // Operator-based: { '>': 10, '<': 100 }
  conversionValue: number; // 0-63 (SKAN 3.0) or 0-7 (SKAN 4.0)
  coarseValue?: 'low' | 'medium' | 'high'; // SKAN 4.0 only
  lockWindow?: boolean; // SKAN 4.0 only
  priority?: number;
  description?: string;
}

SKANMetrics

interface SKANMetrics {
  isSupported: boolean;
  version: string;
  currentValue: number | null;
  currentPreset: string | null;
  ruleCount: number;
  evaluationCount: number;
}

Available Presets

• subscriptions -- Optimized for subscription apps (trial start, subscription start/renew)
• engagement -- Optimized for engagement-driven apps (content views, sessions, bookmarks)
• iap -- Optimized for in-app purchase revenue tracking (purchase tiers by revenue)

Deep Links

Auto-Tracking (Default)

When autoTrackDeepLinks is true (default), the SDK automatically tracks a deep_link_opened event for every incoming deep link. The event includes the full URL, scheme, host, path, and all query parameters (UTM, click IDs) as flat top-level properties.

Manual Deep Link Handling

import { parseDeepLink, setupDeepLinkListener } from '@layers/react-native';

const unsubscribe = setupDeepLinkListener((data) => {
  console.log('Deep link:', data.url);
  console.log('Host:', data.host);
  console.log('Path:', data.path);
  console.log('UTM Source:', data.queryParams.utm_source);
  console.log('Click ID:', data.queryParams.fbclid);
});

// Later: unsubscribe()

The listener handles both:

• Initial URL (cold start): Checks Linking.getInitialURL() on setup.
• Subsequent URLs (warm start): Listens to Linking url events.

parseDeepLink

function parseDeepLink(url: string): DeepLinkData | null;

interface DeepLinkData {
  url: string;
  scheme: string;
  host: string;
  path: string;
  queryParams: Record<string, string>;
  timestamp: number;
}

Clipboard Attribution -- iOS

On iOS, the SDK reads the clipboard on first launch (during init()) for a Layers click URL. If found, the click URL and click ID are included as properties on the app_open event. This is controlled by the server's remote config (clipboard_attribution_enabled).

For manual reading:

import { readClipboardAttribution } from '@layers/react-native';

const data = await readClipboardAttribution();
if (data) {
  console.log('Click URL:', data.clickUrl);
  console.log('Click ID:', data.clickId);
}

interface ClipboardAttribution {
  clickUrl: string;
  clickId: string;
}

Requires @react-native-clipboard/clipboard as a peer dependency.

Expo Router Integration

For automatic screen tracking with Expo Router:

import { useLayersExpoRouterTracking } from '@layers/react-native';
import { usePathname, useGlobalSearchParams } from 'expo-router';

function RootLayout() {
  useLayersExpoRouterTracking(layers, usePathname, useGlobalSearchParams);

  return <Stack />;
}

This hook automatically tracks a screen event every time the Expo Router pathname changes, including route parameters as event properties.

Install ID

The SDK generates and persists a unique install ID via AsyncStorage:

import { getOrSetInstallId } from '@layers/react-native';

const installId = await getOrSetInstallId();

This ID persists across app sessions and is included in the device context.

Automatic Behaviors

• app_open event: Tracked on init() with clipboard attribution (iOS).
• deep_link_opened event: Tracked automatically for all incoming deep links.
• Background flush: Events are flushed when the app goes to background/inactive.
• Foreground flush: Events are flushed when the app becomes active.
• Network reconnect flush: Events are flushed when the device reconnects (requires @react-native-community/netinfo).
• Periodic flush: Events are flushed on a timer (configurable).
• Remote config: Server configuration is fetched during init.
• SKAN auto-config: SKAN preset/rules from remote config are applied automatically (iOS).
• Device context: Platform, OS version, device model, locale, screen size, timezone, IDFV (iOS), and install ID are collected automatically.
• Event persistence: Events are persisted via AsyncStorage (if available) and rehydrated on restart.

TypeScript Types

All types are exported from the package:

import type {
  ATTStatus,
  ClipboardAttribution,
  ConsentState,
  DeepLinkData,
  DeviceContext,
  Environment,
  ErrorListener,
  EventProperties,
  LayersRNConfig,
  SKANConversionRule,
  SKANMetrics,
  SKANPresetConfig,
  UserProperties
} from '@layers/react-native';