React Native SDK - Datalyr Docs

Complete reference for @datalyr/react-native 1.7.15, which posts events to https://ingest.datalyr.com/track. For a first install, start with Install in a mobile app.

Requirements

Package	Version	Required
`react-native`	`>=0.72.0`	Yes
`react`	`>=18.0.0`	Yes
`expo-modules-core`	`>=2.0.0`	Yes, in bare React Native too
`@react-native-community/netinfo`	`>=11.0.0`	Optional
`react-native-device-info`	`>=12.0.0`	Optional

Install expo-modules-core even in a bare React Native app. The SDK calls requireNativeModule at module load, so a missing package throws before initialize() runs.

Minimum iOS deployment target is 13.0.

Install

npm install @datalyr/react-native expo-modules-core
cd ios && pod install

The package bundles @react-native-async-storage/async-storage, react-native-get-random-values, and uuid. For Play Install Referrer on Android, add this line to android/app/build.gradle.

implementation 'com.android.installreferrer:installreferrer:2.2'

Initialize

import { Datalyr } from '@datalyr/react-native'

await Datalyr.initialize({ apiKey: 'dk_your_api_key' })

Expo apps import the Expo entry point instead.

import { Datalyr } from '@datalyr/react-native/expo'

import Datalyr from '@datalyr/react-native' returns the class, not the singleton. Use the named import { Datalyr } for the static facade, or { datalyr } for the instance. The default import needs new and creates a second SDK.

The SDK buffers 50 events sent before initialize() resolves.

What the SDK tracks without your code

Wire event name	Trigger
`app_install`	First launch, detected by a missing `@datalyr/first_launch_time` key
`session_start`	Init with a new session ID, or foreground after 30 minutes idle
`session_end`	Idle timeout, `destroy()`, or recovery of an abandoned session at next init
`$att_status`	Every `updateTrackingAuthorization()` call
`$network_status_change`	The network listener reports a change after init
`$web_attribution_matched`	An email or IP lookup matched an earlier web visit

There is no app_open, app_foreground, or app_background event. Moving to the background flushes the queue and records activity time. It sends no event.

Events the SDK sends for you

Method you call	Wire event name
`screen()`	`pageview`
`identify()`	`$identify`
`alias()`	`$alias`
`trackAppUpdate()`	`app_update`
`trackPurchase()`	`purchase`
`trackSubscription()`	`subscribe`
`trackAddToCart()`	`add_to_cart`
`trackViewContent()`	`view_content`
`trackInitiateCheckout()`	`initiate_checkout`
`trackCompleteRegistration()`	`complete_registration`
`trackSearch()`	`search`
`trackLead()`	`lead`
`trackAddPaymentInfo()`	`add_payment_info`

screen() sends an event named pageview, not screen. Event names accept letters, digits, _, ., $, and -, up to 100 characters. Any other run of characters becomes a single _, with a console warning.

Track an event

await Datalyr.track('signup_completed', { plan: 'pro', seats: 5 })

Screens

await Datalyr.screen('Pricing', { variant: 'A' })

Navigation library	Use
React Navigation	`datalyrScreenTracking` or `createScreenTrackingListeners`
Expo Router	`useDatalyrScreenTracking()` from `@datalyr/react-native/expo`

Automatic tracking adds source: 'auto_navigation' or source: 'auto_expo_router' to the pageview properties.

Identity

Call identify() once per signed-in person. A call with a different userId runs reset() first, which rotates the anonymous ID and the visitor ID, and erases attribution and the journey.

// Pass your database user ID, not an email. Emails change, and a changed
// email creates a second user with a split journey.
await Datalyr.identify('user_123', {
  email: '[email protected]',
  plan: 'pro'
})

A repeat call with an unchanged identity fingerprint sends no $identify event.

Identity on the wire

Wire field	Value
`anonymousId`	Top-level. Format `anon_<uuid>`.
`properties.anonymous_id`	The same value, repeated.
`userId`	Your ID from `identify()`.
`properties.sessionId`	Format `sess_<epoch_ms>_<9 base36 chars>`.
`context.session_id`	The same session ID. This is the field Datalyr reads.
`properties.fingerprint.deviceId`	A UUID for the install.

This SDK sends no distinct_id and no top-level visitor_id.

await Datalyr.reset()
const anonymousId = Datalyr.getAnonymousId()

