@datalyr/react-native 1.1.1 → 1.2.1

package/src/integrations/tiktok-integration.ts

@@ -0,0 +1,360 @@
+/**
+ * TikTok Business SDK Integration
+ * Uses bundled native iOS SDK for event forwarding and user identification
+ */
+
+import { Platform } from 'react-native';
+import { TikTokConfig } from '../types';
+import { TikTokNativeBridge, isNativeModuleAvailable } from '../native/DatalyrNativeBridge';
+
+/**
+ * TikTok standard event names (current as of 2025)
+ * Note: CompletePayment and SubmitForm are legacy, use Purchase and Lead instead
+ */
+const TikTokEvents = {
+  // Commerce events
+  PURCHASE: 'Purchase',
+  ADD_TO_CART: 'AddToCart',
+  ADD_TO_WISHLIST: 'AddToWishlist',
+  INITIATE_CHECKOUT: 'InitiateCheckout',
+  ADD_PAYMENT_INFO: 'AddPaymentInfo',
+  VIEW_CONTENT: 'ViewContent',
+  SEARCH: 'Search',
+
+  // User events
+  COMPLETE_REGISTRATION: 'CompleteRegistration',
+  SUBSCRIBE: 'Subscribe',
+  START_TRIAL: 'StartTrial',
+  LEAD: 'Lead',
+  CONTACT: 'Contact',
+
+  // App events
+  DOWNLOAD: 'Download',
+  SCHEDULE: 'Schedule',
+  SUBMIT_APPLICATION: 'SubmitApplication',
+} as const;
+
+/**
+ * TikTok Integration class for handling TikTok Business SDK operations
+ * Uses native iOS SDK bundled via CocoaPods (no additional npm packages required)
+ */
+export class TikTokIntegration {
+  private config: TikTokConfig | null = null;
+  private initialized: boolean = false;
+  private available: boolean = false;
+  private debug: boolean = false;
+
+  /**
+   * Initialize TikTok SDK with configuration
+   */
+  async initialize(config: TikTokConfig, debug: boolean = false): Promise<void> {
+    this.debug = debug;
+    this.config = config;
+
+    // Only available on iOS via native module
+    if (Platform.OS !== 'ios') {
+      this.log('TikTok SDK only available on iOS');
+      return;
+    }
+
+    this.available = isNativeModuleAvailable();
+
+    if (!this.available) {
+      this.log('TikTok native module not available');
+      return;
+    }
+
+    try {
+      const success = await TikTokNativeBridge.initialize(
+        config.appId,
+        config.tiktokAppId,
+        config.accessToken,
+        debug
+      );
+
+      if (success) {
+        this.initialized = true;
+        this.log(`TikTok SDK initialized with App ID: ${config.tiktokAppId}`);
+      }
+    } catch (error) {
+      this.logError('Failed to initialize TikTok SDK:', error);
+    }
+  }
+
+  /**
+   * Update tracking authorization status (call after ATT prompt)
+   */
+  async updateTrackingAuthorization(enabled: boolean): Promise<void> {
+    if (!this.available || !this.initialized) return;
+
+    try {
+      // TikTok SDK auto-handles ATT, but we track the event
+      if (enabled) {
+        await this.trackEvent('ATTAuthorized');
+      }
+      await TikTokNativeBridge.updateTrackingAuthorization(enabled);
+      this.log(`TikTok ATT status: ${enabled ? 'authorized' : 'not authorized'}`);
+    } catch (error) {
+      this.logError('Failed to update TikTok tracking authorization:', error);
+    }
+  }
+
+  /**
+   * Log purchase event to TikTok (uses Purchase - TikTok's current standard event)
+   */
+  async logPurchase(
+    value: number,
+    currency: string,
+    contentId?: string,
+    contentType?: string,
+    parameters?: Record<string, any>
+  ): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      const properties: Record<string, any> = {
+        value,
+        currency,
+        ...parameters,
+      };
+
+      if (contentId) properties.content_id = contentId;
+      if (contentType) properties.content_type = contentType;
+
+      await TikTokNativeBridge.trackEvent(TikTokEvents.PURCHASE, undefined, properties);
+      this.log(`TikTok Purchase event logged: ${value} ${currency}`);
+    } catch (error) {
+      this.logError('Failed to log TikTok purchase:', error);
+    }
+  }
+
+  /**
+   * Log subscription event to TikTok
+   */
+  async logSubscription(value: number, currency: string, plan?: string): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      const properties: Record<string, any> = {
+        value,
+        currency,
+      };
+
+      if (plan) {
+        properties.content_id = plan;
+        properties.content_type = 'subscription';
+      }
+
+      await TikTokNativeBridge.trackEvent(TikTokEvents.SUBSCRIBE, undefined, properties);
+      this.log(`TikTok subscription event logged: ${value} ${currency}`);
+    } catch (error) {
+      this.logError('Failed to log TikTok subscription:', error);
+    }
+  }
+
+  /**
+   * Log add to cart event
+   */
+  async logAddToCart(value: number, currency: string, contentId?: string, contentType?: string): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      const properties: Record<string, any> = {
+        value,
+        currency,
+      };
+
+      if (contentId) properties.content_id = contentId;
+      if (contentType) properties.content_type = contentType;
+
+      await TikTokNativeBridge.trackEvent(TikTokEvents.ADD_TO_CART, undefined, properties);
+      this.log('TikTok add to cart event logged');
+    } catch (error) {
+      this.logError('Failed to log TikTok add to cart:', error);
+    }
+  }
+
+  /**
+   * Log view content event
+   */
+  async logViewContent(contentId?: string, contentName?: string, contentType?: string): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      const properties: Record<string, any> = {};
+      if (contentId) properties.content_id = contentId;
+      if (contentName) properties.content_name = contentName;
+      if (contentType) properties.content_type = contentType;
+
+      await TikTokNativeBridge.trackEvent(TikTokEvents.VIEW_CONTENT, undefined, properties);
+      this.log('TikTok view content event logged');
+    } catch (error) {
+      this.logError('Failed to log TikTok view content:', error);
+    }
+  }
+
+  /**
+   * Log initiate checkout event
+   */
+  async logInitiateCheckout(value: number, currency: string, numItems?: number): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      const properties: Record<string, any> = {
+        value,
+        currency,
+      };
+      if (numItems) properties.quantity = numItems;
+
+      await TikTokNativeBridge.trackEvent(TikTokEvents.INITIATE_CHECKOUT, undefined, properties);
+      this.log('TikTok initiate checkout event logged');
+    } catch (error) {
+      this.logError('Failed to log TikTok initiate checkout:', error);
+    }
+  }
+
+  /**
+   * Log complete registration event
+   */
+  async logCompleteRegistration(method?: string): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      const properties: Record<string, any> = {};
+      if (method) properties.registration_method = method;
+
+      await TikTokNativeBridge.trackEvent(TikTokEvents.COMPLETE_REGISTRATION, undefined, properties);
+      this.log('TikTok complete registration event logged');
+    } catch (error) {
+      this.logError('Failed to log TikTok complete registration:', error);
+    }
+  }
+
+  /**
+   * Log search event
+   */
+  async logSearch(query: string): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      await TikTokNativeBridge.trackEvent(TikTokEvents.SEARCH, undefined, { query });
+      this.log('TikTok search event logged');
+    } catch (error) {
+      this.logError('Failed to log TikTok search:', error);
+    }
+  }
+
+  /**
+   * Log lead event (uses Lead - current standard, SubmitForm is legacy)
+   */
+  async logLead(value?: number, currency?: string): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      const properties: Record<string, any> = {};
+      if (value !== undefined) properties.value = value;
+      if (currency) properties.currency = currency;
+
+      await TikTokNativeBridge.trackEvent(TikTokEvents.LEAD, undefined, properties);
+      this.log('TikTok lead event logged');
+    } catch (error) {
+      this.logError('Failed to log TikTok lead:', error);
+    }
+  }
+
+  /**
+   * Log add payment info event
+   */
+  async logAddPaymentInfo(success: boolean): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      await TikTokNativeBridge.trackEvent(TikTokEvents.ADD_PAYMENT_INFO, undefined, { success });
+      this.log('TikTok add payment info event logged');
+    } catch (error) {
+      this.logError('Failed to log TikTok add payment info:', error);
+    }
+  }
+
+  /**
+   * Log custom event to TikTok
+   */
+  async trackEvent(eventName: string, properties?: Record<string, any>): Promise<void> {
+    if (!this.available || !this.initialized) return;
+    if (this.config?.enableAppEvents === false) return;
+
+    try {
+      await TikTokNativeBridge.trackEvent(eventName, undefined, properties || {});
+      this.log(`TikTok event logged: ${eventName}`);
+    } catch (error) {
+      this.logError('Failed to log TikTok event:', error);
+    }
+  }
+
+  /**
+   * Identify user for improved attribution matching
+   */
+  async identify(email?: string, phone?: string, externalId?: string): Promise<void> {
+    if (!this.available || !this.initialized) return;
+
+    // Only call identify if we have at least one value
+    if (!email && !phone && !externalId) return;
+
+    try {
+      await TikTokNativeBridge.identify(externalId, email, phone);
+      this.log('TikTok user identification set');
+    } catch (error) {
+      this.logError('Failed to identify TikTok user:', error);
+    }
+  }
+
+  /**
+   * Clear user session (call on logout)
+   */
+  async logout(): Promise<void> {
+    if (!this.available || !this.initialized) return;
+
+    try {
+      await TikTokNativeBridge.logout();
+      this.log('TikTok user logged out');
+    } catch (error) {
+      this.logError('Failed to logout TikTok user:', error);
+    }
+  }
+
+  /**
+   * Check if TikTok SDK is available and initialized
+   */
+  isAvailable(): boolean {
+    return this.available && this.initialized;
+  }
+
+  /**
+   * Check if TikTok SDK native module is installed
+   */
+  isInstalled(): boolean {
+    return this.available;
+  }
+
+  private log(message: string, data?: any): void {
+    if (this.debug) {
+      console.log(`[Datalyr/TikTok] ${message}`, data || '');
+    }
+  }
+
+  private logError(message: string, error: any): void {
+    console.error(`[Datalyr/TikTok] ${message}`, error);
+  }
+}
+
+// Export singleton instance
+export const tiktokIntegration = new TikTokIntegration();

