@loyalytics/swan-react-native-sdk 2.0.2 → 2.1.0

package/lib/module/index.js

@@ -14,7 +14,7 @@
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import Base64 from 'react-native-base64';
 import uuid from 'react-native-uuid';
-import { StyleSheet, View, Modal, PermissionsAndroid, Platform, AppState } from 'react-native';
+import { StyleSheet, View, Modal, PermissionsAndroid, Platform, AppState, Linking } from 'react-native';
 import { SDK_VERSION as PACKAGE_VERSION } from "./version.js";
 import PopUpView from "./components/PopUpView.js";
 import HeaderView from "./components/HeaderView.js";
@@ -130,6 +130,7 @@ export default class SwanSDK {
   pushService = null;
   pendingPushEventListeners = [];
   appStateSubscription = null;
+  linkingSubscription = null;
 
   // Track if initial notification was already handled to prevent duplicate ACKs
   initialNotificationHandled = false;
@@ -308,6 +309,10 @@ export default class SwanSDK {
       this.updateLocation().catch(error => {
         Logger.warn('[SwanSDK] Location update failed:', error);
       });
+
+      // Phase 5: Deep link listeners (non-blocking)
+      Logger.log('[SwanSDK] Phase 5: Setting up deep link listeners...');
+      this.setupDeepLinkListeners();
     } catch (error) {
       Logger.error('[SwanSDK] SDK Initialization failed:', error);
       throw error;
@@ -588,6 +593,180 @@ export default class SwanSDK {
   emitNotificationOpened(payload) {
     this.emit(SwanSDK.EVENTS.NOTIFICATION_OPENED, payload);
   }
+
+  /**
+   * Parse a URL string and extract path and query parameters.
+   * Uses manual parsing to avoid dependency on URL API which has inconsistent
+   * support across React Native/Hermes versions for custom schemes.
+   * @internal
+   */
+  parseDeepLinkUrl(url) {
+    try {
+      if (!url || typeof url !== 'string' || url.trim().length === 0) {
+        return null;
+      }
+      const trimmedUrl = url.trim();
+
+      // Split URL into base and query string
+      const questionMarkIndex = trimmedUrl.indexOf('?');
+      let basePart = '';
+      let queryString = '';
+      if (questionMarkIndex === -1) {
+        basePart = trimmedUrl;
+      } else {
+        basePart = trimmedUrl.substring(0, questionMarkIndex);
+        queryString = trimmedUrl.substring(questionMarkIndex + 1);
+      }
+
+      // Extract path component
+      // For http/https URLs: strip scheme + host (https://example.com/path → /path)
+      // For custom scheme URLs: keep everything after :// (myapp://products/123 → /products/123)
+      let path = basePart;
+      const schemeEnd = basePart.indexOf('://');
+      if (schemeEnd !== -1) {
+        const scheme = basePart.substring(0, schemeEnd).toLowerCase();
+        const afterScheme = basePart.substring(schemeEnd + 3);
+        if (scheme === 'http' || scheme === 'https') {
+          // Strip host for web URLs
+          const firstSlash = afterScheme.indexOf('/');
+          path = firstSlash !== -1 ? afterScheme.substring(firstSlash) : '/';
+        } else {
+          // Custom scheme — entire afterScheme is the route
+          path = '/' + afterScheme;
+        }
+      }
+
+      // Parse query string into key-value pairs
+      const params = {};
+      if (queryString.length > 0) {
+        // Strip fragment identifier if present
+        const hashIndex = queryString.indexOf('#');
+        const cleanQuery = hashIndex !== -1 ? queryString.substring(0, hashIndex) : queryString;
+        const pairs = cleanQuery.split('&');
+        for (const pair of pairs) {
+          const equalsIndex = pair.indexOf('=');
+          if (equalsIndex !== -1) {
+            const key = decodeURIComponent(pair.substring(0, equalsIndex));
+            const value = decodeURIComponent(pair.substring(equalsIndex + 1));
+            if (key.length > 0) {
+              params[key] = value;
+            }
+          } else if (pair.length > 0) {
+            params[decodeURIComponent(pair)] = '';
+          }
+        }
+      }
+      return {
+        path,
+        params
+      };
+    } catch (error) {
+      Logger.error('[SwanSDK] Error parsing deep link URL:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Handle a deep link URL from email, SMS, WhatsApp, or other channels.
+   *
+   * Silently parses the URL, extracts any `swan_` prefixed query parameters,
+   * and tracks a 'deepLinkClicked' event to the backend for campaign attribution.
+   * The host app's existing deep link routing handles navigation — the SDK
+   * only handles attribution tracking.
+   *
+   * If no `swan_` parameters are found, the URL is not a SWAN campaign link
+   * and no tracking occurs.
+   *
+   * @param url - The full deep link URL string
+   * @internal - Called automatically by setupDeepLinkListeners
+   */
+  handleDeepLink(url) {
+    try {
+      Logger.log('[SwanSDK] handleDeepLink called with URL:', url);
+      if (!url || typeof url !== 'string' || url.trim().length === 0) {
+        return;
+      }
+      const parsed = this.parseDeepLinkUrl(url);
+      if (!parsed) {
+        return;
+      }
+
+      // Extract swan_ prefixed parameters
+      const swanParams = {};
+      for (const [key, value] of Object.entries(parsed.params)) {
+        if (key.startsWith('swan_')) {
+          swanParams[key] = value;
+        }
+      }
+
+      // If no SWAN parameters found, this is not a SWAN campaign link
+      if (Object.keys(swanParams).length === 0) {
+        return;
+      }
+      Logger.log('[SwanSDK] Deep link attribution: found SWAN parameters:', JSON.stringify(swanParams));
+
+      // Track click via webhook API (same endpoint as push notification clicks)
+      const commId = swanParams['swan_comm_id'];
+      if (!commId) {
+        Logger.warn('[SwanSDK] Deep link missing swan_comm_id, skipping webhook tracking');
+        return;
+      }
+      const linkId = swanParams['swan_link_id'] || null;
+
+      // Queue as SWAN_NOTIFICATION_ACK with type: 'deepLink' so backend
+      // can distinguish from push notification ACKs (where commId is Firebase's messageId)
+      const ackData = {
+        commId,
+        event: 'clicked',
+        type: 'deepLink',
+        ...(linkId && {
+          linkId
+        }),
+        timestamp: Date.now()
+      };
+      this.trackEvent('SWAN_NOTIFICATION_ACK', ackData).catch(error => {
+        Logger.error('[SwanSDK] Failed to send deep link click ACK:', error);
+      });
+    } catch (error) {
+      Logger.error('[SwanSDK] handleDeepLink: unexpected error:', error);
+    }
+  }
+
+  /**
+   * Set up deep link listeners using React Native Linking API.
+   * Handles both warm start (app already running) and cold start (app launched via deep link).
+   * Called automatically during SDK initialization.
+   * @internal
+   */
+  setupDeepLinkListeners() {
+    try {
+      // Clean up existing listener if any
+      if (this.linkingSubscription) {
+        this.linkingSubscription.remove();
+      }
+
+      // Listen for deep links when app is already running (warm start)
+      this.linkingSubscription = Linking.addEventListener('url', ({
+        url
+      }) => {
+        Logger.log('[SwanSDK] Deep link received (warm start):', url);
+        this.handleDeepLink(url);
+      });
+
+      // Check for initial URL that launched the app (cold start)
+      Linking.getInitialURL().then(initialUrl => {
+        if (initialUrl) {
+          Logger.log('[SwanSDK] Deep link received (cold start):', initialUrl);
+          this.handleDeepLink(initialUrl);
+        }
+      }).catch(error => {
+        Logger.warn('[SwanSDK] Failed to get initial URL:', error);
+      });
+      Logger.log('[SwanSDK] Deep link listeners set up successfully');
+    } catch (error) {
+      Logger.error('[SwanSDK] Failed to set up deep link listeners:', error);
+    }
+  }
   static setLoggingEnabled(enabled) {
     Logger.enableLogs(enabled);
   }
@@ -1094,12 +1273,14 @@ export default class SwanSDK {
         results.push(...enrichResults);
       }
 
-      // 5. Process Ack Events (Individual to /post-in-app-notification-sdk-ack)
+      // 5. Process Ack Events (Individual to webhook/comms/mobile-push-tracking)
       if (ackEvents.length > 0) {
         const ackPromises = ackEvents.map(async event => {
           const {
             commId,
-            event: ackType
+            event: ackType,
+            type,
+            linkId
           } = event.eventData.data;
           const payload = {
             commId,
@@ -1108,6 +1289,10 @@ export default class SwanSDK {
             event: ackType,
             deviceId
           };
+
+          // Deep link ACKs include type and linkId for backend routing
+          if (type) payload.type = type;
+          if (linkId) payload.linkId = linkId;
           const response = await this.sendToSwan(URLS.WEBHOOK_MOBILE_PUSH_URL[this.isProduction], payload);
           return {
             id: event.id,