reset() rotates both the anonymous ID and the visitor ID, ends the session, and clears attribution, the journey, and SKAdNetwork state.

Revenue

await Datalyr.trackPurchase(99.99, 'USD', 'pro_yearly')
await Datalyr.trackSubscription(19.99, 'USD', 'pro_monthly')

Attribution

The SDK subscribes to Linking and reads the initial URL. It reads these 44 parameters from both the query string and the URL fragment. Keys are lowercased before matching.

Group	Parameters
Datalyr	`lyr`, `datalyr`, `dl_tag`, `dl_campaign`
Click IDs	`fbclid`, `ttclid`, `gclid`, `wbraid`, `gbraid`, `dclid`, `twclid`, `li_fat_id`, `msclkid`, `irclid`, `click_id`, `oppref`
Click ID aliases	`fb_click_id` stores as `fbclid`. `tt_click_id` and `tiktok_click_id` store as `ttclid`. `li_click_id` also sets `li_fat_id`. `irclickid` also sets `irclid`.
Meta extras	`fb_action_ids`, `fb_action_types`
UTM	`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `utm_id`, `utm_source_platform`, `utm_creative_format`, `utm_marketing_tactic`
Partner	`partner_id`, `affiliate_id`, `referrer_id`, `source_id`
Ad structure	`campaign_id`, `ad_id`, `adset_id`, `creative_id`, `placement_id`, `keyword`, `matchtype`, `network`, `device`

Each utm_* value is mirrored to campaign_source, campaign_medium, campaign_name, campaign_term, and campaign_content.

Install attribution

Platform	Mechanism	Properties added
Android	Play Install Referrer	`install_referrer_url`, `referrer_click_timestamp`, `install_begin_timestamp`, `gclid`, `gbraid`, `wbraid`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `attribution_source`
iOS 14.3 and later	AdServices	`asa_campaign_id`, `asa_campaign_name`, `asa_ad_group_id`, `asa_ad_group_name`, `asa_keyword_id`, `asa_keyword`, `asa_org_id`, `asa_org_name`, `asa_click_date`, `asa_conversion_type`, `asa_country_or_region`

Play Install Referrer values merge onto an event only when the event carries neither gclid nor utm_source.

const referrer = Datalyr.getPlayInstallReferrer()
const searchAds = Datalyr.getAppleSearchAdsAttribution()

SKAdNetwork

await Datalyr.trackWithSKAdNetwork('purchase', { value: 49.99 })

The fine value is (rank & 0x7) << 3 | revenueTier, clamped to 0–63. Revenue tiers run under 1, 5, 10, 25, 50, 100, and 250, then 7 above 250. Coarse value is low under 10, medium under 50, and high above. skadTemplate accepts ecommerce, gaming, or subscription. A cross-launch high-water guard stops any decrease. reset() clears it.

App Tracking Transparency

The SDK never prompts. Call the prompt yourself, then report the result.

import { requestTrackingPermissionsAsync } from 'expo-tracking-transparency'

const { granted } = await requestTrackingPermissionsAsync()
await Datalyr.updateTrackingAuthorization(granted)

This sends $att_status and refreshes idfa, idfv, gaid, att_status, and advertiser_tracking_enabled on later events.

RevenueCat and Superwall

await Purchases.setAttributes(Datalyr.getRevenueCatAttributes())
Superwall.shared.setUserAttributes(Datalyr.getSuperwallAttributes())

Call both after the two SDKs initialize, and again after the ATT prompt. See RevenueCat and Superwall.

Complete method list

Method	Signature
`initialize`	`(config: DatalyrConfig) => Promise<void>`
`track`	`(eventName: string, eventData?: EventData) => Promise<void>`
`screen`	`(screenName: string, properties?: EventData) => Promise<void>`
`identify`	`(userId: string, properties?: UserProperties) => Promise<void>`
`alias`	`(newUserId: string, previousId?: string) => Promise<void>`
`reset`	`() => Promise<void>`
`flush`	`() => Promise<void>`
`destroy`	`() => void` (instance only)
`getStatus`	`() => { initialized, workspaceId, visitorId, anonymousId, sessionId, currentUserId?, queueStats, attribution, journey }`
`getAnonymousId`	`() => string`
`getAttributionData`	`() => AttributionData`
`setAttributionData`	`(data: Partial<AttributionData>) => Promise<void>`
`getJourney`	`() => TouchPoint[]` (instance only)
`getJourneySummary`	`() => JourneySummary` (instance only)
`getCurrentSession`	`() => SessionData \| null`
`endSession`	`() => Promise<void>`
`updateAutoEventsConfig`	`(config: Partial<AutoEventConfig>) => void`
`trackAppUpdate`	`(previousVersion: string, currentVersion: string) => Promise<void>`
`trackWithSKAdNetwork`	`(event: string, properties?: EventData) => Promise<void>`
`trackPurchase`	`(value: number, currency = 'USD', productId?: string) => Promise<void>`
`trackSubscription`	`(value: number, currency = 'USD', plan?: string) => Promise<void>`
`trackAddToCart`	`(value: number, currency = 'USD', productId?: string, productName?: string) => Promise<void>`
`trackViewContent`	`(contentId?: string, contentName?: string, contentType = 'product', value?: number, currency?: string) => Promise<void>`
`trackInitiateCheckout`	`(value: number, currency = 'USD', numItems?: number, productIds?: string[]) => Promise<void>`
`trackCompleteRegistration`	`(method?: string) => Promise<void>`
`trackSearch`	`(query: string, resultIds?: string[]) => Promise<void>`
`trackLead`	`(value?: number, currency?: string) => Promise<void>`
`trackAddPaymentInfo`	`(success = true) => Promise<void>`
`getConversionValue`	`(event: string, properties?: Record<string, any>) => number \| null`
`getPlatformIntegrationStatus`	`() => { appleSearchAds: boolean; playInstallReferrer: boolean }`
`getAppleSearchAdsAttribution`	`() => AppleSearchAdsAttribution \| null`
`getPlayInstallReferrer`	`() => Record<string, any> \| null` (instance and Expo static)
`getSuperwallAttributes`	`() => Record<string, string>`
`getRevenueCatAttributes`	`() => Record<string, string>`
`updateTrackingAuthorization`	`(enabled: boolean) => Promise<void>`

Expo signature differences

The Expo entry point changes five signatures. Copying bare React Native code produces a type error or a missing default.

Method	Bare React Native	Expo
`trackAddToCart`	`(value, currency = 'USD', productId?, productName?)`	`(value, currency, contentId?, contentName?)` (`currency` required)
`trackViewContent`	`(contentId?, contentName?, contentType = 'product', …)`	`(contentId, contentName?, contentType?, …)` (`contentId` required, no default type)
`trackInitiateCheckout`	`(value, currency = 'USD', …)`	`(value?, currency?, …)` (both optional, no default)
`trackAddPaymentInfo`	`(success = true)`	`(success?)` (no default)
`updateTrackingAuthorization`	`(enabled: boolean)`	`(authorized: boolean)`

Configuration

await Datalyr.initialize({
  apiKey: 'dk_your_api_key',
  timeout: 15000,       // milliseconds on React Native, not seconds
  batchSize: 10,
  flushInterval: 30000, // milliseconds
  maxQueueSize: 100
})

timeout, retryDelay, flushInterval, and sessionTimeoutMs are milliseconds on React Native. The iOS SDK uses seconds for the first three. Copying timeout: 15 from a Swift configuration aborts every request after 15 milliseconds.

Option	Type	Default	Unit
`apiKey`	`string`	Required	None
`workspaceId`	`string`	`''`	None
`endpoint`	`string`	`'https://ingest.datalyr.com/track'`	URL
`useServerTracking`	`boolean`	`true`	None
`debug`	`boolean`	`false`	None
`maxRetries`	`number`	`3`	attempts
`retryDelay`	`number`	`1000`	milliseconds
`timeout`	`number`	`15000`	milliseconds
`batchSize`	`number`	`10`	events per drain
`flushInterval`	`number`	`30000`	milliseconds
`maxQueueSize`	`number`	`100`	events
`enableAutoEvents`	`boolean`	`true`	None
`enableAttribution`	`boolean`	`true`	None
`enableWebToAppAttribution`	`boolean`	Unset. Anything other than `false` turns it on.	None
`autoEventConfig`	`AutoEventConfig`	Unset	None
`skadTemplate`	`'ecommerce' \| 'gaming' \| 'subscription'`	Unset	None

AutoEventConfig

Option	Type	Default	Unit
`trackSessions`	`boolean`	`true`	None
`trackScreenViews`	`boolean`	`true`	None
`sessionTimeoutMs`	`number`	`1800000`	milliseconds (30 minutes)

sessionTimeoutMs sets when the session_start and session_end events fire. The session ID on the wire rotates on a fixed 30 minutes.

Options with no effect

Remove these from your configuration, and use the option in the right-hand column.

Option	Use instead
`apiUrl`	`endpoint`
`maxEventQueueSize`	`maxQueueSize`
`retryConfig`	`maxRetries` and `retryDelay`
`autoEvents`	`autoEventConfig`
`respectDoNotTrack`	Your own gate around `initialize()`
`AutoEventConfig.trackAppUpdates`	A `trackAppUpdate()` call you make
`AutoEventConfig.trackPerformance`	A `track()` call you make

endpoint, debug, and deferred attribution

endpoint applies only while useServerTracking is false. To point at another host, set both endpoint and useServerTracking: false. That also switches authentication to Authorization: Bearer. Logging follows __DEV__, not debug. A release build prints nothing with debug: true, and a development build prints with debug: false. For deferred attribution, call getPlayInstallReferrer() on Android and getAppleSearchAdsAttribution() on iOS.

Limits

Limit	Value
Events drained per pass	10, from `batchSize`
HTTP requests per drain	One per event. There is no batch endpoint.
Send trigger	Every `enqueue()` while online. `batchSize` is not a threshold.
Flush interval	30,000 ms
Retries per event	3
Retry backoff	`2^n × retryDelay + random(0…1000)` ms, capped at 30,000 ms
`Retry-After` honored	Capped at 30,000 ms
Request timeout	15,000 ms
Client rate limit	100 requests per 60,000 ms. The SDK waits, up to 60,100 ms.
Queue	100 events
Dead-letter queue	100 events, 3 replays each, discarded after 7 days
Pre-init buffer	50 events
Event name	100 characters
Journey	30 touchpoints over 90 days
Attribution lookup timeout	10,000 ms

How failed requests behave

Response	Behavior
`429`, `408`	Retried with backoff, honoring `Retry-After`.
`401`, other `4xx`	Dropped. A wrong API key produces this.
`5xx`, network failure, timeout	Retried up to `maxRetries`, then moved to the dead-letter queue.

Storage

Keys live in AsyncStorage.

Key	Holds
`@datalyr/visitor_id`	The visitor ID
`@datalyr/anonymous_id`	The anonymous ID
`@datalyr/session_id`	The session ID
`@datalyr/user_id`	The identified user ID
`@datalyr/user_properties`	Traits from `identify()`
`@datalyr/event_queue`	The pending queue
`@datalyr/dead_letter_queue`	Permanently failed events
`@datalyr/attribution_data`	The attribution record
`@datalyr/first_launch_time`	The `app_install` guard
`@datalyr/current_session`	Auto-event session state
`@datalyr/first_touch`, `@datalyr/last_touch`, `@datalyr/journey`	Journey state
`@datalyr/skan_high_fine`, `@datalyr/skan_high_coarse`, `@datalyr/skan_window_locked`	SKAdNetwork state
`datalyr_web_attribution_checked`	Web-match guard

The Expo build adds @datalyr/session_start, @datalyr/install_time, @datalyr/last_app_version, and @datalyr/device_id.

Verify the install

Run the app on a clean simulator or a fresh install.
Open Events in Datalyr.
Confirm app_install and session_start arrive within 30 seconds.

If nothing arrives, call Datalyr.getStatus() and read initialized and queueStats. A queue that grows without draining means the API key is wrong. See No events.

​Requirements

​Install

​Initialize

​What the SDK tracks without your code

​Events the SDK sends for you

​Track an event

​Screens

​Identity

​Identity on the wire

​Revenue

​Attribution

​Install attribution

​SKAdNetwork

​App Tracking Transparency

​RevenueCat and Superwall

​Complete method list

​Expo signature differences

​Configuration

​AutoEventConfig

​Options with no effect

​endpoint, debug, and deferred attribution

​Limits

​How failed requests behave

​Storage

​Verify the install

Requirements

Install

Initialize

What the SDK tracks without your code

Events the SDK sends for you

Track an event

Screens

Identity

Identity on the wire

Revenue

Attribution

Install attribution

SKAdNetwork

App Tracking Transparency

RevenueCat and Superwall

Complete method list

Expo signature differences

Configuration

AutoEventConfig

Options with no effect

endpoint, debug, and deferred attribution

Limits

How failed requests behave

Storage

Verify the install