insert-affiliate-react-native-sdk 1.9.0 → 1.11.1

package/src/DeepLinkIapProvider.tsx

@@ -1,4 +1,4 @@
-import React, { createContext, useEffect, useState, useRef } from 'react';
+import React, { createContext, useEffect, useState, useRef, useCallback } from 'react';
 import { Platform, Linking, Dimensions, PixelRatio } from 'react-native';
 import axios from 'axios';
 import AsyncStorage from '@react-native-async-storage/async-storage';
@@ -80,8 +80,19 @@ const ASYNC_KEYS = {
   USER_ACCOUNT_TOKEN: '@app_user_account_token',
   IOS_OFFER_CODE: '@app_ios_offer_code',
   AFFILIATE_STORED_DATE: '@app_affiliate_stored_date',
+  SDK_INIT_REPORTED: '@app_sdk_init_reported',
+  REPORTED_AFFILIATE_ASSOCIATIONS: '@app_reported_affiliate_associations',
 };
 
+// Source types for affiliate association tracking
+type AffiliateAssociationSource =
+  | 'deep_link_ios'      // iOS custom URL scheme (ia-companycode://shortcode)
+  | 'deep_link_android'  // Android deep link with ?insertAffiliate= param
+  | 'install_referrer'   // Android Play Store install referrer
+  | 'clipboard_match'    // iOS clipboard UUID match from backend
+  | 'short_code_manual'  // Developer called setShortCode()
+  | 'referring_link';    // Developer called setInsertAffiliateIdentifier()
+
 // STARTING CONTEXT IMPLEMENTATION
 export const DeepLinkIapContext = createContext<T_DEEPLINK_IAP_CONTEXT>({
   referrerLink: '',
@@ -121,49 +132,74 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
   const [OfferCode, setOfferCode] = useState<string | null>(null);
   const [affiliateAttributionActiveTime, setAffiliateAttributionActiveTime] = useState<number | null>(null);
   const insertAffiliateIdentifierChangeCallbackRef = useRef<InsertAffiliateIdentifierChangeCallback | null>(null);
+  const isInitializingRef = useRef<boolean>(false);
+
+  // Refs for values that need to be current inside callbacks (to avoid stale closures)
+  const companyCodeRef = useRef<string | null>(null);
+  const verboseLoggingRef = useRef<boolean>(false);
+
+  // Refs for implementation functions (ref callback pattern for stable + fresh)
+  const initializeImplRef = useRef<(code: string | null, verboseLogging?: boolean, insertLinksEnabled?: boolean, insertLinksClipboardEnabled?: boolean, affiliateAttributionActiveTime?: number) => Promise<void>>(null as any);
+  const setShortCodeImplRef = useRef<(shortCode: string) => Promise<boolean>>(null as any);
+  const getAffiliateDetailsImplRef = useRef<(affiliateCode: string) => Promise<AffiliateDetails>>(null as any);
+  const returnInsertAffiliateIdentifierImplRef = useRef<(ignoreTimeout?: boolean) => Promise<string | null>>(null as any);
+  const isAffiliateAttributionValidImplRef = useRef<() => Promise<boolean>>(null as any);
+  const getAffiliateStoredDateImplRef = useRef<() => Promise<Date | null>>(null as any);
+  const storeExpectedStoreTransactionImplRef = useRef<(purchaseToken: string) => Promise<void>>(null as any);
+  const returnUserAccountTokenAndStoreExpectedTransactionImplRef = useRef<() => Promise<string | null>>(null as any);
+  const validatePurchaseWithIapticAPIImplRef = useRef<(jsonIapPurchase: CustomPurchase, iapticAppId: string, iapticAppName: string, iapticPublicKey: string) => Promise<boolean>>(null as any);
+  const trackEventImplRef = useRef<(eventName: string) => Promise<void>>(null as any);
+  const setInsertAffiliateIdentifierImplRef = useRef<(referringLink: string) => Promise<void | string>>(null as any);
+  const handleInsertLinksImplRef = useRef<(url: string) => Promise<boolean>>(null as any);
 
   // MARK: Initialize the SDK
-  const initialize = async (companyCode: string | null, verboseLogging: boolean = false, insertLinksEnabled: boolean = false, insertLinksClipboardEnabled: boolean = false, affiliateAttributionActiveTime?: number): Promise<void> => {
-    setVerboseLogging(verboseLogging);
-    setInsertLinksEnabled(insertLinksEnabled);
-    setInsertLinksClipboardEnabled(insertLinksClipboardEnabled);
-    if (affiliateAttributionActiveTime !== undefined) {
-      setAffiliateAttributionActiveTime(affiliateAttributionActiveTime);
+  const initializeImpl = async (companyCodeParam: string | null, verboseLoggingParam: boolean = false, insertLinksEnabledParam: boolean = false, insertLinksClipboardEnabledParam: boolean = false, affiliateAttributionActiveTimeParam?: number): Promise<void> => {
+    // Prevent multiple concurrent initialization attempts
+    if (isInitialized || isInitializingRef.current) {
+      return;
     }
-    
-    if (verboseLogging) {
-      console.log('[Insert Affiliate] [VERBOSE] Starting SDK initialization...');
-      console.log('[Insert Affiliate] [VERBOSE] Company code provided:', companyCode ? 'Yes' : 'No');
-      console.log('[Insert Affiliate] [VERBOSE] Verbose logging enabled');
+    isInitializingRef.current = true;
+
+    setVerboseLogging(verboseLoggingParam);
+    verboseLoggingRef.current = verboseLoggingParam;
+    setInsertLinksEnabled(insertLinksEnabledParam);
+    setInsertLinksClipboardEnabled(insertLinksClipboardEnabledParam);
+    if (affiliateAttributionActiveTimeParam !== undefined) {
+      setAffiliateAttributionActiveTime(affiliateAttributionActiveTimeParam);
     }
 
-    if (isInitialized) {
-      console.error('[Insert Affiliate] SDK is already initialized.');
-      return;
+    if (verboseLoggingParam) {
+      console.log('[Insert Affiliate] [VERBOSE] Starting SDK initialization...');
+      console.log('[Insert Affiliate] [VERBOSE] Company code provided:', companyCodeParam ? 'Yes' : 'No');
+      console.log('[Insert Affiliate] [VERBOSE] Verbose logging enabled');
     }
 
-    if (companyCode && companyCode.trim() !== '') {
-      setCompanyCode(companyCode);
-      await saveValueInAsync(ASYNC_KEYS.COMPANY_CODE, companyCode);
+    if (companyCodeParam && companyCodeParam.trim() !== '') {
+      setCompanyCode(companyCodeParam);
+      companyCodeRef.current = companyCodeParam;
+      await saveValueInAsync(ASYNC_KEYS.COMPANY_CODE, companyCodeParam);
       setIsInitialized(true);
       console.log(
-        `[Insert Affiliate] SDK initialized with company code: ${companyCode}`
+        `[Insert Affiliate] SDK initialized with company code: ${companyCodeParam}`
       );
-      if (verboseLogging) {
+      if (verboseLoggingParam) {
         console.log('[Insert Affiliate] [VERBOSE] Company code saved to AsyncStorage');
         console.log('[Insert Affiliate] [VERBOSE] SDK marked as initialized');
       }
+
+      // Report SDK initialization for onboarding verification (fire and forget)
+      reportSdkInitIfNeeded(companyCodeParam, verboseLoggingParam);
     } else {
       console.warn(
         '[Insert Affiliate] SDK initialized without a company code.'
       );
       setIsInitialized(true);
-      if (verboseLogging) {
+      if (verboseLoggingParam) {
         console.log('[Insert Affiliate] [VERBOSE] No company code provided, SDK initialized in limited mode');
       }
     }
 
-    if (insertLinksEnabled && Platform.OS === 'ios') {
+    if (insertLinksEnabledParam && Platform.OS === 'ios') {
       try {
         const enhancedSystemInfo = await getEnhancedSystemInfo();
         await sendSystemInfoToBackend(enhancedSystemInfo);
@@ -197,6 +233,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
 
         if (companyCodeFromStorage) {
           setCompanyCode(companyCodeFromStorage);
+          companyCodeRef.current = companyCodeFromStorage;
           verboseLog('Company code restored from storage');
         }
 
@@ -337,13 +374,6 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     console.log('[Insert Affiliate] SDK has been reset.');
   };
 
-  // MARK: Callback Management
-  // Sets a callback that will be triggered whenever storeInsertAffiliateIdentifier is called
-  // The callback receives the current affiliate identifier (returnInsertAffiliateIdentifier result)
-  const setInsertAffiliateIdentifierChangeCallbackHandler = (callback: InsertAffiliateIdentifierChangeCallback | null): void => {
-    insertAffiliateIdentifierChangeCallbackRef.current = callback;
-  };
-
   // MARK: Deep Link Handling
   // Helper function to parse URLs in React Native compatible way
   const parseURL = (url: string) => {
@@ -389,14 +419,26 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
         return false;
       }
 
-      // Parse the URL to extract query parameters
-      const urlObj = new URL(url);
-      const insertAffiliate = urlObj.searchParams.get('insertAffiliate');
-      
+      // Parse the URL to extract query parameters (React Native compatible)
+      // URLSearchParams is not available in React Native, so parse manually
+      let insertAffiliate: string | null = null;
+      const queryIndex = url.indexOf('?');
+      if (queryIndex !== -1) {
+        const queryString = url.substring(queryIndex + 1);
+        const params = queryString.split('&');
+        for (const param of params) {
+          const [key, value] = param.split('=');
+          if (key === 'insertAffiliate' && value) {
+            insertAffiliate = decodeURIComponent(value);
+            break;
+          }
+        }
+      }
+
       if (insertAffiliate && insertAffiliate.length > 0) {
         verboseLog(`Found insertAffiliate parameter: ${insertAffiliate}`);
 
-        await storeInsertAffiliateIdentifier({ link: insertAffiliate });
+        await storeInsertAffiliateIdentifier({ link: insertAffiliate, source: 'deep_link_android' });
 
         return true;
       } else {
@@ -525,7 +567,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
       // If we have insertAffiliate parameter, use it as the affiliate identifier
       if (insertAffiliate && insertAffiliate.length > 0) {
         verboseLog(`Found insertAffiliate parameter, setting as affiliate identifier: ${insertAffiliate}`);
-        await storeInsertAffiliateIdentifier({ link: insertAffiliate });
+        await storeInsertAffiliateIdentifier({ link: insertAffiliate, source: 'install_referrer' });
 
         return true;
       } else {
@@ -540,10 +582,10 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
   };
 
   // Handles Insert Links deep linking - equivalent to iOS handleInsertLinks
-  const handleInsertLinks = async (url: string): Promise<boolean> => {
+  const handleInsertLinksImpl = async (url: string): Promise<boolean> => {
     try {
       console.log(`[Insert Affiliate] Attempting to handle URL: ${url}`);
-      
+
       if (!url || typeof url !== 'string') {
         console.log('[Insert Affiliate] Invalid URL provided to handleInsertLinks');
         return false;
@@ -602,7 +644,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
       }
 
       // If URL scheme is used, we can straight away store the short code as the referring link
-      await storeInsertAffiliateIdentifier({ link: shortCode });
+      await storeInsertAffiliateIdentifier({ link: shortCode, source: 'deep_link_ios' });
 
       // Collect and send enhanced system info to backend
       try {
@@ -664,14 +706,48 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     }
   };
 
+  // Parse shortcode from query parameter (new format: scheme://insert-affiliate?code=SHORTCODE)
+  const parseShortCodeFromQuery = (url: string): string | null => {
+    try {
+      const queryIndex = url.indexOf('?');
+      if (queryIndex !== -1) {
+        const queryString = url.substring(queryIndex + 1);
+        const params = queryString.split('&');
+        for (const param of params) {
+          const [key, value] = param.split('=');
+          if (key === 'code' && value) {
+            return decodeURIComponent(value);
+          }
+        }
+      }
+      return null;
+    } catch (error) {
+      verboseLog(`Error parsing short code from query: ${error}`);
+      return null;
+    }
+  };
+
   const parseShortCodeFromURLString = (url: string): string | null => {
     try {
-      // For custom schemes like ia-companycode://shortcode, everything after :// is the short code
+      // First try to extract from query parameter (new format: scheme://insert-affiliate?code=SHORTCODE)
+      const queryCode = parseShortCodeFromQuery(url);
+      if (queryCode) {
+        console.log(`[Insert Affiliate] Found short code in query parameter: ${queryCode}`);
+        return queryCode;
+      }
+
+      // Fall back to path format (legacy: scheme://SHORTCODE)
       const match = url.match(/^[^:]+:\/\/(.+)$/);
       if (match) {
-        const shortCode = match[1];
+        let shortCode = match[1];
         // Remove leading slash if present
-        return shortCode.startsWith('/') ? shortCode.substring(1) : shortCode;
+        shortCode = shortCode.startsWith('/') ? shortCode.substring(1) : shortCode;
+        // If the path is 'insert-affiliate' (from new format without code param), return null
+        if (shortCode === 'insert-affiliate' || shortCode.startsWith('insert-affiliate?')) {
+          return null;
+        }
+        console.log(`[Insert Affiliate] Found short code in URL path (legacy format): ${shortCode}`);
+        return shortCode;
       }
       return null;
     } catch (error) {
@@ -694,29 +770,30 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     await AsyncStorage.clear();
   };
 
-  // Helper function to get company code from state or storage
+  // Helper function to get company code from ref or storage (uses ref to avoid stale closures)
   const getActiveCompanyCode = async (): Promise<string | null> => {
     verboseLog('Getting active company code...');
-    let activeCompanyCode = companyCode;
-    verboseLog(`Company code in React state: ${activeCompanyCode || 'empty'}`);
-    
+    let activeCompanyCode = companyCodeRef.current;
+    verboseLog(`Company code in ref: ${activeCompanyCode || 'empty'}`);
+
     if (!activeCompanyCode || (activeCompanyCode.trim() === '' && activeCompanyCode !== null)) {
-      verboseLog('Company code not in state, checking AsyncStorage...');
+      verboseLog('Company code not in ref, checking AsyncStorage...');
       activeCompanyCode = await getValueFromAsync(ASYNC_KEYS.COMPANY_CODE);
       verboseLog(`Company code in AsyncStorage: ${activeCompanyCode || 'empty'}`);
-      
+
       if (activeCompanyCode) {
-        // Update state for future use
+        // Update ref and state for future use
+        companyCodeRef.current = activeCompanyCode;
         setCompanyCode(activeCompanyCode);
-        verboseLog('Updated React state with company code from storage');
+        verboseLog('Updated ref and React state with company code from storage');
       }
     }
     return activeCompanyCode;
   };
 
-  // Helper function for verbose logging
+  // Helper function for verbose logging (uses ref to avoid stale closures)
   const verboseLog = (message: string) => {
-    if (verboseLogging) {
+    if (verboseLoggingRef.current) {
       console.log(`[Insert Affiliate] [VERBOSE] ${message}`);
     }
   };
@@ -736,6 +813,96 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     }
   };
 
+  // Reports a new affiliate association to the backend for tracking.
+  // Only reports each unique affiliateIdentifier once to prevent duplicates.
+  const reportAffiliateAssociationIfNeeded = async (
+    affiliateIdentifier: string,
+    source: AffiliateAssociationSource
+  ): Promise<void> => {
+    try {
+      const activeCompanyCode = await getActiveCompanyCode();
+      if (!activeCompanyCode) {
+        verboseLog('Cannot report affiliate association: no company code available');
+        return;
+      }
+
+      // Get the set of already-reported affiliate identifiers
+      const reportedAssociationsJson = await AsyncStorage.getItem(ASYNC_KEYS.REPORTED_AFFILIATE_ASSOCIATIONS);
+      const reportedAssociations: string[] = reportedAssociationsJson ? JSON.parse(reportedAssociationsJson) : [];
+
+      // Check if this affiliate identifier has already been reported
+      if (reportedAssociations.includes(affiliateIdentifier)) {
+        verboseLog(`Affiliate association already reported for: ${affiliateIdentifier}, skipping`);
+        return;
+      }
+
+      verboseLog(`Reporting new affiliate association: ${affiliateIdentifier} (source: ${source})`);
+
+      const response = await fetch('https://api.insertaffiliate.com/V1/onboarding/affiliate-associated', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          companyId: activeCompanyCode,
+          affiliateIdentifier: affiliateIdentifier,
+          source: source,
+          timestamp: new Date().toISOString(),
+        }),
+      });
+
+      if (response.ok) {
+        // Add to reported set and persist
+        reportedAssociations.push(affiliateIdentifier);
+        await AsyncStorage.setItem(ASYNC_KEYS.REPORTED_AFFILIATE_ASSOCIATIONS, JSON.stringify(reportedAssociations));
+        verboseLog(`Affiliate association reported successfully for: ${affiliateIdentifier}`);
+      } else {
+        verboseLog(`Affiliate association report failed with status: ${response.status}`);
+      }
+    } catch (error) {
+      // Silently fail - this is non-critical telemetry
+      verboseLog(`Affiliate association report error: ${error}`);
+    }
+  };
+
+  // Reports SDK initialization to the backend for onboarding verification.
+  // Only reports once per install to minimize server load.
+  const reportSdkInitIfNeeded = async (companyCode: string, verboseLogging: boolean): Promise<void> => {
+    try {
+      // Only report once per install
+      const alreadyReported = await AsyncStorage.getItem(ASYNC_KEYS.SDK_INIT_REPORTED);
+      if (alreadyReported === 'true') {
+        return;
+      }
+
+      if (verboseLogging) {
+        console.log('[Insert Affiliate] Reporting SDK initialization for onboarding verification...');
+      }
+
+      const response = await fetch('https://api.insertaffiliate.com/V1/onboarding/sdk-init', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ companyId: companyCode }),
+      });
+
+      if (response.ok) {
+        await AsyncStorage.setItem(ASYNC_KEYS.SDK_INIT_REPORTED, 'true');
+        if (verboseLogging) {
+          console.log('[Insert Affiliate] SDK initialization reported successfully');
+        }
+      } else if (verboseLogging) {
+        console.log(`[Insert Affiliate] SDK initialization report failed with status: ${response.status}`);
+      }
+    } catch (error) {
+      // Silently fail - this is non-critical telemetry
+      if (verboseLogging) {
+        console.log(`[Insert Affiliate] SDK initialization report error: ${error}`);
+      }
+    }
+  };
+
   // MARK: - Deep Linking Utilities
   
   // Retrieves and validates clipboard content for UUID format
@@ -1154,9 +1321,9 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
         const matchFound = response.data.matchFound || false;
         if (matchFound && response.data.matched_affiliate_shortCode && response.data.matched_affiliate_shortCode.length > 0) {
           const matchedShortCode = response.data.matched_affiliate_shortCode;
-          verboseLog(`Storing Matched short code from backend: ${matchedShortCode}`); 
-          
-          await storeInsertAffiliateIdentifier({ link: matchedShortCode });
+          verboseLog(`Storing Matched short code from backend: ${matchedShortCode}`);
+
+          await storeInsertAffiliateIdentifier({ link: matchedShortCode, source: 'clipboard_match' });
         }
       }
       
@@ -1224,7 +1391,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     }
   };
 
-  const getAffiliateDetails = async (affiliateCode: string): Promise<AffiliateDetails> => {
+  const getAffiliateDetailsImpl = async (affiliateCode: string): Promise<AffiliateDetails> => {
     try {
       const activeCompanyCode = await getActiveCompanyCode();
       if (!activeCompanyCode) {
@@ -1269,7 +1436,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     }
   };
 
-  async function setShortCode(shortCode: string): Promise<boolean> {
+  const setShortCodeImpl = async (shortCode: string): Promise<boolean> => {
     console.log('[Insert Affiliate] Setting short code.');
     await generateThenSetUserID();
 
@@ -1282,14 +1449,14 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
 
     if (exists) {
       // If affiliate exists, set the Insert Affiliate Identifier
-      await storeInsertAffiliateIdentifier({ link: capitalisedShortCode });
+      await storeInsertAffiliateIdentifier({ link: capitalisedShortCode, source: 'short_code_manual' });
       console.log(`[Insert Affiliate] Short code ${capitalisedShortCode} validated and stored successfully.`);
       return true;
     } else {
       console.warn(`[Insert Affiliate] Short code ${capitalisedShortCode} does not exist. Not storing.`);
       return false;
     }
-  }
+  };
 
   async function getOrCreateUserAccountToken(): Promise<string> {
     let userAccountToken = await getValueFromAsync(ASYNC_KEYS.USER_ACCOUNT_TOKEN);
@@ -1302,9 +1469,9 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     return userAccountToken;
   };
 
-  const returnUserAccountTokenAndStoreExpectedTransaction = async (): Promise<string | null> => {
+  const returnUserAccountTokenAndStoreExpectedTransactionImpl = async (): Promise<string | null> => {
     try {
-      const shortCode = await returnInsertAffiliateIdentifier();
+      const shortCode = await returnInsertAffiliateIdentifierImpl();
       if (!shortCode) {
         console.log('[Insert Affiliate] No affiliate stored - not saving expected transaction.');
         return null;
@@ -1317,14 +1484,14 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
         console.error('[Insert Affiliate] Failed to generate user account token.');
         return null;
       } else {
-        await storeExpectedStoreTransaction(userAccountToken);
+        await storeExpectedStoreTransactionImpl(userAccountToken);
         return userAccountToken;
       }
     } catch (error) {
       // Handle E_IAP_NOT_AVAILABLE error gracefully
-      if ((error as any)?.code === 'E_IAP_NOT_AVAILABLE' || 
+      if ((error as any)?.code === 'E_IAP_NOT_AVAILABLE' ||
           (error instanceof Error && error.message.includes('E_IAP_NOT_AVAILABLE'))) {
-        
+
         if (isDevelopmentEnvironment) {
           console.warn('[Insert Affiliate] IAP not available in development environment. Cannot store expected transaction.');
           verboseLog('E_IAP_NOT_AVAILABLE error in returnUserAccountTokenAndStoreExpectedTransaction - gracefully handling in development');
@@ -1338,50 +1505,50 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
   };
 
   // MARK: Return Insert Affiliate Identifier
-  const returnInsertAffiliateIdentifier = async (ignoreTimeout: boolean = false): Promise<string | null> => {
+  const returnInsertAffiliateIdentifierImpl = async (ignoreTimeout: boolean = false): Promise<string | null> => {
     try {
       verboseLog(`Getting insert affiliate identifier (ignoreTimeout: ${ignoreTimeout})...`);
-      
+
       // If timeout is enabled and we're not ignoring it, check validity first
       if (!ignoreTimeout && affiliateAttributionActiveTime) {
-        const isValid = await isAffiliateAttributionValid();
+        const isValid = await isAffiliateAttributionValidImpl();
         if (!isValid) {
           verboseLog('Attribution has expired, returning null');
           return null;
         }
       }
-      
+
       // Now get the actual identifier
       verboseLog(`React state - referrerLink: ${referrerLink || 'empty'}, userId: ${userId || 'empty'}`);
-      
+
       // Try React state first
       if (referrerLink && userId) {
         const identifier = `${referrerLink}-${userId}`;
         verboseLog(`Found identifier in React state: ${identifier}`);
         return identifier;
       }
-      
+
       verboseLog('React state empty, checking AsyncStorage...');
-      
+
       // Fallback to async storage if React state is empty
       const storedLink = await getValueFromAsync(ASYNC_KEYS.REFERRER_LINK);
       let storedUserId = await getValueFromAsync(ASYNC_KEYS.USER_ID);
-      
+
       verboseLog(`AsyncStorage - storedLink: ${storedLink || 'empty'}, storedUserId: ${storedUserId || 'empty'}`);
-      
+
       // If we have a stored link but no user ID, generate one now
       if (storedLink && !storedUserId) {
         verboseLog('Found stored link but no user ID, generating user ID now...');
         storedUserId = await generateThenSetUserID();
         verboseLog(`Generated user ID: ${storedUserId}`);
       }
-      
+
       if (storedLink && storedUserId) {
         const identifier = `${storedLink}-${storedUserId}`;
         verboseLog(`Found identifier in AsyncStorage: ${identifier}`);
         return identifier;
       }
-      
+
       verboseLog('No affiliate identifier found in state or storage');
       return null;
     } catch (error) {
@@ -1391,44 +1558,44 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
   };
 
   // MARK: Attribution Timeout Functions
-  
+
   // Check if the current affiliate attribution is still valid based on timeout
-  const isAffiliateAttributionValid = async (): Promise<boolean> => {
+  const isAffiliateAttributionValidImpl = async (): Promise<boolean> => {
     try {
       // If no timeout is set, attribution is always valid
       if (!affiliateAttributionActiveTime) {
         verboseLog('No attribution timeout set, attribution is valid');
         return true;
       }
-      
-      const storedDate = await getAffiliateStoredDate();
+
+      const storedDate = await getAffiliateStoredDateImpl();
       if (!storedDate) {
         verboseLog('No stored date found, attribution is invalid');
         return false;
       }
-      
+
       const now = new Date();
       const timeDifferenceSeconds = Math.floor((now.getTime() - storedDate.getTime()) / 1000);
       const isValid = timeDifferenceSeconds <= affiliateAttributionActiveTime;
-      
+
       verboseLog(`Attribution timeout check: stored=${storedDate.toISOString()}, now=${now.toISOString()}, diff=${timeDifferenceSeconds}s, timeout=${affiliateAttributionActiveTime}s, valid=${isValid}`);
-      
+
       return isValid;
     } catch (error) {
       verboseLog(`Error checking attribution validity: ${error}`);
       return false;
     }
   };
-  
+
   // Get the date when the affiliate identifier was stored
-  const getAffiliateStoredDate = async (): Promise<Date | null> => {
+  const getAffiliateStoredDateImpl = async (): Promise<Date | null> => {
     try {
       const storedDateString = await getValueFromAsync(ASYNC_KEYS.AFFILIATE_STORED_DATE);
       if (!storedDateString) {
         verboseLog('No affiliate stored date found');
         return null;
       }
-      
+
       const storedDate = new Date(storedDateString);
       verboseLog(`Retrieved affiliate stored date: ${storedDate.toISOString()}`);
       return storedDate;
@@ -1440,9 +1607,9 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
 
   // MARK: Insert Affiliate Identifier
 
-  async function setInsertAffiliateIdentifier(
+  const setInsertAffiliateIdentifierImpl = async (
     referringLink: string
-  ): Promise<void | string> {
+  ): Promise<void | string> => {
     console.log('[Insert Affiliate] Setting affiliate identifier.');
     verboseLog(`Input referringLink: ${referringLink}`);
 
@@ -1457,7 +1624,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
       if (!referringLink) {
         console.warn('[Insert Affiliate] Referring link is invalid.');
         verboseLog('Referring link is empty or invalid, storing as-is');
-        await storeInsertAffiliateIdentifier({ link: referringLink });
+        await storeInsertAffiliateIdentifier({ link: referringLink, source: 'referring_link' });
         return `${referringLink}-${customerID}`;
       }
 
@@ -1481,7 +1648,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
           '[Insert Affiliate] Referring link is already a short code.'
         );
         verboseLog('Link is already a short code, storing directly');
-        await storeInsertAffiliateIdentifier({ link: referringLink });
+        await storeInsertAffiliateIdentifier({ link: referringLink, source: 'referring_link' });
         return `${referringLink}-${customerID}`;
       }
 
@@ -1494,7 +1661,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
       if (!encodedAffiliateLink) {
         console.error('[Insert Affiliate] Failed to encode affiliate link.');
         verboseLog('Failed to encode link, storing original');
-        await storeInsertAffiliateIdentifier({ link: referringLink });
+        await storeInsertAffiliateIdentifier({ link: referringLink, source: 'referring_link' });
         return `${referringLink}-${customerID}`;
       }
 
@@ -1517,14 +1684,14 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
         console.log('[Insert Affiliate] Short link received:', shortLink);
         verboseLog(`Successfully converted to short link: ${shortLink}`);
         verboseLog('Storing short link to AsyncStorage...');
-        await storeInsertAffiliateIdentifier({ link: shortLink });
+        await storeInsertAffiliateIdentifier({ link: shortLink, source: 'referring_link' });
         verboseLog('Short link stored successfully');
         return `${shortLink}-${customerID}`;
       } else {
         console.warn('[Insert Affiliate] Unexpected response format.');
         verboseLog(`Unexpected API response. Status: ${response.status}, Data: ${JSON.stringify(response.data)}`);
         verboseLog('Storing original link as fallback');
-        await storeInsertAffiliateIdentifier({ link: referringLink });
+        await storeInsertAffiliateIdentifier({ link: referringLink, source: 'referring_link' });
         return `${referringLink}-${customerID}`;
       }
     } catch (error) {
@@ -1532,42 +1699,48 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
       verboseLog(`Error in setInsertAffiliateIdentifier: ${error}`);
     }
   };
-  
-  async function storeInsertAffiliateIdentifier({ link }: { link: string }) {
-    console.log(`[Insert Affiliate] Storing affiliate identifier: ${link}`);
-    
+
+  async function storeInsertAffiliateIdentifier({ link, source }: { link: string; source: AffiliateAssociationSource }) {
+    console.log(`[Insert Affiliate] Storing affiliate identifier: ${link} (source: ${source})`);
+
     // Check if we're trying to store the same link (prevent duplicate storage)
     const existingLink = await getValueFromAsync(ASYNC_KEYS.REFERRER_LINK);
     if (existingLink === link) {
       verboseLog(`Link ${link} is already stored, skipping duplicate storage`);
       return;
     }
-    
+
     verboseLog(`Updating React state with referrer link: ${link}`);
     setReferrerLink(link);
     verboseLog(`Saving referrer link to AsyncStorage...`);
     await saveValueInAsync(ASYNC_KEYS.REFERRER_LINK, link);
-    
+
     // Store the current date/time when the affiliate identifier is stored
     const currentDate = new Date().toISOString();
     verboseLog(`Saving affiliate stored date: ${currentDate}`);
     await saveValueInAsync(ASYNC_KEYS.AFFILIATE_STORED_DATE, currentDate);
-    
+
     verboseLog(`Referrer link saved to AsyncStorage successfully`);
-    
+
     // Automatically fetch and store offer code for any affiliate identifier
     verboseLog('Attempting to fetch offer code for stored affiliate identifier...');
     await retrieveAndStoreOfferCode(link);
-    
+
     // Trigger callback with the current affiliate identifier
     if (insertAffiliateIdentifierChangeCallbackRef.current) {
-      const currentIdentifier = await returnInsertAffiliateIdentifier();
+      const currentIdentifier = await returnInsertAffiliateIdentifierImpl();
       verboseLog(`Triggering callback with identifier: ${currentIdentifier}`);
       insertAffiliateIdentifierChangeCallbackRef.current(currentIdentifier);
     }
+
+    // Report this new affiliate association to the backend (fire and forget)
+    const fullIdentifier = await returnInsertAffiliateIdentifierImpl();
+    if (fullIdentifier) {
+      reportAffiliateAssociationIfNeeded(fullIdentifier, source);
+    }
   }
 
-  const validatePurchaseWithIapticAPI = async (
+  const validatePurchaseWithIapticAPIImpl = async (
     jsonIapPurchase: CustomPurchase,
     iapticAppId: string,
     iapticAppName: string,
@@ -1575,10 +1748,10 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
   ): Promise<boolean> => {
     try {
       // Check for E_IAP_NOT_AVAILABLE error in development environment
-      if ((jsonIapPurchase as any)?.error?.code === 'E_IAP_NOT_AVAILABLE' || 
+      if ((jsonIapPurchase as any)?.error?.code === 'E_IAP_NOT_AVAILABLE' ||
           (jsonIapPurchase as any)?.code === 'E_IAP_NOT_AVAILABLE' ||
           (typeof jsonIapPurchase === 'string' && (jsonIapPurchase as string).includes('E_IAP_NOT_AVAILABLE'))) {
-        
+
         if (isDevelopmentEnvironment) {
           console.warn('[Insert Affiliate] IAP not available in development environment. This is expected behavior.');
           verboseLog('E_IAP_NOT_AVAILABLE error detected in development - gracefully handling');
@@ -1619,7 +1792,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
         transaction,
       };
 
-      let insertAffiliateIdentifier = await returnInsertAffiliateIdentifier();
+      let insertAffiliateIdentifier = await returnInsertAffiliateIdentifierImpl();
 
       if (insertAffiliateIdentifier) {
         requestBody.additionalData = {
@@ -1647,9 +1820,9 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
       }
     } catch (error) {
       // Handle E_IAP_NOT_AVAILABLE error gracefully
-      if ((error as any)?.code === 'E_IAP_NOT_AVAILABLE' || 
+      if ((error as any)?.code === 'E_IAP_NOT_AVAILABLE' ||
           (error instanceof Error && error.message.includes('E_IAP_NOT_AVAILABLE'))) {
-        
+
         if (isDevelopmentEnvironment) {
           console.warn('[Insert Affiliate] IAP not available in development environment. SDK will continue without purchase validation.');
           verboseLog('E_IAP_NOT_AVAILABLE error caught in validatePurchaseWithIapticAPI - gracefully handling in development');
@@ -1673,9 +1846,9 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     }
   };
 
-  const storeExpectedStoreTransaction = async (purchaseToken: string): Promise<void> => {
+  const storeExpectedStoreTransactionImpl = async (purchaseToken: string): Promise<void> => {
     verboseLog(`Storing expected store transaction with token: ${purchaseToken}`);
-    
+
     const activeCompanyCode = await getActiveCompanyCode();
     if (!activeCompanyCode) {
       console.error("[Insert Affiliate] Company code is not set. Please initialize the SDK with a valid company code.");
@@ -1683,7 +1856,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
       return;
     }
 
-    const shortCode = await returnInsertAffiliateIdentifier();
+    const shortCode = await returnInsertAffiliateIdentifierImpl();
     if (!shortCode) {
       console.error("[Insert Affiliate] No affiliate identifier found. Please set one before tracking events.");
       verboseLog("Cannot store transaction: no affiliate identifier available");
@@ -1729,10 +1902,10 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
   };
 
   // MARK: Track Event
-  const trackEvent = async (eventName: string): Promise<void> => {
+  const trackEventImpl = async (eventName: string): Promise<void> => {
     try {
       verboseLog(`Tracking event: ${eventName}`);
-      
+
       const activeCompanyCode = await getActiveCompanyCode();
       if (!activeCompanyCode) {
         console.error("[Insert Affiliate] Company code is not set. Please initialize the SDK with a valid company code.");
@@ -1762,7 +1935,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
       verboseLog(`Track event payload: ${JSON.stringify(payload)}`);
 
       verboseLog("Making API call to track event...");
-      
+
       const response = await axios.post(
         'https://api.insertaffiliate.com/v1/trackEvent',
         payload,
@@ -1877,6 +2050,89 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     return removeSpecialCharacters(offerCode);
   };
 
+  // ============================================================================
+  // REF CALLBACK PATTERN: Update refs on every render for fresh closures
+  // ============================================================================
+  initializeImplRef.current = initializeImpl;
+  setShortCodeImplRef.current = setShortCodeImpl;
+  getAffiliateDetailsImplRef.current = getAffiliateDetailsImpl;
+  returnInsertAffiliateIdentifierImplRef.current = returnInsertAffiliateIdentifierImpl;
+  isAffiliateAttributionValidImplRef.current = isAffiliateAttributionValidImpl;
+  getAffiliateStoredDateImplRef.current = getAffiliateStoredDateImpl;
+  storeExpectedStoreTransactionImplRef.current = storeExpectedStoreTransactionImpl;
+  returnUserAccountTokenAndStoreExpectedTransactionImplRef.current = returnUserAccountTokenAndStoreExpectedTransactionImpl;
+  validatePurchaseWithIapticAPIImplRef.current = validatePurchaseWithIapticAPIImpl;
+  trackEventImplRef.current = trackEventImpl;
+  setInsertAffiliateIdentifierImplRef.current = setInsertAffiliateIdentifierImpl;
+  handleInsertLinksImplRef.current = handleInsertLinksImpl;
+
+  // ============================================================================
+  // STABLE WRAPPERS: useCallback with [] deps that delegate to refs
+  // These provide stable function references that always call current implementations
+  // ============================================================================
+  const initialize = useCallback(async (
+    code: string | null,
+    verboseLogging?: boolean,
+    insertLinksEnabled?: boolean,
+    insertLinksClipboardEnabled?: boolean,
+    affiliateAttributionActiveTime?: number
+  ): Promise<void> => {
+    return initializeImplRef.current(code, verboseLogging, insertLinksEnabled, insertLinksClipboardEnabled, affiliateAttributionActiveTime);
+  }, []);
+
+  const setShortCode = useCallback(async (shortCode: string): Promise<boolean> => {
+    return setShortCodeImplRef.current(shortCode);
+  }, []);
+
+  const getAffiliateDetails = useCallback(async (affiliateCode: string): Promise<AffiliateDetails> => {
+    return getAffiliateDetailsImplRef.current(affiliateCode);
+  }, []);
+
+  const returnInsertAffiliateIdentifier = useCallback(async (ignoreTimeout?: boolean): Promise<string | null> => {
+    return returnInsertAffiliateIdentifierImplRef.current(ignoreTimeout);
+  }, []);
+
+  const isAffiliateAttributionValid = useCallback(async (): Promise<boolean> => {
+    return isAffiliateAttributionValidImplRef.current();
+  }, []);
+
+  const getAffiliateStoredDate = useCallback(async (): Promise<Date | null> => {
+    return getAffiliateStoredDateImplRef.current();
+  }, []);
+
+  const storeExpectedStoreTransaction = useCallback(async (purchaseToken: string): Promise<void> => {
+    return storeExpectedStoreTransactionImplRef.current(purchaseToken);
+  }, []);
+
+  const returnUserAccountTokenAndStoreExpectedTransaction = useCallback(async (): Promise<string | null> => {
+    return returnUserAccountTokenAndStoreExpectedTransactionImplRef.current();
+  }, []);
+
+  const validatePurchaseWithIapticAPI = useCallback(async (
+    jsonIapPurchase: CustomPurchase,
+    iapticAppId: string,
+    iapticAppName: string,
+    iapticPublicKey: string
+  ): Promise<boolean> => {
+    return validatePurchaseWithIapticAPIImplRef.current(jsonIapPurchase, iapticAppId, iapticAppName, iapticPublicKey);
+  }, []);
+
+  const trackEvent = useCallback(async (eventName: string): Promise<void> => {
+    return trackEventImplRef.current(eventName);
+  }, []);
+
+  const setInsertAffiliateIdentifier = useCallback(async (referringLink: string): Promise<void | string> => {
+    return setInsertAffiliateIdentifierImplRef.current(referringLink);
+  }, []);
+
+  const setInsertAffiliateIdentifierChangeCallbackHandler = useCallback((callback: InsertAffiliateIdentifierChangeCallback | null): void => {
+    insertAffiliateIdentifierChangeCallbackRef.current = callback;
+  }, []);
+
+  const handleInsertLinks = useCallback(async (url: string): Promise<boolean> => {
+    return handleInsertLinksImplRef.current(url);
+  }, []);
+
   return (
     <DeepLinkIapContext.Provider
       value={{