@datalyr/react-native 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to the Datalyr React Native SDK will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1] - 2025-01
+
+### Added
+- Apple Search Ads attribution support via AdServices framework (iOS 14.3+)
+- `getAppleSearchAdsAttribution()` method to retrieve attribution data
+- Automatic capture of Apple Search Ads attribution on SDK initialization
+- Apple Search Ads data included in all events (asa_campaign_id, asa_keyword, etc.)
+
 ## [1.2.0] - 2025-01
 
 ### Added

package/README.md

@@ -23,6 +23,9 @@ Mobile analytics and attribution SDK for React Native and Expo. Track events, id
 - [Auto Events](#auto-events)
 - [SKAdNetwork](#skadnetwork)
 - [Platform Integrations](#platform-integrations)
+  - [Meta](#meta-facebook)
+  - [TikTok](#tiktok)
+  - [Apple Search Ads](#apple-search-ads)
 - [Expo Support](#expo-support)
 - [TypeScript](#typescript)
 - [Troubleshooting](#troubleshooting)
@@ -482,6 +485,32 @@ await Datalyr.initialize({
 });
 ```
 
+### Apple Search Ads
+
+Attribution for users who install from Apple Search Ads (iOS 14.3+). Automatically fetched on initialization.
+
+```typescript
+// Check if user came from Apple Search Ads
+const asaAttribution = Datalyr.getAppleSearchAdsAttribution();
+
+if (asaAttribution?.attribution) {
+  console.log(asaAttribution.campaignId);    // Campaign ID
+  console.log(asaAttribution.campaignName);  // Campaign name
+  console.log(asaAttribution.adGroupId);     // Ad group ID
+  console.log(asaAttribution.keyword);       // Search keyword
+  console.log(asaAttribution.clickDate);     // Click date
+}
+```
+
+Attribution data is automatically included in all events with the `asa_` prefix:
+- `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`
+
+No additional configuration needed. The SDK uses Apple's AdServices API.
+
 ### App Tracking Transparency
 
 Update after ATT dialog:
@@ -495,7 +524,7 @@ await Datalyr.updateTrackingAuthorization(status === 'granted');
 
 ```typescript
 const status = Datalyr.getPlatformIntegrationStatus();
-// { meta: true, tiktok: true }
+// { meta: true, tiktok: true, appleSearchAds: true }
 ```
 
 ---

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/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;
@@ -138,7 +139,13 @@ export declare class DatalyrSDK {
     getPlatformIntegrationStatus(): {
         meta: boolean;
         tiktok: boolean;
+        appleSearchAds: boolean;
     };
+    /**
+     * Get Apple Search Ads attribution data
+     * Returns attribution if user installed via Apple Search Ads, null otherwise
+     */
+    getAppleSearchAdsAttribution(): AppleSearchAdsAttribution | null;
     /**
      * Update tracking authorization status on all platform SDKs
      * Call this AFTER the user responds to the ATT permission dialog
@@ -234,7 +241,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;

package/lib/datalyr-sdk.js

@@ -6,7 +6,7 @@ import { attributionManager } from './attribution';
 import { AutoEventsManager } from './auto-events';
 import { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 import { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
-import { metaIntegration, tiktokIntegration } from './integrations';
+import { metaIntegration, tiktokIntegration, appleSearchAdsIntegration } from './integrations';
 export class DatalyrSDK {
     constructor() {
         this.autoEventsManager = null;
@@ -132,9 +132,12 @@ export class DatalyrSDK {
             if (((_c = config.tiktok) === null || _c === void 0 ? void 0 : _c.appId) && ((_d = config.tiktok) === null || _d === void 0 ? void 0 : _d.tiktokAppId)) {
                 await tiktokIntegration.initialize(config.tiktok, config.debug);
             }
+            // Initialize Apple Search Ads attribution (iOS only, auto-fetches on init)
+            await appleSearchAdsIntegration.initialize(config.debug);
             debugLog('Platform integrations initialized', {
                 meta: metaIntegration.isAvailable(),
                 tiktok: tiktokIntegration.isAvailable(),
+                appleSearchAds: appleSearchAdsIntegration.isAvailable(),
             });
             // SDK initialized successfully - set state before tracking install event
             this.state.initialized = true;
@@ -672,8 +675,16 @@ export class DatalyrSDK {
         return {
             meta: metaIntegration.isAvailable(),
             tiktok: tiktokIntegration.isAvailable(),
+            appleSearchAds: appleSearchAdsIntegration.isAvailable(),
         };
     }
+    /**
+     * Get Apple Search Ads attribution data
+     * Returns attribution if user installed via Apple Search Ads, null otherwise
+     */
+    getAppleSearchAdsAttribution() {
+        return appleSearchAdsIntegration.getAttributionData();
+    }
     /**
      * Update tracking authorization status on all platform SDKs
      * Call this AFTER the user responds to the ATT permission dialog
@@ -745,6 +756,21 @@ export class DatalyrSDK {
         const deviceInfo = await getDeviceInfo();
         const fingerprintData = await createFingerprintData();
         const attributionData = attributionManager.getAttributionData();
+        // Get Apple Search Ads attribution if available
+        const asaAttribution = appleSearchAdsIntegration.getAttributionData();
+        const asaData = (asaAttribution === null || asaAttribution === void 0 ? void 0 : asaAttribution.attribution) ? {
+            asa_campaign_id: asaAttribution.campaignId,
+            asa_campaign_name: asaAttribution.campaignName,
+            asa_ad_group_id: asaAttribution.adGroupId,
+            asa_ad_group_name: asaAttribution.adGroupName,
+            asa_keyword_id: asaAttribution.keywordId,
+            asa_keyword: asaAttribution.keyword,
+            asa_org_id: asaAttribution.orgId,
+            asa_org_name: asaAttribution.orgName,
+            asa_click_date: asaAttribution.clickDate,
+            asa_conversion_type: asaAttribution.conversionType,
+            asa_country_or_region: asaAttribution.countryOrRegion,
+        } : {};
         const payload = {
             workspaceId: this.state.config.workspaceId || 'mobile_sdk',
             visitorId: this.state.visitorId,
@@ -766,6 +792,8 @@ export class DatalyrSDK {
                 timestamp: Date.now(),
                 // Attribution data
                 ...attributionData,
+                // Apple Search Ads attribution
+                ...asaData,
             },
             fingerprintData,
             source: 'mobile_app',
@@ -999,6 +1027,9 @@ export class Datalyr {
     static getPlatformIntegrationStatus() {
         return datalyr.getPlatformIntegrationStatus();
     }
+    static getAppleSearchAdsAttribution() {
+        return datalyr.getAppleSearchAdsAttribution();
+    }
     static async updateTrackingAuthorization(enabled) {
         await datalyr.updateTrackingAuthorization(enabled);
     }

package/lib/index.d.ts

@@ -10,5 +10,6 @@ export * from './event-queue';
 export { DatalyrSDK };
 export { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 export { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
-export { metaIntegration, tiktokIntegration } from './integrations';
+export { metaIntegration, tiktokIntegration, appleSearchAdsIntegration } from './integrations';
+export type { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';
 export default DatalyrSDK;

package/lib/index.js

@@ -19,6 +19,6 @@ export { DatalyrSDK };
 export { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 export { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
 // Export platform integrations
-export { metaIntegration, tiktokIntegration } from './integrations';
+export { metaIntegration, tiktokIntegration, appleSearchAdsIntegration } from './integrations';
 // Default export for compatibility
 export default DatalyrSDK;

package/lib/integrations/apple-search-ads-integration.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Apple Search Ads Attribution Integration
+ * Uses AdServices framework (iOS 14.3+) to capture attribution from App Store search ads
+ */
+import { AppleSearchAdsAttribution } from '../native/DatalyrNativeBridge';
+/**
+ * Apple Search Ads Integration class
+ * Fetches attribution data for users who installed via Apple Search Ads
+ */
+export declare class AppleSearchAdsIntegration {
+    private attributionData;
+    private fetched;
+    private available;
+    private debug;
+    /**
+     * Initialize and fetch Apple Search Ads attribution
+     */
+    initialize(debug?: boolean): Promise<void>;
+    /**
+     * Fetch attribution data from Apple's AdServices API
+     * Call this during app initialization
+     */
+    fetchAttribution(): Promise<AppleSearchAdsAttribution | null>;
+    /**
+     * Get cached attribution data
+     */
+    getAttributionData(): AppleSearchAdsAttribution | null;
+    /**
+     * Check if user came from Apple Search Ads
+     */
+    hasAttribution(): boolean;
+    /**
+     * Check if Apple Search Ads is available (iOS 14.3+)
+     */
+    isAvailable(): boolean;
+    /**
+     * Check if attribution has been fetched
+     */
+    hasFetched(): boolean;
+    private log;
+    private logError;
+}
+export declare const appleSearchAdsIntegration: AppleSearchAdsIntegration;

package/lib/integrations/apple-search-ads-integration.js

@@ -0,0 +1,106 @@
+/**
+ * Apple Search Ads Attribution Integration
+ * Uses AdServices framework (iOS 14.3+) to capture attribution from App Store search ads
+ */
+import { Platform } from 'react-native';
+import { AppleSearchAdsNativeBridge, isNativeModuleAvailable } from '../native/DatalyrNativeBridge';
+/**
+ * Apple Search Ads Integration class
+ * Fetches attribution data for users who installed via Apple Search Ads
+ */
+export class AppleSearchAdsIntegration {
+    constructor() {
+        this.attributionData = null;
+        this.fetched = false;
+        this.available = false;
+        this.debug = false;
+    }
+    /**
+     * Initialize and fetch Apple Search Ads attribution
+     */
+    async initialize(debug = false) {
+        this.debug = debug;
+        // Only available on iOS via native module
+        if (Platform.OS !== 'ios') {
+            this.log('Apple Search Ads only available on iOS');
+            return;
+        }
+        this.available = isNativeModuleAvailable();
+        if (!this.available) {
+            this.log('Apple Search Ads native module not available');
+            return;
+        }
+        // Automatically fetch attribution on init
+        await this.fetchAttribution();
+    }
+    /**
+     * Fetch attribution data from Apple's AdServices API
+     * Call this during app initialization
+     */
+    async fetchAttribution() {
+        var _a;
+        if (!this.available) {
+            return null;
+        }
+        // Only fetch once
+        if (this.fetched) {
+            return this.attributionData;
+        }
+        try {
+            this.attributionData = await AppleSearchAdsNativeBridge.getAttribution();
+            this.fetched = true;
+            if ((_a = this.attributionData) === null || _a === void 0 ? void 0 : _a.attribution) {
+                this.log('Apple Search Ads attribution found:', {
+                    campaignId: this.attributionData.campaignId,
+                    campaignName: this.attributionData.campaignName,
+                    adGroupId: this.attributionData.adGroupId,
+                    keyword: this.attributionData.keyword,
+                });
+            }
+            else {
+                this.log('No Apple Search Ads attribution (user did not come from search ad)');
+            }
+            return this.attributionData;
+        }
+        catch (error) {
+            this.logError('Failed to fetch Apple Search Ads attribution:', error);
+            this.fetched = true;
+            return null;
+        }
+    }
+    /**
+     * Get cached attribution data
+     */
+    getAttributionData() {
+        return this.attributionData;
+    }
+    /**
+     * Check if user came from Apple Search Ads
+     */
+    hasAttribution() {
+        var _a;
+        return ((_a = this.attributionData) === null || _a === void 0 ? void 0 : _a.attribution) === true;
+    }
+    /**
+     * Check if Apple Search Ads is available (iOS 14.3+)
+     */
+    isAvailable() {
+        return this.available;
+    }
+    /**
+     * Check if attribution has been fetched
+     */
+    hasFetched() {
+        return this.fetched;
+    }
+    log(message, data) {
+        if (this.debug) {
+            console.log(`[Datalyr/AppleSearchAds] ${message}`, data || '');
+        }
+    }
+    logError(message, error) {
+        console.error(`[Datalyr/AppleSearchAds] ${message}`, error);
+    }
+}
+// Export singleton instance
+export const appleSearchAdsIntegration = new AppleSearchAdsIntegration();

package/lib/integrations/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * Platform SDK Integrations
- * Meta (Facebook) and TikTok SDK wrappers for deferred deep linking and event forwarding
+ * Meta (Facebook), TikTok, and Apple Search Ads SDK wrappers
  */
 export { MetaIntegration, metaIntegration } from './meta-integration';
 export { TikTokIntegration, tiktokIntegration } from './tiktok-integration';
+export { AppleSearchAdsIntegration, appleSearchAdsIntegration } from './apple-search-ads-integration';

package/lib/integrations/index.js

@@ -1,6 +1,7 @@
 /**
  * Platform SDK Integrations
- * Meta (Facebook) and TikTok SDK wrappers for deferred deep linking and event forwarding
+ * Meta (Facebook), TikTok, and Apple Search Ads SDK wrappers
  */
 export { MetaIntegration, metaIntegration } from './meta-integration';
 export { TikTokIntegration, tiktokIntegration } from './tiktok-integration';
+export { AppleSearchAdsIntegration, appleSearchAdsIntegration } from './apple-search-ads-integration';

package/lib/native/DatalyrNativeBridge.d.ts

@@ -1,7 +1,24 @@
 /**
- * Native Bridge for Meta and TikTok SDKs
+ * Native Bridge for Meta, TikTok, and Apple Search Ads
  * Uses bundled native modules instead of separate npm packages
  */
+/**
+ * Apple Search Ads attribution data returned from AdServices API
+ */
+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;
+}
 /**
  * Check if native module is available
  */
@@ -12,6 +29,7 @@ export declare const isNativeModuleAvailable: () => boolean;
 export declare const getSDKAvailability: () => Promise<{
     meta: boolean;
     tiktok: boolean;
+    appleSearchAds: boolean;
 }>;
 export declare const MetaNativeBridge: {
     initialize(appId: string, clientToken?: string, advertiserTrackingEnabled?: boolean): Promise<boolean>;
@@ -29,3 +47,11 @@ export declare const TikTokNativeBridge: {
     logout(): Promise<boolean>;
     updateTrackingAuthorization(enabled: boolean): Promise<boolean>;
 };
+export declare 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
+     */
+    getAttribution(): Promise<AppleSearchAdsAttribution | null>;
+};

package/lib/native/DatalyrNativeBridge.js

@@ -1,5 +1,5 @@
 /**
- * Native Bridge for Meta and TikTok SDKs
+ * Native Bridge for Meta, TikTok, and Apple Search Ads
  * Uses bundled native modules instead of separate npm packages
  */
 import { NativeModules, Platform } from 'react-native';
@@ -16,13 +16,13 @@ export const isNativeModuleAvailable = () => {
  */
 export const getSDKAvailability = async () => {
     if (!DatalyrNative) {
-        return { meta: false, tiktok: false };
+        return { meta: false, tiktok: false, appleSearchAds: false };
     }
     try {
         return await DatalyrNative.getSDKAvailability();
     }
     catch (_a) {
-        return { meta: false, tiktok: false };
+        return { meta: false, tiktok: false, appleSearchAds: false };
     }
 };
 // MARK: - Meta SDK Bridge
@@ -166,3 +166,22 @@ export const TikTokNativeBridge = {
         }
     },
 };
+// MARK: - Apple Search Ads Bridge
+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() {
+        if (!DatalyrNative)
+            return null;
+        try {
+            return await DatalyrNative.getAppleSearchAdsAttribution();
+        }
+        catch (error) {
+            console.error('[Datalyr/AppleSearchAds] Get attribution failed:', error);
+            return null;
+        }
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalyr/react-native",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Datalyr SDK for React Native & Expo - Server-side attribution tracking with bundled Meta and TikTok SDKs",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -38,6 +38,7 @@
     "tiktok-attribution",
     "google-attribution",
     "ios-attribution",
+    "apple-search-ads",
     "conversion-tracking",
     "revenue-optimization",
     "deferred-deep-linking",

package/src/datalyr-sdk-expo.ts

@@ -33,8 +33,9 @@ import { attributionManager, AttributionData } from './attribution';
 import { createAutoEventsManager, AutoEventsManager } from './auto-events';
 import { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 import { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
-import { metaIntegration, tiktokIntegration } from './integrations';
+import { metaIntegration, tiktokIntegration, appleSearchAdsIntegration } from './integrations';
 import { DeferredDeepLinkResult } from './types';
+import { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';
 
 export class DatalyrSDKExpo {
   private state: SDKState;
@@ -176,6 +177,14 @@ export class DatalyrSDKExpo {
         }
       }
 
+      // Initialize Apple Search Ads attribution (iOS only, auto-fetches on init)
+      await appleSearchAdsIntegration.initialize(config.debug);
+      debugLog('Platform integrations initialized', {
+        meta: metaIntegration.isAvailable(),
+        tiktok: tiktokIntegration.isAvailable(),
+        appleSearchAds: appleSearchAdsIntegration.isAvailable(),
+      });
+
       this.state.initialized = true;
 
       if (attributionManager.isInstall()) {
@@ -636,13 +645,22 @@ export class DatalyrSDKExpo {
     return null;
   }
 
-  getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean } {
+  getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean; appleSearchAds: boolean } {
     return {
       meta: metaIntegration.isAvailable(),
       tiktok: tiktokIntegration.isAvailable(),
+      appleSearchAds: appleSearchAdsIntegration.isAvailable(),
     };
   }
 
+  /**
+   * Get Apple Search Ads attribution data
+   * Returns attribution if user installed via Apple Search Ads, null otherwise
+   */
+  getAppleSearchAdsAttribution(): AppleSearchAdsAttribution | null {
+    return appleSearchAdsIntegration.getAttributionData();
+  }
+
   async updateTrackingAuthorization(authorized: boolean): Promise<void> {
     if (metaIntegration.isAvailable()) {
       metaIntegration.updateTrackingAuthorization(authorized);
@@ -694,6 +712,22 @@ export class DatalyrSDKExpo {
     const attributionData = attributionManager.getAttributionData();
     const networkType = await getNetworkType();
 
+    // Get Apple Search Ads attribution if available
+    const asaAttribution = appleSearchAdsIntegration.getAttributionData();
+    const asaData = asaAttribution?.attribution ? {
+      asa_campaign_id: asaAttribution.campaignId,
+      asa_campaign_name: asaAttribution.campaignName,
+      asa_ad_group_id: asaAttribution.adGroupId,
+      asa_ad_group_name: asaAttribution.adGroupName,
+      asa_keyword_id: asaAttribution.keywordId,
+      asa_keyword: asaAttribution.keyword,
+      asa_org_id: asaAttribution.orgId,
+      asa_org_name: asaAttribution.orgName,
+      asa_click_date: asaAttribution.clickDate,
+      asa_conversion_type: asaAttribution.conversionType,
+      asa_country_or_region: asaAttribution.countryOrRegion,
+    } : {};
+
     const payload: EventPayload = {
       workspaceId: this.state.config.workspaceId || 'mobile_sdk',
       visitorId: this.state.visitorId,
@@ -713,6 +747,8 @@ export class DatalyrSDKExpo {
         timestamp: Date.now(),
         sdk_variant: 'expo',
         ...attributionData,
+        // Apple Search Ads attribution
+        ...asaData,
       },
       fingerprintData,
       source: 'mobile_app',
@@ -945,10 +981,14 @@ export class DatalyrExpo {
     return datalyrExpo.getDeferredAttributionData();
   }
 
-  static getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean } {
+  static getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean; appleSearchAds: boolean } {
     return datalyrExpo.getPlatformIntegrationStatus();
   }
 
+  static getAppleSearchAdsAttribution(): AppleSearchAdsAttribution | null {
+    return datalyrExpo.getAppleSearchAdsAttribution();
+  }
+
   static async updateTrackingAuthorization(authorized: boolean): Promise<void> {
     await datalyrExpo.updateTrackingAuthorization(authorized);
   }

package/src/datalyr-sdk.ts

@@ -30,7 +30,8 @@ import { attributionManager, AttributionData } from './attribution';
 import { createAutoEventsManager, AutoEventsManager, SessionData } from './auto-events';
 import { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 import { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
-import { metaIntegration, tiktokIntegration } from './integrations';
+import { metaIntegration, tiktokIntegration, appleSearchAdsIntegration } from './integrations';
+import { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';
 
 export class DatalyrSDK {
   private state: SDKState;
@@ -181,9 +182,13 @@ export class DatalyrSDK {
         await tiktokIntegration.initialize(config.tiktok, config.debug);
       }
 
+      // Initialize Apple Search Ads attribution (iOS only, auto-fetches on init)
+      await appleSearchAdsIntegration.initialize(config.debug);
+
       debugLog('Platform integrations initialized', {
         meta: metaIntegration.isAvailable(),
         tiktok: tiktokIntegration.isAvailable(),
+        appleSearchAds: appleSearchAdsIntegration.isAvailable(),
       });
 
       // SDK initialized successfully - set state before tracking install event
@@ -832,13 +837,22 @@ export class DatalyrSDK {
   /**
    * Get platform integration status
    */
-  getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean } {
+  getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean; appleSearchAds: boolean } {
     return {
       meta: metaIntegration.isAvailable(),
       tiktok: tiktokIntegration.isAvailable(),
+      appleSearchAds: appleSearchAdsIntegration.isAvailable(),
     };
   }
 
+  /**
+   * Get Apple Search Ads attribution data
+   * Returns attribution if user installed via Apple Search Ads, null otherwise
+   */
+  getAppleSearchAdsAttribution(): AppleSearchAdsAttribution | null {
+    return appleSearchAdsIntegration.getAttributionData();
+  }
+
   /**
    * Update tracking authorization status on all platform SDKs
    * Call this AFTER the user responds to the ATT permission dialog
@@ -919,6 +933,22 @@ export class DatalyrSDK {
     const fingerprintData = await createFingerprintData();
     const attributionData = attributionManager.getAttributionData();
 
+    // Get Apple Search Ads attribution if available
+    const asaAttribution = appleSearchAdsIntegration.getAttributionData();
+    const asaData = asaAttribution?.attribution ? {
+      asa_campaign_id: asaAttribution.campaignId,
+      asa_campaign_name: asaAttribution.campaignName,
+      asa_ad_group_id: asaAttribution.adGroupId,
+      asa_ad_group_name: asaAttribution.adGroupName,
+      asa_keyword_id: asaAttribution.keywordId,
+      asa_keyword: asaAttribution.keyword,
+      asa_org_id: asaAttribution.orgId,
+      asa_org_name: asaAttribution.orgName,
+      asa_click_date: asaAttribution.clickDate,
+      asa_conversion_type: asaAttribution.conversionType,
+      asa_country_or_region: asaAttribution.countryOrRegion,
+    } : {};
+
     const payload: EventPayload = {
       workspaceId: this.state.config.workspaceId || 'mobile_sdk',
       visitorId: this.state.visitorId,
@@ -940,6 +970,8 @@ export class DatalyrSDK {
         timestamp: Date.now(),
         // Attribution data
         ...attributionData,
+        // Apple Search Ads attribution
+        ...asaData,
       },
       fingerprintData,
       source: 'mobile_app',
@@ -1239,10 +1271,14 @@ export class Datalyr {
     return datalyr.getDeferredAttributionData();
   }
 
-  static getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean } {
+  static getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean; appleSearchAds: boolean } {
     return datalyr.getPlatformIntegrationStatus();
   }
 
+  static getAppleSearchAdsAttribution(): AppleSearchAdsAttribution | null {
+    return datalyr.getAppleSearchAdsAttribution();
+  }
+
   static async updateTrackingAuthorization(enabled: boolean): Promise<void> {
     await datalyr.updateTrackingAuthorization(enabled);
   }

package/src/expo.ts

@@ -52,5 +52,9 @@ export * from './event-queue';
 export { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 export { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
 
+// Export platform integrations
+export { appleSearchAdsIntegration } from './integrations';
+export type { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';
+
 // Default export
 export default datalyrExpo;

package/src/index.ts

@@ -27,7 +27,10 @@ export { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEn
 export { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
 
 // Export platform integrations
-export { metaIntegration, tiktokIntegration } from './integrations';
+export { metaIntegration, tiktokIntegration, appleSearchAdsIntegration } from './integrations';
+
+// Export native bridge types
+export type { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';
 
 // Default export for compatibility
 export default DatalyrSDK; 

package/src/integrations/apple-search-ads-integration.ts

@@ -0,0 +1,119 @@
+/**
+ * Apple Search Ads Attribution Integration
+ * Uses AdServices framework (iOS 14.3+) to capture attribution from App Store search ads
+ */
+
+import { Platform } from 'react-native';
+import { AppleSearchAdsNativeBridge, AppleSearchAdsAttribution, isNativeModuleAvailable } from '../native/DatalyrNativeBridge';
+
+/**
+ * Apple Search Ads Integration class
+ * Fetches attribution data for users who installed via Apple Search Ads
+ */
+export class AppleSearchAdsIntegration {
+  private attributionData: AppleSearchAdsAttribution | null = null;
+  private fetched: boolean = false;
+  private available: boolean = false;
+  private debug: boolean = false;
+
+  /**
+   * Initialize and fetch Apple Search Ads attribution
+   */
+  async initialize(debug: boolean = false): Promise<void> {
+    this.debug = debug;
+
+    // Only available on iOS via native module
+    if (Platform.OS !== 'ios') {
+      this.log('Apple Search Ads only available on iOS');
+      return;
+    }
+
+    this.available = isNativeModuleAvailable();
+
+    if (!this.available) {
+      this.log('Apple Search Ads native module not available');
+      return;
+    }
+
+    // Automatically fetch attribution on init
+    await this.fetchAttribution();
+  }
+
+  /**
+   * Fetch attribution data from Apple's AdServices API
+   * Call this during app initialization
+   */
+  async fetchAttribution(): Promise<AppleSearchAdsAttribution | null> {
+    if (!this.available) {
+      return null;
+    }
+
+    // Only fetch once
+    if (this.fetched) {
+      return this.attributionData;
+    }
+
+    try {
+      this.attributionData = await AppleSearchAdsNativeBridge.getAttribution();
+      this.fetched = true;
+
+      if (this.attributionData?.attribution) {
+        this.log('Apple Search Ads attribution found:', {
+          campaignId: this.attributionData.campaignId,
+          campaignName: this.attributionData.campaignName,
+          adGroupId: this.attributionData.adGroupId,
+          keyword: this.attributionData.keyword,
+        });
+      } else {
+        this.log('No Apple Search Ads attribution (user did not come from search ad)');
+      }
+
+      return this.attributionData;
+    } catch (error) {
+      this.logError('Failed to fetch Apple Search Ads attribution:', error);
+      this.fetched = true;
+      return null;
+    }
+  }
+
+  /**
+   * Get cached attribution data
+   */
+  getAttributionData(): AppleSearchAdsAttribution | null {
+    return this.attributionData;
+  }
+
+  /**
+   * Check if user came from Apple Search Ads
+   */
+  hasAttribution(): boolean {
+    return this.attributionData?.attribution === true;
+  }
+
+  /**
+   * Check if Apple Search Ads is available (iOS 14.3+)
+   */
+  isAvailable(): boolean {
+    return this.available;
+  }
+
+  /**
+   * Check if attribution has been fetched
+   */
+  hasFetched(): boolean {
+    return this.fetched;
+  }
+
+  private log(message: string, data?: any): void {
+    if (this.debug) {
+      console.log(`[Datalyr/AppleSearchAds] ${message}`, data || '');
+    }
+  }
+
+  private logError(message: string, error: any): void {
+    console.error(`[Datalyr/AppleSearchAds] ${message}`, error);
+  }
+}
+
+// Export singleton instance
+export const appleSearchAdsIntegration = new AppleSearchAdsIntegration();

package/src/integrations/index.ts

@@ -1,7 +1,8 @@
 /**
  * Platform SDK Integrations
- * Meta (Facebook) and TikTok SDK wrappers for deferred deep linking and event forwarding
+ * Meta (Facebook), TikTok, and Apple Search Ads SDK wrappers
  */
 
 export { MetaIntegration, metaIntegration } from './meta-integration';
 export { TikTokIntegration, tiktokIntegration } from './tiktok-integration';
+export { AppleSearchAdsIntegration, appleSearchAdsIntegration } from './apple-search-ads-integration';

package/src/native/DatalyrNativeBridge.ts

@@ -1,10 +1,28 @@
 /**
- * Native Bridge for Meta and TikTok SDKs
+ * Native Bridge for Meta, TikTok, and Apple Search Ads
  * Uses bundled native modules instead of separate npm packages
  */
 
 import { NativeModules, Platform } from 'react-native';
 
+/**
+ * Apple Search Ads attribution data returned from AdServices API
+ */
+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;
+}
+
 interface DatalyrNativeModule {
   // Meta SDK Methods
   initializeMetaSDK(
@@ -48,8 +66,11 @@ interface DatalyrNativeModule {
   logoutTikTok(): Promise<boolean>;
   updateTikTokTrackingAuthorization(enabled: boolean): Promise<boolean>;
 
+  // Apple Search Ads Methods
+  getAppleSearchAdsAttribution(): Promise<AppleSearchAdsAttribution | null>;
+
   // SDK Availability
-  getSDKAvailability(): Promise<{ meta: boolean; tiktok: boolean }>;
+  getSDKAvailability(): Promise<{ meta: boolean; tiktok: boolean; appleSearchAds: boolean }>;
 }
 
 // Native module is only available on iOS
@@ -69,15 +90,16 @@ export const isNativeModuleAvailable = (): boolean => {
 export const getSDKAvailability = async (): Promise<{
   meta: boolean;
   tiktok: boolean;
+  appleSearchAds: boolean;
 }> => {
   if (!DatalyrNative) {
-    return { meta: false, tiktok: false };
+    return { meta: false, tiktok: false, appleSearchAds: false };
   }
 
   try {
     return await DatalyrNative.getSDKAvailability();
   } catch {
-    return { meta: false, tiktok: false };
+    return { meta: false, tiktok: false, appleSearchAds: false };
   }
 };
 
@@ -269,3 +291,23 @@ export const TikTokNativeBridge = {
     }
   },
 };
+
+// MARK: - Apple Search Ads Bridge
+
+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) return null;
+
+    try {
+      return await DatalyrNative.getAppleSearchAdsAttribution();
+    } catch (error) {
+      console.error('[Datalyr/AppleSearchAds] Get attribution failed:', error);
+      return null;
+    }
+  },
+};