React Native SDK - Datalyr Docs

Complete reference for @datalyr/react-native 1.7.21, 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

Expo
Bare React Native

npx expo install @datalyr/react-native expo-application expo-device expo-network

expo-application, expo-device, and expo-network are required when you import from @datalyr/react-native/expo.Add the config plugin to app.json. Prebuild then writes the SKAdNetwork IDs and the ATT prompt string into Info.plist.

"plugins": [
  ["@datalyr/react-native", {
    "networks": ["meta", "tiktok"],
    "skAdNetworkIds": ["abcd1234ef.skadnetwork"],
    "trackingUsageDescription": "We use this to measure ad performance.",
    "attributionCopyEndpoint": "https://example.com",
    "reengagementPostbackCopies": true
  }]
]

Option	Type	Writes to `Info.plist`
`networks`	`string[]`	`SKAdNetworkItems`. Accepts `meta`, `tiktok`, `google`, `snapchat`, and `apple`. `apple` adds no ID, because Apple Search Ads attributes through AdServices. Existing entries are kept, and duplicates removed.
`skAdNetworkIds`	`string[]`	`SKAdNetworkItems`. Extra IDs for networks not in the list above.
`trackingUsageDescription`	`string`	`NSUserTrackingUsageDescription`, when the key is not already set.
`attributionCopyEndpoint`	`string`	`AttributionCopyEndpoint`. Optional. AdAttributionKit posts copies of winning postbacks to `https://<host>/.well-known/appattribution/report-attribution/` on iOS 17.4 and later.
`reengagementPostbackCopies`	`boolean`	`EligibleForAdAttributionKitReengagementPostbackCopies`. Optional. Enables re-engagement postbacks on iOS 18 and later.

The plugin does nothing on Android.

Build	What works
Development build: `npx expo run:ios`, `npx expo run:android`, or EAS Build	Events, SKAdNetwork, AdAttributionKit, IDFA, Apple Search Ads, Play Install Referrer
Expo Go	Events only. Config plugins are ignored.

The package is built on Expo Modules. Install them once.

npm install @datalyr/react-native expo-modules-core
# Adds use_expo_modules! to the Podfile and useExpoModules() to settings.gradle.
npx install-expo-modules@latest
cd ios && pod install
# Android needs no Gradle change. The library declares Play Install Referrer itself.

The package bundles @react-native-async-storage/async-storage, react-native-get-random-values, and uuid.

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
`$deep_link`	A deep link that carries `lyr`, a click ID, or a UTM parameter. The event carries the link’s attribution parameters.
`$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. alias() without previousId uses the current user ID, or the anonymous ID when nobody is identified. Earlier anonymous events then link to the new ID.

Revenue

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

trackPurchase and trackSubscription are revenue only until the workspace has recorded revenue from a payment source or your server. See SDK values.

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_attribution`, `asa_campaign_id`, `asa_campaign_name`, `asa_adgroup_id`, `asa_adgroup_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.

Behavior	Detail
Registration	Once per install, under the `@datalyr/skan_registered` key
iOS 17.4 and later	Each value goes to both SKAdNetwork and AdAttributionKit
iOS 18 and later	Re-engagement values also send
No `skadTemplate`	`trackWithSKAdNetwork()` logs a warning once per process and sends no update

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. Both methods set datalyr_id to the anonymous ID, the same anonymousId value that is on the wire.

Bind a provider identity

await Datalyr.bindProviderIdentity('revenuecat', await Purchases.getAppUserID())

Datalyr joins that provider’s webhooks to this install through the event.

Item	Value
Wire event	`$provider_identity_bound`
Properties	`external_ids: { <namespace>: <providerUserId> }` and `provider_namespace`
When to call	On every launch, after the provider SDK starts. The server write is idempotent.
Namespaces joined server-side	`revenuecat`, `superwall`, `stripe`, `shopify`, `whop`, `checkoutchamp`, `clickfunnels`, `firebase`, `klaviyo`
Any other namespace	A warning logs once per process. The event still sends, but no webhook joins on it.

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>`
`bindProviderIdentity`	`(namespace: string, providerUserId: string) => Promise<void>`
`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. Log lines carry a [Datalyr] prefix.

Log line	Prints when
Debug	`__DEV__` is true. `debug: true` does not turn it on in a release build.
Error: a dropped event, a dead-letter move, a bad key	Always, in release builds too
Native modules not linked, iOS	Once, at `initialize()`, in Expo Go or a build without `pod install`

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 data payload	200,000 bytes of serialized JSON. `track()` drops larger data before enqueue and logs an error.
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`	Held for a 10-minute grace window, with one warning. After the window, dropped. A wrong API key produces this.
`413`	Moved to the dead-letter queue at once, marked permanent. Replay skips it. The log line names the event and its byte size.
Other `4xx`	Dropped.
`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_registered`, `@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.

What changed in 1.7.21

Area	Change
Expo autolinking	The iOS native modules register under Expo SDK 54 autolinking. On Android, React Native autolinking registers `DatalyrPackage`, so GAID and Play Install Referrer work in Expo apps.
Identity	`getSuperwallAttributes()`, `getRevenueCatAttributes()`, and `alias()` use the anonymous ID that is on the wire, so webhook joins and `$alias` links match.
SKAdNetwork	Registration runs once per install. Earlier releases sent a `0/low` value on every cold launch on iOS 17.4 and later.
AdAttributionKit	On iOS 17.4 and later each conversion value goes to SKAdNetwork and AdAttributionKit. On iOS 18 and later re-engagement values send.
`$deep_link`	Tracked for a deep link that carries `lyr`, a click ID, or a UTM parameter.
HTTP 401	The queue holds for a 10-minute grace window before the permanent-4xx path applies.
HTTP 413	Dead-lettered at once, marked permanent, skipped by replay.
Logging	Error lines print in release builds.
`bindProviderIdentity()`	An unknown namespace logs a warning once. The event still sends.
Privacy manifest	`ingest.datalyr.com` and `api.datalyr.com` are no longer listed under `NSPrivacyTrackingDomains`, so events send before the ATT prompt.

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

​Bind a provider identity

​Complete method list

​Expo signature differences

​Configuration

​AutoEventConfig

​Options with no effect

​endpoint, debug, and deferred attribution

​Limits

​How failed requests behave

​Storage

​What changed in 1.7.21

​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

Bind a provider identity

Complete method list

Expo signature differences

Configuration

AutoEventConfig

Options with no effect

endpoint, debug, and deferred attribution

Limits

How failed requests behave

Storage

What changed in 1.7.21

Verify the install