@datalyr/react-native 1.6.1 → 1.6.3

package/README.md

@@ -12,13 +12,20 @@ Mobile analytics and attribution SDK for React Native and Expo. Track events, id
   - [Custom Events](#custom-events)
   - [Screen Views](#screen-views)
   - [E-Commerce Events](#e-commerce-events)
+  - [Revenue Events](#revenue-events)
 - [User Identity](#user-identity)
   - [Anonymous ID](#anonymous-id)
   - [Identifying Users](#identifying-users)
+  - [Alias](#alias)
   - [User Properties](#user-properties)
+  - [Logout](#logout)
+- [Sessions](#sessions)
 - [Attribution](#attribution)
   - [Automatic Capture](#automatic-capture)
+  - [Manual Attribution](#manual-attribution)
   - [Web-to-App Attribution](#web-to-app-attribution)
+  - [Deferred Attribution](#deferred-attribution)
+- [Customer Journey](#customer-journey)
 - [Event Queue](#event-queue)
 - [Auto Events](#auto-events)
 - [SKAdNetwork](#skadnetwork)
@@ -27,12 +34,16 @@ Mobile analytics and attribution SDK for React Native and Expo. Track events, id
   - [TikTok](#tiktok)
   - [Google Ads](#google-ads)
   - [Apple Search Ads](#apple-search-ads)
+  - [Google Play Install Referrer](#google-play-install-referrer)
+  - [App Tracking Transparency](#app-tracking-transparency)
+- [Enhanced App Campaigns](#enhanced-app-campaigns)
 - [Third-Party Integrations](#third-party-integrations)
   - [Superwall](#superwall)
   - [RevenueCat](#revenuecat)
 - [Migrating from AppsFlyer / Adjust](#migrating-from-appsflyer--adjust)
 - [Expo Support](#expo-support)
 - [TypeScript](#typescript)
+- [API Reference](#api-reference)
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
 
@@ -125,24 +136,62 @@ Every event includes:
 
 ## Configuration
 
+All fields except `apiKey` are optional.
+
 ```typescript
 await Datalyr.initialize({
   // Required
-  apiKey: string,
+  apiKey: string,                          // API key from dashboard (starts with 'dk_')
+
+  // Optional: workspace
+  workspaceId?: string,                    // Workspace ID for multi-workspace setups
+
+  // Debugging
+  debug?: boolean,                         // Console logging (default: false)
+
+  // Network
+  endpoint?: string,                       // API endpoint URL (default: 'https://api.datalyr.com')
+  useServerTracking?: boolean,             // Use server-side tracking (default: true)
+  maxRetries?: number,                     // Max retry attempts for failed requests (default: 3)
+  retryDelay?: number,                     // Delay between retries in ms (default: 1000)
+  timeout?: number,                        // Request timeout in ms (default: 15000)
 
   // Features
-  debug?: boolean,                   // Console logging
-  enableAutoEvents?: boolean,        // Track app lifecycle
-  enableAttribution?: boolean,       // Capture attribution data
+  enableAutoEvents?: boolean,              // Track app lifecycle automatically (default: true)
+  enableAttribution?: boolean,             // Capture attribution data (default: true)
+  enableWebToAppAttribution?: boolean,     // Web-to-app attribution matching (default: true)
 
-  // Event Queue
-  batchSize?: number,                // Events per batch (default: 10)
-  flushInterval?: number,            // Send interval ms (default: 30000)
-  maxQueueSize?: number,             // Max queued events (default: 100)
+  // Event queue
+  batchSize?: number,                      // Events per batch (default: 10)
+  flushInterval?: number,                  // Auto-flush interval in ms (default: 30000)
+  maxQueueSize?: number,                   // Max queued events (default: 100)
+
+  // Auto events
+  autoEventConfig?: AutoEventConfig,       // Fine-grained auto-event settings (see below)
 
   // iOS
-  skadTemplate?: 'ecommerce' | 'gaming' | 'subscription',
+  skadTemplate?: 'ecommerce' | 'gaming' | 'subscription',  // SKAdNetwork conversion template
+});
+```
+
+### AutoEventConfig
+
+```typescript
+interface AutoEventConfig {
+  trackSessions?: boolean;       // Track session_start / session_end
+  trackScreenViews?: boolean;    // Track screen views automatically
+  trackAppUpdates?: boolean;     // Track app_update events
+  trackPerformance?: boolean;    // Track performance metrics
+  sessionTimeoutMs?: number;     // Session timeout in ms
+}
+```
+
+Update at runtime:
 
+```typescript
+Datalyr.updateAutoEventsConfig({
+  trackSessions: true,
+  sessionTimeoutMs: 1800000, // 30 minutes
 });
 ```
 
@@ -152,8 +201,6 @@ await Datalyr.initialize({
 
 ### Custom Events
 
-Track any action in your app:
-
 ```typescript
 // Simple event
 await Datalyr.track('signup_started');
@@ -177,8 +224,6 @@ await Datalyr.track('level_completed', {
 
 ### Screen Views
 
-Track navigation:
-
 ```typescript
 await Datalyr.screen('Home');
 
@@ -221,6 +266,26 @@ await Datalyr.trackLead(100.0, 'USD');
 await Datalyr.trackAddPaymentInfo(true);
 ```
 
+### Revenue Events
+
+Track revenue with automatic SKAdNetwork encoding:
+
+```typescript
+await Datalyr.trackRevenue('in_app_purchase', {
+  value: 4.99,
+  currency: 'USD',
+  product_id: 'gems_500',
+});
+```
+
+### App Update Tracking
+
+Manually track version changes:
+
+```typescript
+await Datalyr.trackAppUpdate('1.0.0', '1.1.0');
+```
+
 ---
 
 ## User Identity
@@ -253,6 +318,18 @@ After `identify()`:
 - All future events include `user_id`
 - Historical anonymous events can be linked server-side
 
+### Alias
+
+Associate a new user ID with a previous one. Use this when a user's identity changes (e.g., after account merge):
+
+```typescript
+// Link new ID to the currently identified user
+await Datalyr.alias('new_user_456');
+
+// Or specify the previous ID explicitly
+await Datalyr.alias('new_user_456', 'old_user_123');
+```
+
 ### User Properties
 
 Pass any user attributes:
@@ -286,6 +363,20 @@ This:
 
 ---
 
+## Sessions
+
+```typescript
+// Get current session data
+const session = Datalyr.getCurrentSession();
+
+// Force end the current session
+await Datalyr.endSession();
+```
+
+Sessions are managed automatically when `enableAutoEvents` is enabled. A new session starts on app launch, and the current session ends after 30 minutes of inactivity (configurable via `autoEventConfig.sessionTimeoutMs`).
+
+---
+
 ## Attribution
 
 ### Automatic Capture
@@ -304,13 +395,24 @@ Captured parameters:
 | Click IDs | `fbclid`, `gclid`, `ttclid`, `twclid`, `li_click_id`, `msclkid` |
 | Campaign | `campaign_id`, `adset_id`, `ad_id` |
 
+### Manual Attribution
+
+Set attribution programmatically:
+
+```typescript
+await Datalyr.setAttributionData({
+  utm_source: 'newsletter',
+  utm_campaign: 'spring_sale',
+});
+```
+
 ### Web-to-App Attribution
 
 Automatically recover attribution from a web prelander when users install the app from an ad.
 
 **How it works:**
-- **Android**: Attribution params are passed through the Play Store `referrer` URL parameter (set by the web SDK's `trackAppDownloadClick()`). The mobile SDK reads these via the Play Install Referrer API — deterministic, ~95% accuracy.
-- **iOS**: On first install, the SDK calls the Datalyr API to match the device's IP against recent `$app_download_click` web events within 24 hours — ~90%+ accuracy for immediate installs.
+- **Android**: Attribution params are passed through the Play Store `referrer` URL parameter (set by the web SDK's `trackAppDownloadClick()`). The mobile SDK reads these via the Play Install Referrer API -- deterministic, ~95% accuracy.
+- **iOS**: On first install, the SDK calls the Datalyr API to match the device's IP against recent `$app_download_click` web events within 24 hours -- ~90%+ accuracy for immediate installs.
 
 No additional mobile code is needed. Attribution is recovered automatically during `initialize()` on first install, before the `app_install` event fires.
 
@@ -321,15 +423,43 @@ After a match, the SDK:
 
 **Fallback:** If IP matching misses (e.g., VPN toggle during install), email-based attribution is still recovered when `identify()` is called with the user's email.
 
-### Manual Attribution
+### Deferred Attribution
 
-Set attribution programmatically:
+Retrieve deferred attribution data captured from deep links or install referrers:
 
 ```typescript
-await Datalyr.setAttributionData({
-  utm_source: 'newsletter',
-  utm_campaign: 'spring_sale',
-});
+const deferred = Datalyr.getDeferredAttributionData();
+if (deferred) {
+  console.log(deferred.url);          // Deep link URL
+  console.log(deferred.source);       // Attribution source
+  console.log(deferred.fbclid);       // Facebook click ID
+  console.log(deferred.gclid);        // Google click ID
+  console.log(deferred.ttclid);       // TikTok click ID
+  console.log(deferred.utmSource);    // UTM source
+  console.log(deferred.utmMedium);    // UTM medium
+  console.log(deferred.utmCampaign);  // UTM campaign
+  console.log(deferred.utmContent);   // UTM content
+  console.log(deferred.utmTerm);      // UTM term
+  console.log(deferred.campaignId);   // Campaign ID
+  console.log(deferred.adsetId);      // Adset ID
+  console.log(deferred.adId);         // Ad ID
+}
+```
+
+---
+
+## Customer Journey
+
+Access multi-touch attribution journey data via the `datalyr` singleton instance:
+
+```typescript
+import { datalyr } from '@datalyr/react-native';
+
+// Summary: first/last touch, touchpoint count
+const summary = datalyr.getJourneySummary();
+
+// Full journey: all touchpoints in order
+const journey = datalyr.getJourney();
 ```
 
 ---
@@ -407,7 +537,10 @@ await Datalyr.initialize({
   skadTemplate: 'ecommerce',
 });
 
-// E-commerce events update conversion values
+// Track with automatic SKAN conversion value encoding
+await Datalyr.trackWithSKAdNetwork('purchase', { value: 99.99 });
+
+// Or use e-commerce helpers (also update SKAN automatically)
 await Datalyr.trackPurchase(99.99, 'USD');
 ```
 
@@ -417,6 +550,15 @@ await Datalyr.trackPurchase(99.99, 'USD');
 | `gaming` | level_complete, tutorial_complete, purchase, achievement_unlocked |
 | `subscription` | trial_start, subscribe, upgrade, cancel, signup |
 
+### Test Conversion Values
+
+Preview the conversion value an event would produce without sending it to Apple:
+
+```typescript
+const value = Datalyr.getConversionValue('purchase', { value: 49.99 });
+// Returns a number (0-63) or null if no template is configured
+```
+
 ---
 
 ## Platform Integrations
@@ -434,7 +576,7 @@ Conversions are sent to Meta via the [Conversions API (CAPI)](https://developers
 **Setup:**
 1. Connect your Meta ad account in the Datalyr dashboard (Settings > Connections)
 2. Select your Meta Pixel
-3. Create postback rules to map events (e.g., `purchase` → `Purchase`, `lead` → `Lead`)
+3. Create postback rules to map events (e.g., `purchase` -> `Purchase`, `lead` -> `Lead`)
 
 No Facebook SDK needed in your app. No `Info.plist` changes, no `FacebookAppID`.
 
@@ -449,7 +591,7 @@ Conversions are sent to TikTok via the [Events API](https://business-api.tiktok.
 **Setup:**
 1. Connect your TikTok Ads account in the Datalyr dashboard (Settings > Connections)
 2. Select your TikTok Pixel
-3. Create postback rules to map events (e.g., `purchase` → `CompletePayment`, `add_to_cart` → `AddToCart`)
+3. Create postback rules to map events (e.g., `purchase` -> `CompletePayment`, `add_to_cart` -> `AddToCart`)
 
 No TikTok SDK needed in your app. No access tokens, no native configuration.
 
@@ -464,7 +606,7 @@ Conversions are sent to Google via the [Google Ads API](https://developers.googl
 **Setup:**
 1. Connect your Google Ads account in the Datalyr dashboard (Settings > Connections)
 2. Select your conversion actions
-3. Create postback rules to map events (e.g., `purchase` → your Google conversion action)
+3. Create postback rules to map events (e.g., `purchase` -> your Google conversion action)
 
 No Google SDK needed in your app beyond the Play Install Referrer (already included for Android).
 
@@ -494,6 +636,52 @@ Attribution data is automatically included in all events with the `asa_` prefix:
 
 No additional configuration needed. The SDK uses Apple's AdServices API.
 
+### Google Play Install Referrer
+
+Android-only. Captures UTM parameters and click IDs from the Google Play Store install referrer URL. This data is retrieved automatically on first launch via the Play Install Referrer API.
+
+**How it works:**
+1. User clicks an ad or link with UTM parameters
+2. Google Play Store stores the referrer URL
+3. On first app launch, the SDK retrieves the referrer
+4. Attribution data (utm_source, utm_medium, gclid, etc.) is extracted and merged into the session
+
+**Access the raw referrer data:**
+
+```typescript
+import { datalyr } from '@datalyr/react-native';
+
+const referrer = datalyr.getPlayInstallReferrer();
+if (referrer) {
+  // Google Ads click IDs
+  console.log(referrer.gclid);    // Standard Google Ads click ID
+  console.log(referrer.gbraid);   // Privacy-safe click ID (iOS App campaigns)
+  console.log(referrer.wbraid);   // Privacy-safe click ID (Web-to-App campaigns)
+
+  // UTM parameters
+  console.log(referrer.utmSource);
+  console.log(referrer.utmMedium);
+  console.log(referrer.utmCampaign);
+  console.log(referrer.utmTerm);
+  console.log(referrer.utmContent);
+
+  // Timestamps
+  console.log(referrer.referrerClickTimestamp);   // When the referrer link was clicked (ms)
+  console.log(referrer.installBeginTimestamp);     // When the install began (ms)
+  console.log(referrer.installCompleteTimestamp);  // When the install completed (ms)
+
+  // Raw referrer URL
+  console.log(referrer.referrerUrl);
+}
+```
+
+**Requirements:**
+- Android only (returns `null` on iOS)
+- Requires the Google Play Install Referrer Library in `android/app/build.gradle`:
+  ```groovy
+  implementation 'com.android.installreferrer:installreferrer:2.2'
+  ```
+
 ### App Tracking Transparency
 
 Update after ATT dialog:
@@ -503,37 +691,219 @@ const { status } = await requestTrackingPermissionsAsync();
 await Datalyr.updateTrackingAuthorization(status === 'granted');
 ```
 
-### Check Status
+### Integration Status
 
 ```typescript
 const status = Datalyr.getPlatformIntegrationStatus();
-// { appleSearchAds: true }
+// { appleSearchAds: boolean, playInstallReferrer: boolean }
 ```
 
 ---
 
-## Expo Support
+## Enhanced App Campaigns
+
+Run mobile app ads through web campaigns (Meta Sales, TikTok Traffic, Google Ads) that redirect users to the app store through your own domain. This bypasses SKAN restrictions, ATT requirements, and adset limits -- ad platforms treat these as regular web campaigns.
+
+### How It Works
+
+1. User clicks your ad -> lands on a page on your domain with the Datalyr web SDK (`dl.js`)
+2. SDK captures attribution (fbclid, ttclid, gclid, UTMs, ad cookies like `_fbp`/`_fbc`/`_ttp`)
+3. User redirects to app store (via button click or auto-redirect)
+4. User installs app -> mobile SDK matches via Play Store referrer (Android, ~95%) or IP matching (iOS, ~90%+)
+5. In-app events fire -> conversions sent to Meta/TikTok/Google server-side via postbacks
+
+### Setup
+
+**1. Create a tracking link** in the Datalyr dashboard: Track -> Create Link -> App Link. Enter your prelander page URL and app store URLs.
+
+**2. Host a page on your domain** with one of these options:
+
+#### Option A: Prelander (Recommended)
+
+A real landing page with a download button. Better ad platform compliance, higher intent.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Download Your App</title>
+  <script src="https://cdn.datalyr.com/dl.js" data-workspace="YOUR_WORKSPACE_ID"></script>
+</head>
+<body>
+  <h1>Download Our App</h1>
+  <button id="ios-download">Download for iOS</button>
+  <button id="android-download">Download for Android</button>
+
+  <script>
+    document.getElementById('ios-download').addEventListener('click', function() {
+      Datalyr.trackAppDownloadClick({
+        targetPlatform: 'ios',
+        appStoreUrl: 'https://apps.apple.com/app/idXXXXXXXXXX'
+      });
+    });
+    document.getElementById('android-download').addEventListener('click', function() {
+      Datalyr.trackAppDownloadClick({
+        targetPlatform: 'android',
+        appStoreUrl: 'https://play.google.com/store/apps/details?id=com.example.app'
+      });
+    });
+  </script>
+</body>
+</html>
+```
 
-```typescript
-import { Datalyr } from '@datalyr/react-native/expo';
+#### Option B: Redirect Page
+
+Instant redirect -- no visible content, user goes straight to app store.
+
+> **Note:** Some ad platforms (particularly Meta) may flag redirect pages with no visible content as low-quality landing pages or cloaking. Use the prelander option if compliance is a concern.
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://cdn.datalyr.com/dl.js" data-workspace="YOUR_WORKSPACE_ID"></script>
+  <script>
+    window.addEventListener('DOMContentLoaded', function() {
+      var isAndroid = /android/i.test(navigator.userAgent);
+      Datalyr.trackAppDownloadClick({
+        targetPlatform: isAndroid ? 'android' : 'ios',
+        appStoreUrl: isAndroid
+          ? 'https://play.google.com/store/apps/details?id=com.example.app'
+          : 'https://apps.apple.com/app/idXXXXXXXXXX'
+      });
+    });
+  </script>
+</head>
+<body></body>
+</html>
 ```
 
-Same API as standard React Native.
+**3. Set up your ad campaign:**
+
+- **Meta Ads**: Campaign objective -> Sales, conversion location -> Website, placements -> Mobile only. Paste your page URL as the Website URL. No SKAN, no ATT, no adset limits.
+- **TikTok Ads**: Campaign objective -> Website Conversions, paste your page URL as destination. Select your TikTok Pixel from Datalyr.
+- **Google Ads**: Performance Max or Search campaign. Use your page URL as the landing page.
+
+Add UTM parameters to the URL so attribution flows through:
+- Meta: `?utm_source=facebook&utm_medium=cpc&utm_campaign={{campaign.name}}&utm_content={{adset.name}}&utm_term={{ad.name}}`
+- TikTok: `?utm_source=tiktok&utm_medium=cpc&utm_campaign=__CAMPAIGN_NAME__&utm_content=__AID_NAME__&utm_term=__CID_NAME__`
+- Google: `?utm_source=google&utm_medium=cpc&utm_campaign={campaignid}&utm_content={adgroupid}&utm_term={keyword}`
+
+### Important
+
+- The page **must load JavaScript**. Server-side redirects (301/302, nginx, Cloudflare Page Rules) will NOT work.
+- Host on your own domain -- do not use `datalyr.com` or shared domains.
+- The redirect page adds ~100-200ms for the SDK to load. Prelander has no latency since the user clicks a button.
 
 ---
 
-## TypeScript
+## Third-Party Integrations
+
+### Superwall
+
+Pass Datalyr attribution data to Superwall to personalize paywalls by ad source, campaign, ad set, and keyword.
 
 ```typescript
-import {
-  Datalyr,
-  DatalyrConfig,
-  EventData,
-  UserProperties,
-  AttributionData,
-} from '@datalyr/react-native';
+import { Datalyr } from '@datalyr/react-native';
+import Superwall from '@superwall/react-native-superwall';
+
+// After both SDKs are initialized
+Superwall.setUserAttributes(Datalyr.getSuperwallAttributes());
+
+// Your placements will now have attribution data available as filters
+Superwall.register({ placement: 'onboarding_paywall' });
+```
+
+Call after `Datalyr.initialize()` completes. If using ATT on iOS, call again after the user responds to the ATT prompt to include the IDFA.
+
+**Returned attribute keys:**
+
+| Key | Description |
+|-----|-------------|
+| `datalyr_id` | The user's DATALYR visitor ID |
+| `media_source` | Traffic source (e.g., `facebook`, `google`) |
+| `campaign` | Campaign name from the ad |
+| `adgroup` | Ad group or ad set name |
+| `ad` | Individual ad ID |
+| `keyword` | Search keyword that triggered the ad |
+| `network` | Ad network name |
+| `utm_source` | UTM source parameter |
+| `utm_medium` | UTM medium parameter (e.g., `cpc`) |
+| `utm_campaign` | UTM campaign parameter |
+| `utm_term` | UTM term parameter |
+| `utm_content` | UTM content parameter |
+| `lyr` | DATALYR tracking link ID |
+| `fbclid` | Meta click ID from the ad URL |
+| `gclid` | Google click ID from the ad URL |
+| `ttclid` | TikTok click ID from the ad URL |
+| `idfa` | Apple advertising ID (only if ATT authorized) |
+| `gaid` | Google advertising ID (Android) |
+| `att_status` | App Tracking Transparency status (`0`-`3`) |
+
+Only non-empty values are included.
+
+### RevenueCat
+
+Pass Datalyr attribution data to RevenueCat for revenue attribution and offering targeting.
+
+```typescript
+import { Datalyr } from '@datalyr/react-native';
+import Purchases from 'react-native-purchases';
+
+// After both SDKs are configured
+Purchases.setAttributes(Datalyr.getRevenueCatAttributes());
 ```
 
+Call after configuring the Purchases SDK and before the first purchase. If using ATT, call again after permission is granted to include IDFA.
+
+**Reserved attributes (`$`-prefixed):**
+
+| Key | Description |
+|-----|-------------|
+| `$datalyrId` | The user's DATALYR visitor ID |
+| `$mediaSource` | Traffic source (e.g., `facebook`, `google`) |
+| `$campaign` | Campaign name from the ad |
+| `$adGroup` | Ad group or ad set name |
+| `$ad` | Individual ad ID |
+| `$keyword` | Search keyword that triggered the ad |
+| `$idfa` | Apple advertising ID (only if ATT authorized) |
+| `$gpsAdId` | Google advertising ID (Android) |
+| `$attConsentStatus` | ATT consent status (see mapping below) |
+
+**ATT status mapping for `$attConsentStatus`:**
+
+| ATT Value | String |
+|-----------|--------|
+| 0 | `notDetermined` |
+| 1 | `restricted` |
+| 2 | `denied` |
+| 3 | `authorized` |
+
+**Custom attributes:**
+
+| Key | Description |
+|-----|-------------|
+| `utm_source` | UTM source parameter |
+| `utm_medium` | UTM medium parameter (e.g., `cpc`) |
+| `utm_campaign` | UTM campaign parameter |
+| `utm_term` | UTM term parameter |
+| `utm_content` | UTM content parameter |
+| `lyr` | DATALYR tracking link ID |
+| `fbclid` | Meta click ID from the ad URL |
+| `gclid` | Google click ID from the ad URL |
+| `ttclid` | TikTok click ID from the ad URL |
+| `wbraid` | Google web-to-app click ID |
+| `gbraid` | Google app click ID |
+| `network` | Ad network |
+| `creative_id` | Creative ID |
+
+Only non-empty values are included.
+
+> Datalyr also receives Superwall and RevenueCat events via server-side webhooks for analytics. The SDK methods and webhook integration are independent -- you can use one or both.
+
 ---
 
 ## Migrating from AppsFlyer / Adjust
@@ -587,40 +957,132 @@ await Datalyr.trackPurchase(99.99, 'USD');
 
 ---
 
-## Third-Party Integrations
+## Expo Support
 
-### Superwall
+```typescript
+import { Datalyr } from '@datalyr/react-native/expo';
+```
 
-Pass Datalyr attribution data to Superwall to personalize paywalls by ad source, campaign, ad set, and keyword.
+Same API as standard React Native.
 
-```typescript
-import Datalyr from '@datalyr/react-native';
-import Superwall from '@superwall/react-native-superwall';
+---
 
-// After both SDKs are initialized
-Superwall.setUserAttributes(Datalyr.getSuperwallAttributes());
+## TypeScript
 
-// Your placements will now have attribution data available as filters
-Superwall.register({ placement: 'onboarding_paywall' });
+```typescript
+import {
+  Datalyr,
+  DatalyrConfig,
+  EventData,
+  UserProperties,
+  AttributionData,
+  AutoEventConfig,
+  DeferredDeepLinkResult,
+} from '@datalyr/react-native';
 ```
 
-Call after `Datalyr.initialize()` completes. If using ATT on iOS, call again after the user responds to the ATT prompt to include the IDFA.
+---
 
-### RevenueCat
+## API Reference
 
-Pass Datalyr attribution data to RevenueCat for revenue attribution and offering targeting.
+All methods are static on the `Datalyr` class unless noted otherwise.
 
-```typescript
-import Datalyr from '@datalyr/react-native';
-import Purchases from 'react-native-purchases';
+### Initialization
 
-// After both SDKs are configured
-Purchases.setAttributes(Datalyr.getRevenueCatAttributes());
-```
+| Method | Description |
+|--------|-------------|
+| `initialize(config: DatalyrConfig)` | Initialize the SDK. Must be called before any other method. |
 
-Call after configuring the Purchases SDK and before the first purchase. If using ATT, call again after permission is granted to include IDFA.
+### Event Tracking
+
+| Method | Description |
+|--------|-------------|
+| `track(eventName, eventData?)` | Track a custom event |
+| `screen(screenName, properties?)` | Track a screen view |
+| `trackWithSKAdNetwork(event, properties?)` | Track event with SKAN conversion value encoding |
+| `trackPurchase(value, currency?, productId?)` | Track a purchase |
+| `trackSubscription(value, currency?, plan?)` | Track a subscription |
+| `trackRevenue(eventName, properties?)` | Track a revenue event |
+| `trackAddToCart(value, currency?, productId?, productName?)` | Track add-to-cart |
+| `trackViewContent(contentId?, contentName?, contentType?, value?, currency?)` | Track content view |
+| `trackInitiateCheckout(value, currency?, numItems?, productIds?)` | Track checkout start |
+| `trackCompleteRegistration(method?)` | Track registration |
+| `trackSearch(query, resultIds?)` | Track a search |
+| `trackLead(value?, currency?)` | Track a lead |
+| `trackAddPaymentInfo(success?)` | Track payment info added |
+| `trackAppUpdate(previousVersion, currentVersion)` | Track an app version update |
+
+### User Identity
+
+| Method | Description |
+|--------|-------------|
+| `identify(userId, properties?)` | Identify a user |
+| `alias(newUserId, previousId?)` | Associate a new user ID with a previous one |
+| `reset()` | Clear user ID and start new session |
+| `getAnonymousId()` | Get the persistent anonymous device ID |
+
+### Sessions
+
+| Method | Description |
+|--------|-------------|
+| `getCurrentSession()` | Get current session data |
+| `endSession()` | Force end the current session |
+
+### Attribution
+
+| Method | Description |
+|--------|-------------|
+| `getAttributionData()` | Get captured attribution data |
+| `setAttributionData(data)` | Set attribution data manually |
+| `getDeferredAttributionData()` | Get deferred attribution from deep links / install referrer |
+
+### Configuration
+
+| Method | Description |
+|--------|-------------|
+| `updateAutoEventsConfig(config)` | Update auto-event settings at runtime |
+
+### Platform Integrations
+
+| Method | Description |
+|--------|-------------|
+| `getAppleSearchAdsAttribution()` | Get Apple Search Ads attribution (iOS) |
+| `getPlatformIntegrationStatus()` | Check which platform integrations are active |
+| `updateTrackingAuthorization(enabled)` | Update ATT status after user responds to dialog |
+
+### SKAdNetwork
+
+| Method | Description |
+|--------|-------------|
+| `getConversionValue(event, properties?)` | Preview conversion value without sending to Apple |
+
+### Third-Party Integrations
+
+| Method | Description |
+|--------|-------------|
+| `getSuperwallAttributes()` | Get attribution formatted for Superwall |
+| `getRevenueCatAttributes()` | Get attribution formatted for RevenueCat |
+
+### Status
+
+| Method | Description |
+|--------|-------------|
+| `getStatus()` | Get SDK status (initialized, queue stats, online) |
+| `flush()` | Send all queued events immediately |
+
+### Instance Methods (via `datalyr` singleton)
+
+These methods are available on the `datalyr` instance export, not on the static `Datalyr` class:
+
+```typescript
+import { datalyr } from '@datalyr/react-native';
+```
 
-> Datalyr also receives Superwall and RevenueCat events via server-side webhooks for analytics. The SDK methods and webhook integration are independent — you can use one or both.
+| Method | Description |
+|--------|-------------|
+| `getJourneySummary()` | Get journey summary (first/last touch, touchpoint count) |
+| `getJourney()` | Get full customer journey (all touchpoints) |
+| `getPlayInstallReferrer()` | Get raw Play Install Referrer data (Android) |
 
 ---
 

package/lib/datalyr-sdk.js

@@ -23,7 +23,7 @@ export class DatalyrSDK {
                 workspaceId: '',
                 apiKey: '',
                 debug: false,
-                endpoint: 'https://api.datalyr.com', // Updated to server-side API
+                endpoint: 'https://ingest.datalyr.com/track',
                 useServerTracking: true, // Default to server-side
                 maxRetries: 3,
                 retryDelay: 1000,
@@ -63,7 +63,7 @@ export class DatalyrSDK {
             // Set up configuration
             this.state.config = { ...this.state.config, ...config };
             // Initialize HTTP client with server-side API
-            this.httpClient = new HttpClient(this.state.config.endpoint || 'https://api.datalyr.com', {
+            this.httpClient = new HttpClient(this.state.config.endpoint || 'https://ingest.datalyr.com/track', {
                 maxRetries: this.state.config.maxRetries || 3,
                 retryDelay: this.state.config.retryDelay || 1000,
                 timeout: this.state.config.timeout || 15000,
@@ -347,10 +347,9 @@ export class DatalyrSDK {
         }
         try {
             debugLog('Fetching deferred web attribution via IP matching...');
-            const baseUrl = this.state.config.endpoint || 'https://api.datalyr.com';
             const controller = new AbortController();
             const timeout = setTimeout(() => controller.abort(), 10000);
-            const response = await fetch(`${baseUrl}/attribution/deferred-lookup`, {
+            const response = await fetch('https://api.datalyr.com/attribution/deferred-lookup', {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',

package/lib/http-client.js

@@ -5,7 +5,7 @@ export class HttpClient {
         this.requestCount = 0;
         // Use server-side API if flag is set (default to true for v1.0.0)
         this.endpoint = config.useServerTracking !== false
-            ? 'https://api.datalyr.com'
+            ? 'https://ingest.datalyr.com/track'
             : endpoint;
         this.config = config;
     }
@@ -142,6 +142,7 @@ export class HttpClient {
     transformForServerAPI(payload) {
         return {
             event: payload.eventName,
+            eventId: payload.eventId,
             userId: payload.userId || payload.visitorId,
             anonymousId: payload.anonymousId || payload.visitorId,
             properties: {
@@ -152,8 +153,8 @@ export class HttpClient {
             },
             context: {
                 library: '@datalyr/react-native',
-                version: '1.5.0',
-                source: 'mobile_app', // Explicitly set source for mobile
+                version: '1.6.2',
+                source: 'mobile_app',
                 userProperties: payload.userProperties,
             },
             timestamp: payload.timestamp,

package/lib/types.d.ts

@@ -42,11 +42,11 @@ export interface DatalyrConfig {
     /** Enable console logging for debugging. Default: false */
     debug?: boolean;
     /**
-     * API endpoint URL. Default: 'https://api.datalyr.com'
+     * API endpoint URL. Default: 'https://ingest.datalyr.com/track'
      * @deprecated Use `endpoint` instead
      */
     apiUrl?: string;
-    /** API endpoint URL. Default: 'https://api.datalyr.com' */
+    /** API endpoint URL. Default: 'https://ingest.datalyr.com/track' */
     endpoint?: string;
     /** Use server-side tracking. Default: true */
     useServerTracking?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalyr/react-native",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "Datalyr SDK for React Native & Expo - Server-side attribution tracking for iOS and Android",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/datalyr-sdk-expo.ts

@@ -55,7 +55,7 @@ export class DatalyrSDKExpo {
         workspaceId: '',
         apiKey: '',
         debug: false,
-        endpoint: 'https://api.datalyr.com',
+        endpoint: 'https://ingest.datalyr.com/track',
         useServerTracking: true,
         maxRetries: 3,
         retryDelay: 1000,
@@ -92,7 +92,7 @@ export class DatalyrSDKExpo {
 
       this.state.config = { ...this.state.config, ...config };
 
-      this.httpClient = new HttpClient(this.state.config.endpoint || 'https://api.datalyr.com', {
+      this.httpClient = new HttpClient(this.state.config.endpoint || 'https://ingest.datalyr.com/track', {
         maxRetries: this.state.config.maxRetries || 3,
         retryDelay: this.state.config.retryDelay || 1000,
         timeout: this.state.config.timeout || 15000,

package/src/datalyr-sdk.ts

@@ -54,7 +54,7 @@ export class DatalyrSDK {
         workspaceId: '',
         apiKey: '',
         debug: false,
-        endpoint: 'https://api.datalyr.com', // Updated to server-side API
+        endpoint: 'https://ingest.datalyr.com/track',
         useServerTracking: true, // Default to server-side
         maxRetries: 3,
         retryDelay: 1000,
@@ -99,7 +99,7 @@ export class DatalyrSDK {
       this.state.config = { ...this.state.config, ...config };
 
       // Initialize HTTP client with server-side API
-      this.httpClient = new HttpClient(this.state.config.endpoint || 'https://api.datalyr.com', {
+      this.httpClient = new HttpClient(this.state.config.endpoint || 'https://ingest.datalyr.com/track', {
         maxRetries: this.state.config.maxRetries || 3,
         retryDelay: this.state.config.retryDelay || 1000,
         timeout: this.state.config.timeout || 15000,
@@ -425,11 +425,10 @@ export class DatalyrSDK {
     try {
       debugLog('Fetching deferred web attribution via IP matching...');
 
-      const baseUrl = this.state.config.endpoint || 'https://api.datalyr.com';
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), 10000);
 
-      const response = await fetch(`${baseUrl}/attribution/deferred-lookup`, {
+      const response = await fetch('https://api.datalyr.com/attribution/deferred-lookup', {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',

package/src/http-client.ts

@@ -26,8 +26,8 @@ export class HttpClient {
 
   constructor(endpoint: string, config: HttpClientConfig) {
     // Use server-side API if flag is set (default to true for v1.0.0)
-    this.endpoint = config.useServerTracking !== false 
-      ? 'https://api.datalyr.com'
+    this.endpoint = config.useServerTracking !== false
+      ? 'https://ingest.datalyr.com/track'
       : endpoint;
     this.config = config;
   }
@@ -187,6 +187,7 @@ export class HttpClient {
   private transformForServerAPI(payload: EventPayload): any {
     return {
       event: payload.eventName,
+      eventId: payload.eventId,
       userId: payload.userId || payload.visitorId,
       anonymousId: payload.anonymousId || payload.visitorId,
       properties: {
@@ -197,8 +198,8 @@ export class HttpClient {
       },
       context: {
         library: '@datalyr/react-native',
-        version: '1.5.0',
-        source: 'mobile_app',  // Explicitly set source for mobile
+        version: '1.6.2',
+        source: 'mobile_app',
         userProperties: payload.userProperties,
       },
       timestamp: payload.timestamp,

package/src/types.ts

@@ -49,12 +49,12 @@ export interface DatalyrConfig {
   debug?: boolean;
 
   /**
-   * API endpoint URL. Default: 'https://api.datalyr.com'
+   * API endpoint URL. Default: 'https://ingest.datalyr.com/track'
    * @deprecated Use `endpoint` instead
    */
   apiUrl?: string;
 
-  /** API endpoint URL. Default: 'https://api.datalyr.com' */
+  /** API endpoint URL. Default: 'https://ingest.datalyr.com/track' */
   endpoint?: string;
 
   /** Use server-side tracking. Default: true */