@datalyr/react-native 1.2.0 → 1.3.0

package/src/native/DatalyrNativeBridge.ts

@@ -1,10 +1,51 @@
 /**
- * Native Bridge for Meta and TikTok SDKs
+ * Native Bridge for Meta, TikTok, Apple Search Ads, and Play Install Referrer
  * Uses bundled native modules instead of separate npm packages
+ *
+ * Supported Platforms:
+ * - iOS: Meta SDK, TikTok SDK, Apple Search Ads (AdServices)
+ * - Android: Meta SDK, TikTok SDK, Play Install Referrer
  */
 
 import { NativeModules, Platform } from 'react-native';
 
+/**
+ * Apple Search Ads attribution data returned from AdServices API (iOS only)
+ */
+export interface AppleSearchAdsAttribution {
+  attribution: boolean;
+  orgId?: number;
+  orgName?: string;
+  campaignId?: number;
+  campaignName?: string;
+  adGroupId?: number;
+  adGroupName?: string;
+  keywordId?: number;
+  keyword?: string;
+  clickDate?: string;
+  conversionType?: string;
+  countryOrRegion?: string;
+}
+
+/**
+ * Play Install Referrer data (Android only)
+ */
+export interface PlayInstallReferrerData {
+  referrerUrl: string;
+  referrerClickTimestamp: number;
+  installBeginTimestamp: number;
+  installCompleteTimestamp?: number;
+  gclid?: string;
+  fbclid?: string;
+  ttclid?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  referrer?: string;
+}
+
 interface DatalyrNativeModule {
   // Meta SDK Methods
   initializeMetaSDK(
@@ -48,13 +89,29 @@ interface DatalyrNativeModule {
   logoutTikTok(): Promise<boolean>;
   updateTikTokTrackingAuthorization(enabled: boolean): Promise<boolean>;
 
+  // Apple Search Ads Methods (iOS only)
+  getAppleSearchAdsAttribution(): Promise<AppleSearchAdsAttribution | null>;
+
   // SDK Availability
-  getSDKAvailability(): Promise<{ meta: boolean; tiktok: boolean }>;
+  getSDKAvailability(): Promise<{
+    meta: boolean;
+    tiktok: boolean;
+    appleSearchAds: boolean;
+    playInstallReferrer?: boolean;
+  }>;
 }
 
-// Native module is only available on iOS
-const DatalyrNative: DatalyrNativeModule | null =
-  Platform.OS === 'ios' ? NativeModules.DatalyrNative : null;
+interface PlayInstallReferrerModule {
+  isAvailable(): Promise<boolean>;
+  getInstallReferrer(): Promise<PlayInstallReferrerData | null>;
+}
+
+// Native modules - available on both iOS and Android
+const DatalyrNative: DatalyrNativeModule | null = NativeModules.DatalyrNative ?? null;
+
+// Play Install Referrer - Android only
+const DatalyrPlayInstallReferrer: PlayInstallReferrerModule | null =
+  Platform.OS === 'android' ? NativeModules.DatalyrPlayInstallReferrer : null;
 
 /**
  * Check if native module is available
@@ -64,20 +121,34 @@ export const isNativeModuleAvailable = (): boolean => {
 };
 
 /**
- * Get SDK availability status
+ * Get SDK availability status for all platforms
  */
 export const getSDKAvailability = async (): Promise<{
   meta: boolean;
   tiktok: boolean;
+  appleSearchAds: boolean;
+  playInstallReferrer: boolean;
 }> => {
+  const defaultAvailability = {
+    meta: false,
+    tiktok: false,
+    appleSearchAds: false,
+    playInstallReferrer: false,
+  };
+
   if (!DatalyrNative) {
-    return { meta: false, tiktok: false };
+    return defaultAvailability;
   }
 
   try {
-    return await DatalyrNative.getSDKAvailability();
+    const result = await DatalyrNative.getSDKAvailability();
+    return {
+      ...defaultAvailability,
+      ...result,
+      playInstallReferrer: Platform.OS === 'android' && DatalyrPlayInstallReferrer !== null,
+    };
   } catch {
-    return { meta: false, tiktok: false };
+    return defaultAvailability;
   }
 };
 
@@ -269,3 +340,60 @@ export const TikTokNativeBridge = {
     }
   },
 };
