@datalyr/react-native 1.2.0 → 1.3.0

package/android/src/main/java/com/datalyr/reactnative/DatalyrPlayInstallReferrerModule.java

@@ -0,0 +1,229 @@
+package com.datalyr.reactnative;
+
+import android.os.RemoteException;
+import android.util.Log;
+
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.WritableMap;
+
+import com.android.installreferrer.api.InstallReferrerClient;
+import com.android.installreferrer.api.InstallReferrerStateListener;
+import com.android.installreferrer.api.ReferrerDetails;
+
+import java.io.UnsupportedEncodingException;
+import java.net.URLDecoder;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Google Play Install Referrer Module for Android
+ *
+ * Captures install attribution data from Google Play Store:
+ * - UTM parameters (utm_source, utm_medium, utm_campaign, etc.)
+ * - Google Ads click ID (gclid)
+ * - Referrer timestamps
+ *
+ * This data is critical for attributing installs to marketing campaigns.
+ */
+public class DatalyrPlayInstallReferrerModule extends ReactContextBaseJavaModule {
+    private static final String TAG = "DatalyrPlayReferrer";
+    private static final String MODULE_NAME = "DatalyrPlayInstallReferrer";
+
+    private final ReactApplicationContext reactContext;
+    private InstallReferrerClient referrerClient;
+
+    public DatalyrPlayInstallReferrerModule(ReactApplicationContext context) {
+        super(context);
+        this.reactContext = context;
+    }
+
+    @Override
+    public String getName() {
+        return MODULE_NAME;
+    }
+
+    /**
+     * Check if Play Install Referrer is available
+     */
+    @ReactMethod
+    public void isAvailable(Promise promise) {
+        try {
+            // Check if the Play Install Referrer library is available
+            Class.forName("com.android.installreferrer.api.InstallReferrerClient");
+            promise.resolve(true);
+        } catch (ClassNotFoundException e) {
+            promise.resolve(false);
+        }
+    }
+
+    /**
+     * Get install referrer data from Google Play
+     *
+     * Returns an object with:
+     * - referrerUrl: The full referrer URL
+     * - referrerClickTimestamp: When the referrer link was clicked (ms)
+     * - installBeginTimestamp: When the install began (ms)
+     * - installCompleteTimestamp: When install was completed (ms) - Android 10+
+     * - gclid: Google Ads click ID (if present)
+     * - utmSource, utmMedium, utmCampaign, etc.
+     */
+    @ReactMethod
+    public void getInstallReferrer(final Promise promise) {
+        try {
+            referrerClient = InstallReferrerClient.newBuilder(reactContext.getApplicationContext()).build();
+
+            referrerClient.startConnection(new InstallReferrerStateListener() {
+                @Override
+                public void onInstallReferrerSetupFinished(int responseCode) {
+                    switch (responseCode) {
+                        case InstallReferrerClient.InstallReferrerResponse.OK:
+                            try {
+                                ReferrerDetails details = referrerClient.getInstallReferrer();
+                                WritableMap result = parseReferrerDetails(details);
+                                promise.resolve(result);
+                            } catch (RemoteException e) {
+                                Log.e(TAG, "Failed to get install referrer", e);
+                                promise.resolve(null);
+                            } finally {
+                                referrerClient.endConnection();
+                            }
+                            break;
+
+                        case InstallReferrerClient.InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
+                            Log.d(TAG, "Install referrer not supported on this device");
+                            promise.resolve(null);
+                            referrerClient.endConnection();
+                            break;
+
+                        case InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE:
+                            Log.d(TAG, "Install referrer service unavailable");
+                            promise.resolve(null);
+                            referrerClient.endConnection();
+                            break;
+
+                        default:
+                            Log.d(TAG, "Install referrer unknown response: " + responseCode);
+                            promise.resolve(null);
+                            referrerClient.endConnection();
+                            break;
+                    }
+                }
+
+                @Override
+                public void onInstallReferrerServiceDisconnected() {
+                    Log.d(TAG, "Install referrer service disconnected");
+                    // Connection lost - can try to reconnect if needed
+                }
+            });
+        } catch (Exception e) {
+            Log.e(TAG, "Failed to start install referrer client", e);
+            promise.resolve(null);
+        }
+    }
+
+    /**
+     * Parse ReferrerDetails into a WritableMap with UTM parameters extracted
+     */
+    private WritableMap parseReferrerDetails(ReferrerDetails details) {
+        WritableMap result = Arguments.createMap();
+
+        try {
+            String referrerUrl = details.getInstallReferrer();
+            result.putString("referrerUrl", referrerUrl);
+            result.putDouble("referrerClickTimestamp", details.getReferrerClickTimestampSeconds() * 1000.0);
+            result.putDouble("installBeginTimestamp", details.getInstallBeginTimestampSeconds() * 1000.0);
+
+            // Android 10+ has install complete timestamp
+            try {
+                long installCompleteTs = details.getInstallBeginTimestampServerSeconds();
+                if (installCompleteTs > 0) {
+                    result.putDouble("installCompleteTimestamp", installCompleteTs * 1000.0);
+                }
+            } catch (NoSuchMethodError e) {
+                // Method not available on older Android versions
+            }
+
+            // Parse UTM parameters from referrer URL
+            if (referrerUrl != null && !referrerUrl.isEmpty()) {
+                Map<String, String> params = parseReferrerUrl(referrerUrl);
+
+                // UTM parameters
+                if (params.containsKey("utm_source")) {
+                    result.putString("utmSource", params.get("utm_source"));
+                }
+                if (params.containsKey("utm_medium")) {
+                    result.putString("utmMedium", params.get("utm_medium"));
+                }
+                if (params.containsKey("utm_campaign")) {
+                    result.putString("utmCampaign", params.get("utm_campaign"));
+                }
+                if (params.containsKey("utm_term")) {
+                    result.putString("utmTerm", params.get("utm_term"));
+                }
+                if (params.containsKey("utm_content")) {
+                    result.putString("utmContent", params.get("utm_content"));
+                }
+
+                // Google Ads click ID
+                if (params.containsKey("gclid")) {
+                    result.putString("gclid", params.get("gclid"));
+                }
+
+                // Other potential click IDs
+                if (params.containsKey("fbclid")) {
+                    result.putString("fbclid", params.get("fbclid"));
+                }
+                if (params.containsKey("ttclid")) {
+                    result.putString("ttclid", params.get("ttclid"));
+                }
+
+                // App referrer (used by some attribution providers)
+                if (params.containsKey("referrer")) {
+                    result.putString("referrer", params.get("referrer"));
+                }
+            }
+
+            Log.d(TAG, "Install referrer parsed successfully");
+
+        } catch (Exception e) {
+            Log.e(TAG, "Failed to parse referrer details", e);
+        }
+
+        return result;
+    }
+
+    /**
+     * Parse URL-encoded referrer string into key-value pairs
+     */
+    private Map<String, String> parseReferrerUrl(String referrerUrl) {
+        Map<String, String> params = new HashMap<>();
+
+        if (referrerUrl == null || referrerUrl.isEmpty()) {
+            return params;
+        }
+
+        try {
+            // Decode the URL-encoded referrer
+            String decoded = URLDecoder.decode(referrerUrl, "UTF-8");
+
+            // Split by & to get key=value pairs
+            String[] pairs = decoded.split("&");
+            for (String pair : pairs) {
+                int idx = pair.indexOf('=');
+                if (idx > 0 && idx < pair.length() - 1) {
+                    String key = pair.substring(0, idx);
+                    String value = pair.substring(idx + 1);
+                    params.put(key, value);
+                }
+            }
+        } catch (UnsupportedEncodingException e) {
+            Log.e(TAG, "Failed to decode referrer URL", e);
+        }
+
+        return params;
+    }
+}