package/src/native/DatalyrNativeBridge.ts

@@ -0,0 +1,313 @@
+/**
+ * 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(
+    appId: string,
+    clientToken: string | null,
+    advertiserTrackingEnabled: boolean
+  ): Promise<boolean>;
+  fetchDeferredAppLink(): Promise<string | null>;
+  logMetaEvent(
+    eventName: string,
+    valueToSum: number | null,
+    parameters: Record<string, any> | null
+  ): Promise<boolean>;
+  logMetaPurchase(
+    amount: number,
+    currency: string,
+    parameters: Record<string, any> | null
+  ): Promise<boolean>;
+  setMetaUserData(userData: Record<string, string | undefined>): Promise<boolean>;
+  clearMetaUserData(): Promise<boolean>;
+  updateMetaTrackingAuthorization(enabled: boolean): Promise<boolean>;
+
+  // TikTok SDK Methods
+  initializeTikTokSDK(
+    appId: string,
+    tiktokAppId: string,
+    accessToken: string | null,
+    debug: boolean
+  ): Promise<boolean>;
+  trackTikTokEvent(
+    eventName: string,
+    eventId: string | null,
+    properties: Record<string, any> | null
+  ): Promise<boolean>;
+  identifyTikTokUser(
+    externalId: string,
+    externalUserName: string,
+    phoneNumber: string,
+    email: string
+  ): Promise<boolean>;
+  logoutTikTok(): Promise<boolean>;
+  updateTikTokTrackingAuthorization(enabled: boolean): Promise<boolean>;
+
+  // Apple Search Ads Methods
+  getAppleSearchAdsAttribution(): Promise<AppleSearchAdsAttribution | null>;
+
+  // SDK Availability
+  getSDKAvailability(): Promise<{ meta: boolean; tiktok: boolean; appleSearchAds: boolean }>;
+}
+
+// Native module is only available on iOS
+const DatalyrNative: DatalyrNativeModule | null =
+  Platform.OS === 'ios' ? NativeModules.DatalyrNative : null;
+
+/**
+ * Check if native module is available
+ */
+export const isNativeModuleAvailable = (): boolean => {
+  return DatalyrNative !== null;
+};
+
+/**
+ * Get SDK availability status
+ */
+export const getSDKAvailability = async (): Promise<{
+  meta: boolean;
+  tiktok: boolean;
+  appleSearchAds: boolean;
+}> => {
+  if (!DatalyrNative) {
+    return { meta: false, tiktok: false, appleSearchAds: false };
+  }
+
+  try {
+    return await DatalyrNative.getSDKAvailability();
+  } catch {
+    return { meta: false, tiktok: false, appleSearchAds: false };
+  }
+};
+
+// MARK: - Meta SDK Bridge
+
+export const MetaNativeBridge = {
+  async initialize(
+    appId: string,
+    clientToken?: string,
+    advertiserTrackingEnabled: boolean = false
+  ): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.initializeMetaSDK(
+        appId,
+        clientToken || null,
+        advertiserTrackingEnabled
+      );
+    } catch (error) {
+      console.error('[Datalyr/MetaNative] Initialize failed:', error);
+      return false;
+    }
+  },
+
+  async fetchDeferredAppLink(): Promise<string | null> {
+    if (!DatalyrNative) return null;
+
+    try {
+      return await DatalyrNative.fetchDeferredAppLink();
+    } catch {
+      return null;
+    }
+  },
+
+  async logEvent(
+    eventName: string,
+    valueToSum?: number,
+    parameters?: Record<string, any>
+  ): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.logMetaEvent(
+        eventName,
+        valueToSum ?? null,
+        parameters || null
+      );
+    } catch (error) {
+      console.error('[Datalyr/MetaNative] Log event failed:', error);
+      return false;
+    }
+  },
+
+  async logPurchase(
+    amount: number,
+    currency: string,
+    parameters?: Record<string, any>
+  ): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.logMetaPurchase(amount, currency, parameters || null);
+    } catch (error) {
+      console.error('[Datalyr/MetaNative] Log purchase failed:', error);
+      return false;
+    }
+  },
+
+  async setUserData(userData: Record<string, string | undefined>): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.setMetaUserData(userData);
+    } catch (error) {
+      console.error('[Datalyr/MetaNative] Set user data failed:', error);
+      return false;
+    }
+  },
+
+  async clearUserData(): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.clearMetaUserData();
+    } catch (error) {
+      console.error('[Datalyr/MetaNative] Clear user data failed:', error);
+      return false;
+    }
+  },
+
+  async updateTrackingAuthorization(enabled: boolean): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.updateMetaTrackingAuthorization(enabled);
+    } catch (error) {
+      console.error('[Datalyr/MetaNative] Update tracking failed:', error);
+      return false;
+    }
+  },
+};
+
+// MARK: - TikTok SDK Bridge
+
+export const TikTokNativeBridge = {
+  async initialize(
+    appId: string,
+    tiktokAppId: string,
+    accessToken?: string,
+    debug: boolean = false
+  ): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.initializeTikTokSDK(
+        appId,
+        tiktokAppId,
+        accessToken || null,
+        debug
+      );
+    } catch (error) {
+      console.error('[Datalyr/TikTokNative] Initialize failed:', error);
+      return false;
+    }
+  },
+
+  async trackEvent(
+    eventName: string,
+    eventId?: string,
+    properties?: Record<string, any>
+  ): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.trackTikTokEvent(
+        eventName,
+        eventId || null,
+        properties || null
+      );
+    } catch (error) {
+      console.error('[Datalyr/TikTokNative] Track event failed:', error);
+      return false;
+    }
+  },
+
+  async identify(
+    externalId?: string,
+    email?: string,
+    phone?: string
+  ): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    // Only call if we have at least one value
+    if (!externalId && !email && !phone) return false;
+
+    try {
+      return await DatalyrNative.identifyTikTokUser(
+        externalId || '',
+        '', // externalUserName - not typically available
+        phone || '',
+        email || ''
+      );
+    } catch (error) {
+      console.error('[Datalyr/TikTokNative] Identify failed:', error);
+      return false;
+    }
+  },
+
+  async logout(): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.logoutTikTok();
+    } catch (error) {
+      console.error('[Datalyr/TikTokNative] Logout failed:', error);
+      return false;
+    }
+  },
+
+  async updateTrackingAuthorization(enabled: boolean): Promise<boolean> {
+    if (!DatalyrNative) return false;
+
+    try {
+      return await DatalyrNative.updateTikTokTrackingAuthorization(enabled);
+    } catch (error) {
+      console.error('[Datalyr/TikTokNative] Update tracking failed:', error);
+      return false;
+    }
+  },
+};
+
+// 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;
+    }
+  },
+};

package/src/native/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Native Module Exports
+ */
+
+export { SKAdNetworkBridge } from './SKAdNetworkBridge';
+export {
+  isNativeModuleAvailable,
+  getSDKAvailability,
+  MetaNativeBridge,
+  TikTokNativeBridge,
+} from './DatalyrNativeBridge';