+
+// MARK: - Apple Search Ads Bridge (iOS only)
+
+export const AppleSearchAdsNativeBridge = {
+  /**
+   * Get Apple Search Ads attribution data
+   * Uses AdServices framework (iOS 14.3+)
+   * Returns null if user didn't come from Apple Search Ads or on older iOS
+   */
+  async getAttribution(): Promise<AppleSearchAdsAttribution | null> {
+    if (!DatalyrNative || Platform.OS !== 'ios') return null;
+
+    try {
+      return await DatalyrNative.getAppleSearchAdsAttribution();
+    } catch (error) {
+      console.error('[Datalyr/AppleSearchAds] Get attribution failed:', error);
+      return null;
+    }
+  },
+};
+
+// MARK: - Play Install Referrer Bridge (Android only)
+
+export const PlayInstallReferrerNativeBridge = {
+  /**
+   * Check if Play Install Referrer is available
+   * Only available on Android with Google Play Services
+   */
+  async isAvailable(): Promise<boolean> {
+    if (!DatalyrPlayInstallReferrer || Platform.OS !== 'android') return false;
+
+    try {
+      return await DatalyrPlayInstallReferrer.isAvailable();
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Get install referrer data from Google Play
+   *
+   * Returns UTM parameters, click IDs (gclid, fbclid, ttclid), and timestamps
+   * from the Google Play Store referrer.
+   *
+   * Call this on first app launch to capture install attribution.
+   */
+  async getInstallReferrer(): Promise<PlayInstallReferrerData | null> {
+    if (!DatalyrPlayInstallReferrer || Platform.OS !== 'android') return null;
+
+    try {
+      return await DatalyrPlayInstallReferrer.getInstallReferrer();
+    } catch (error) {
+      console.error('[Datalyr/PlayInstallReferrer] Get referrer failed:', error);
+      return null;
+    }
+  },
+};

package/src/native/SKAdNetworkBridge.ts

@@ -1,14 +1,37 @@
 import { NativeModules, Platform } from 'react-native';
 
+// SKAN 4.0 coarse value type
+export type SKANCoarseValue = 'low' | 'medium' | 'high';
+
+// SKAN 4.0 conversion result
+export interface SKANConversionResult {
+  fineValue: number;      // 0-63
+  coarseValue: SKANCoarseValue;
+  lockWindow: boolean;
+  priority: number;
+}
+
 interface SKAdNetworkModule {
   updateConversionValue(value: number): Promise<boolean>;
+  updatePostbackConversionValue(
+    fineValue: number,
+    coarseValue: string,
+    lockWindow: boolean
+  ): Promise<boolean>;
+  isSKAN4Available(): Promise<boolean>;
 }
 
-const { DatalyrSKAdNetwork } = NativeModules as { 
-  DatalyrSKAdNetwork?: SKAdNetworkModule 
+const { DatalyrSKAdNetwork } = NativeModules as {
+  DatalyrSKAdNetwork?: SKAdNetworkModule
 };
 
 export class SKAdNetworkBridge {
+  private static _isSKAN4Available: boolean | null = null;
+
+  /**
+   * SKAN 3.0 - Update conversion value (0-63)
+   * @deprecated Use updatePostbackConversionValue for iOS 16.1+
+   */
   static async updateConversionValue(value: number): Promise<boolean> {
     if (Platform.OS !== 'ios') {
       return false; // Android doesn't support SKAdNetwork
@@ -29,6 +52,67 @@ export class SKAdNetworkBridge {
     }
   }
 
+  /**
+   * SKAN 4.0 - Update postback conversion value with coarse value and lock window
+   * Falls back to SKAN 3.0 on iOS 14.0-16.0
+   */
+  static async updatePostbackConversionValue(
+    result: SKANConversionResult
+  ): Promise<boolean> {
+    if (Platform.OS !== 'ios') {
+      return false; // Android doesn't support SKAdNetwork
+    }
+
+    if (!DatalyrSKAdNetwork) {
+      console.warn('[Datalyr] SKAdNetwork native module not found. Ensure native bridge is properly configured.');
+      return false;
+    }
+
+    try {
+      const success = await DatalyrSKAdNetwork.updatePostbackConversionValue(
+        result.fineValue,
+        result.coarseValue,
+        result.lockWindow
+      );
+
+      const isSKAN4 = await this.isSKAN4Available();
+      if (isSKAN4) {
+        console.log(`[Datalyr] SKAN 4.0 postback updated: fineValue=${result.fineValue}, coarseValue=${result.coarseValue}, lockWindow=${result.lockWindow}`);
+      } else {
+        console.log(`[Datalyr] SKAN 3.0 fallback: conversionValue=${result.fineValue}`);
+      }
+
+      return success;
+    } catch (error) {
+      console.warn('[Datalyr] Failed to update SKAdNetwork postback conversion value:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Check if SKAN 4.0 is available (iOS 16.1+)
+   */
+  static async isSKAN4Available(): Promise<boolean> {
+    if (Platform.OS !== 'ios') {
+      return false;
+    }
+
+    if (this._isSKAN4Available !== null) {
+      return this._isSKAN4Available;
+    }
+
+    if (!DatalyrSKAdNetwork?.isSKAN4Available) {
+      return false;
+    }
+
+    try {
+      this._isSKAN4Available = await DatalyrSKAdNetwork.isSKAN4Available();
+      return this._isSKAN4Available;
+    } catch {
+      return false;
+    }
+  }
+
   static isAvailable(): boolean {
     return Platform.OS === 'ios' && !!DatalyrSKAdNetwork;
   }