package/datalyr-react-native.podspec

@@ -20,8 +20,8 @@ Pod::Spec.new do |s|
   s.swift_version = "5.0"
 
   s.dependency "React-Core"
-  s.dependency "FBSDKCoreKit", "~> 17.0"
-  s.dependency "TikTokBusinessSDK", "~> 1.4"
+  s.dependency "FBSDKCoreKit", "~> 18.0"
+  s.dependency "TikTokBusinessSDK", "~> 1.6"
 
   # Disable bitcode (required for TikTok SDK)
   s.pod_target_xcconfig = {

package/ios/DatalyrNative.m

@@ -67,4 +67,8 @@ RCT_EXTERN_METHOD(updateTikTokTrackingAuthorization:(BOOL)enabled
 RCT_EXTERN_METHOD(getSDKAvailability:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject)
 
+// Apple Search Ads Attribution
+RCT_EXTERN_METHOD(getAppleSearchAdsAttribution:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
 @end

package/ios/DatalyrNative.swift

@@ -1,6 +1,7 @@
 import Foundation
 import FBSDKCoreKit
 import TikTokBusinessSDK
+import AdServices
 
 @objc(DatalyrNative)
 class DatalyrNative: NSObject {
@@ -269,7 +270,63 @@ class DatalyrNative: NSObject {
   ) {
     resolve([
       "meta": true,
-      "tiktok": true
+      "tiktok": true,
+      "appleSearchAds": true
     ])
   }
+
+  // MARK: - Apple Search Ads Attribution
+
+  @objc func getAppleSearchAdsAttribution(
+    _ resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    // AdServices is available on iOS 14.3+
+    if #available(iOS 14.3, *) {
+      do {
+        // Get the attribution token from AdServices
+        let token = try AAAttribution.attributionToken()
+
+        // Send token to Apple's API to get attribution data
+        var request = URLRequest(url: URL(string: "https://api-adservices.apple.com/api/v1/")!)
+        request.httpMethod = "POST"
+        request.setValue("text/plain", forHTTPHeaderField: "Content-Type")
+        request.httpBody = token.data(using: .utf8)
+
+        let task = URLSession.shared.dataTask(with: request) { data, response, error in
+          if let error = error {
+            // Network error - resolve with nil instead of rejecting
+            resolve(nil)
+            return
+          }
+
+          guard let data = data else {
+            resolve(nil)
+            return
+          }
+
+          do {
+            if let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] {
+              // Return attribution data
+              // Includes: attribution, orgId, orgName, campaignId, campaignName,
+              // adGroupId, adGroupName, clickDate, conversionType, etc.
+              resolve(json)
+            } else {
+              resolve(nil)
+            }
+          } catch {
+            resolve(nil)
+          }
+        }
+        task.resume()
+
+      } catch {
+        // Attribution token not available (user didn't come from Apple Search Ads)
+        resolve(nil)
+      }
+    } else {
+      // iOS version too old
+      resolve(nil)
+    }
+  }
 }

package/ios/DatalyrSKAdNetwork.m

@@ -8,6 +8,7 @@
 
 RCT_EXPORT_MODULE();
 
+// SKAN 3.0 - Legacy method for iOS 14.0-16.0
 RCT_EXPORT_METHOD(updateConversionValue:(NSInteger)value
                   resolve:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject) {
@@ -23,4 +24,54 @@ RCT_EXPORT_METHOD(updateConversionValue:(NSInteger)value
     }
 }
 
-@end 
+// SKAN 4.0 - New method for iOS 16.1+ with coarse value and lock window support
+RCT_EXPORT_METHOD(updatePostbackConversionValue:(NSInteger)fineValue
+                  coarseValue:(NSString *)coarseValue
+                  lockWindow:(BOOL)lockWindow
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    if (@available(iOS 16.1, *)) {
+        // Convert string to SKAdNetwork.CoarseConversionValue
+        SKAdNetworkCoarseConversionValue coarse;
+        if ([coarseValue isEqualToString:@"high"]) {
+            coarse = SKAdNetworkCoarseConversionValueHigh;
+        } else if ([coarseValue isEqualToString:@"medium"]) {
+            coarse = SKAdNetworkCoarseConversionValueMedium;
+        } else {
+            coarse = SKAdNetworkCoarseConversionValueLow;
+        }
+
+        [SKAdNetwork updatePostbackConversionValue:fineValue
+                                       coarseValue:coarse
+                                        lockWindow:lockWindow
+                                 completionHandler:^(NSError * _Nullable error) {
+            if (error) {
+                reject(@"skadnetwork_error", error.localizedDescription, error);
+            } else {
+                resolve(@(YES));
+            }
+        }];
+    } else if (@available(iOS 14.0, *)) {
+        // Fallback to SKAN 3.0 for iOS 14.0-16.0
+        @try {
+            [SKAdNetwork updateConversionValue:fineValue];
+            resolve(@(YES));
+        } @catch (NSException *exception) {
+            reject(@"skadnetwork_error", exception.reason, nil);
+        }
+    } else {
+        reject(@"ios_version_error", @"SKAdNetwork requires iOS 14.0+", nil);
+    }
+}
+
+// Check if SKAN 4.0 is available (iOS 16.1+)
+RCT_EXPORT_METHOD(isSKAN4Available:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+    if (@available(iOS 16.1, *)) {
+        resolve(@(YES));
+    } else {
+        resolve(@(NO));
+    }
+}
+
+@end

package/lib/ConversionValueEncoder.d.ts

@@ -1,7 +1,10 @@
+import { SKANCoarseValue, SKANConversionResult } from './native/SKAdNetworkBridge';
 interface EventMapping {
     bits: number[];
     revenueBits?: number[];
     priority: number;
+    coarseValue?: SKANCoarseValue;
+    lockWindow?: boolean;
 }
 interface ConversionTemplate {
     name: string;
@@ -11,13 +14,22 @@ export declare class ConversionValueEncoder {
     private template;
     constructor(template: ConversionTemplate);
     /**
-     * Encode an event into Apple's 0-63 conversion value format
+     * Encode an event into Apple's 0-63 conversion value format (SKAN 3.0 compatible)
+     * @deprecated Use encodeWithSKAN4 for iOS 16.1+
      */
     encode(event: string, properties?: Record<string, any>): number;
+    /**
+     * Encode an event with full SKAN 4.0 support (fine value, coarse value, lock window)
+     */
+    encodeWithSKAN4(event: string, properties?: Record<string, any>): SKANConversionResult;
     /**
      * Map revenue amount to 3-bit tier (0-7)
      */
     private getRevenueTier;
+    /**
+     * Map revenue to SKAN 4.0 coarse value
+     */
+    private getCoarseValueForRevenue;
 }
 export declare const ConversionTemplates: {
     ecommerce: ConversionTemplate;

package/lib/ConversionValueEncoder.js

@@ -3,18 +3,27 @@ export class ConversionValueEncoder {
         this.template = template;
     }
     /**
-     * Encode an event into Apple's 0-63 conversion value format
+     * Encode an event into Apple's 0-63 conversion value format (SKAN 3.0 compatible)
+     * @deprecated Use encodeWithSKAN4 for iOS 16.1+
      */
     encode(event, properties) {
+        return this.encodeWithSKAN4(event, properties).fineValue;
+    }
+    /**
+     * Encode an event with full SKAN 4.0 support (fine value, coarse value, lock window)
+     */
+    encodeWithSKAN4(event, properties) {
         const mapping = this.template.events[event];
-        if (!mapping)
-            return 0;
+        if (!mapping) {
+            return { fineValue: 0, coarseValue: 'low', lockWindow: false, priority: 0 };
+        }
         let conversionValue = 0;
         // Set event bits
         for (const bit of mapping.bits) {
             conversionValue |= (1 << bit);
         }
         // Set revenue bits if revenue is provided
+        let coarseValue = mapping.coarseValue || 'medium';
         if (mapping.revenueBits && properties) {
             const revenue = properties.revenue || properties.value || 0;
             const revenueTier = this.getRevenueTier(revenue);
@@ -23,8 +32,17 @@ export class ConversionValueEncoder {
                     conversionValue |= (1 << mapping.revenueBits[i]);
                 }
             }
+            // Upgrade coarse value based on revenue
+            coarseValue = this.getCoarseValueForRevenue(revenue);
         }
-        return Math.min(conversionValue, 63);
+        // Ensure value is within 0-63 range
+        const fineValue = Math.min(conversionValue, 63);
+        return {
+            fineValue,
+            coarseValue,
+            lockWindow: mapping.lockWindow || false,
+            priority: mapping.priority
+        };
     }
     /**
      * Map revenue amount to 3-bit tier (0-7)
@@ -46,40 +64,56 @@ export class ConversionValueEncoder {
             return 6; // $100-250
         return 7; // $250+
     }
+    /**
+     * Map revenue to SKAN 4.0 coarse value
+     */
+    getCoarseValueForRevenue(revenue) {
+        if (revenue < 10)
+            return 'low'; // $0-10 = low value
+        if (revenue < 50)
+            return 'medium'; // $10-50 = medium value
+        return 'high'; // $50+ = high value
+    }
 }
-// Industry templates
+// Industry templates with SKAN 4.0 support
 export const ConversionTemplates = {
+    // E-commerce template - optimized for online stores
+    // SKAN 4.0: purchase locks window, high-value events get "high" coarse value
     ecommerce: {
         name: 'ecommerce',
         events: {
-            purchase: { bits: [0], revenueBits: [1, 2, 3], priority: 100 },
-            add_to_cart: { bits: [4], priority: 30 },
-            begin_checkout: { bits: [5], priority: 50 },
-            signup: { bits: [6], priority: 20 },
-            subscribe: { bits: [0, 1], revenueBits: [2, 3, 4], priority: 90 },
-            view_item: { bits: [7], priority: 10 }
+            purchase: { bits: [0], revenueBits: [1, 2, 3], priority: 100, coarseValue: 'high', lockWindow: true },
+            add_to_cart: { bits: [4], priority: 30, coarseValue: 'low' },
+            begin_checkout: { bits: [5], priority: 50, coarseValue: 'medium' },
+            signup: { bits: [6], priority: 20, coarseValue: 'low' },
+            subscribe: { bits: [0, 1], revenueBits: [2, 3, 4], priority: 90, coarseValue: 'high', lockWindow: true },
+            view_item: { bits: [7], priority: 10, coarseValue: 'low' }
         }
     },
+    // Gaming template - optimized for mobile games
+    // SKAN 4.0: purchase locks window, tutorial completion is medium value
     gaming: {
         name: 'gaming',
         events: {
-            level_complete: { bits: [0], priority: 40 },
-            tutorial_complete: { bits: [1], priority: 60 },
-            purchase: { bits: [2], revenueBits: [3, 4, 5], priority: 100 },
-            achievement_unlocked: { bits: [6], priority: 30 },
-            session_start: { bits: [7], priority: 10 },
-            ad_watched: { bits: [0, 6], priority: 20 }
+            level_complete: { bits: [0], priority: 40, coarseValue: 'medium' },
+            tutorial_complete: { bits: [1], priority: 60, coarseValue: 'medium' },
+            purchase: { bits: [2], revenueBits: [3, 4, 5], priority: 100, coarseValue: 'high', lockWindow: true },
+            achievement_unlocked: { bits: [6], priority: 30, coarseValue: 'low' },
+            session_start: { bits: [7], priority: 10, coarseValue: 'low' },
+            ad_watched: { bits: [0, 6], priority: 20, coarseValue: 'low' }
         }
     },
+    // Subscription template - optimized for subscription apps
+    // SKAN 4.0: subscribe/upgrade lock window, trial is medium value
     subscription: {
         name: 'subscription',
         events: {
-            trial_start: { bits: [0], priority: 70 },
-            subscribe: { bits: [1], revenueBits: [2, 3, 4], priority: 100 },
-            upgrade: { bits: [1, 5], revenueBits: [2, 3, 4], priority: 90 },
-            cancel: { bits: [6], priority: 20 },
-            signup: { bits: [7], priority: 30 },
-            payment_method_added: { bits: [0, 7], priority: 50 }
+            trial_start: { bits: [0], priority: 70, coarseValue: 'medium' },
+            subscribe: { bits: [1], revenueBits: [2, 3, 4], priority: 100, coarseValue: 'high', lockWindow: true },
+            upgrade: { bits: [1, 5], revenueBits: [2, 3, 4], priority: 90, coarseValue: 'high', lockWindow: true },
+            cancel: { bits: [6], priority: 20, coarseValue: 'low' },
+            signup: { bits: [7], priority: 30, coarseValue: 'low' },
+            payment_method_added: { bits: [0, 7], priority: 50, coarseValue: 'medium' }
         }
     }
 };

package/lib/datalyr-sdk.d.ts

@@ -1,6 +1,7 @@
 import { DatalyrConfig, EventData, UserProperties, AutoEventConfig, DeferredDeepLinkResult } from './types';
 import { AttributionData } from './attribution';
 import { SessionData } from './auto-events';
+import { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';
 export declare class DatalyrSDK {
     private state;
     private httpClient;
@@ -55,15 +56,30 @@ export declare class DatalyrSDK {
         currentUserId?: string;
         queueStats: any;
         attribution: any;
+        journey: any;
     };
     /**
      * Get the persistent anonymous ID
      */
     getAnonymousId(): string;
     /**
-     * Get detailed attribution data
+     * Get detailed attribution data (includes journey tracking data)
      */
-    getAttributionData(): AttributionData;
+    getAttributionData(): AttributionData & Record<string, any>;
+    /**
+     * Get journey tracking summary
+     */
+    getJourneySummary(): {
+        hasFirstTouch: boolean;
+        hasLastTouch: boolean;
+        touchpointCount: number;
+        daysSinceFirstTouch: number;
+        sources: string[];
+    };
+    /**
+     * Get full customer journey (all touchpoints)
+     */
+    getJourney(): import("./journey").TouchPoint[];
     /**
      * Set custom attribution data (for testing or manual attribution)
      */
@@ -90,6 +106,7 @@ export declare class DatalyrSDK {
     updateAutoEventsConfig(config: Partial<AutoEventConfig>): void;
     /**
      * Track event with automatic SKAdNetwork conversion value encoding
+     * Uses SKAN 4.0 on iOS 16.1+ with coarse values and lock window support
      */
     trackWithSKAdNetwork(event: string, properties?: EventData): Promise<void>;
     /**
@@ -138,7 +155,19 @@ export declare class DatalyrSDK {
     getPlatformIntegrationStatus(): {
         meta: boolean;
         tiktok: boolean;
+        appleSearchAds: boolean;
+        playInstallReferrer: boolean;
     };
+    /**
+     * Get Apple Search Ads attribution data
+     * Returns attribution if user installed via Apple Search Ads, null otherwise
+     */
+    getAppleSearchAdsAttribution(): AppleSearchAdsAttribution | null;
+    /**
+     * Get Google Play Install Referrer attribution data (Android only)
+     * Returns referrer data if available, null otherwise
+     */
+    getPlayInstallReferrer(): Record<string, any> | null;
     /**
      * Update tracking authorization status on all platform SDKs
      * Call this AFTER the user responds to the ATT permission dialog
@@ -214,6 +243,7 @@ export declare class Datalyr {
         currentUserId?: string;
         queueStats: any;
         attribution: any;
+        journey: any;
     };
     static getAnonymousId(): string;
     static getAttributionData(): AttributionData;
@@ -234,7 +264,9 @@ export declare class Datalyr {
     static getPlatformIntegrationStatus(): {
         meta: boolean;
         tiktok: boolean;
+        appleSearchAds: boolean;
     };
+    static getAppleSearchAdsAttribution(): AppleSearchAdsAttribution | null;
     static updateTrackingAuthorization(enabled: boolean): Promise<void>;
 }
 export default datalyr;