insert-affiliate-react-native-sdk 1.8.0 → 1.10.0

package/src/DeepLinkIapProvider.tsx

@@ -17,6 +17,12 @@ type T_DEEPLINK_IAP_PROVIDER = {
 
 export type InsertAffiliateIdentifierChangeCallback = (identifier: string | null) => void;
 
+export type AffiliateDetails = {
+  affiliateName: string;
+  affiliateShortCode: string;
+  deeplinkurl: string;
+} | null;
+
 type CustomPurchase = {
   [key: string]: any; // Accept any fields to allow it to work wtih multiple IAP libraries
 };
@@ -39,7 +45,8 @@ type T_DEEPLINK_IAP_CONTEXT = {
     purchaseToken: string
   ) => Promise<void>;
   trackEvent: (eventName: string) => Promise<void>;
-  setShortCode: (shortCode: string) => Promise<void>;
+  setShortCode: (shortCode: string) => Promise<boolean>;
+  getAffiliateDetails: (affiliateCode: string) => Promise<AffiliateDetails>;
   setInsertAffiliateIdentifier: (
     referringLink: string
   ) => Promise<void | string>;
@@ -73,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: '',
@@ -92,7 +110,8 @@ export const DeepLinkIapContext = createContext<T_DEEPLINK_IAP_CONTEXT>({
   returnUserAccountTokenAndStoreExpectedTransaction: async () => '',
   storeExpectedStoreTransaction: async (purchaseToken: string) => {},
   trackEvent: async (eventName: string) => {},
-  setShortCode: async (shortCode: string) => {},
+  setShortCode: async (shortCode: string) => false,
+  getAffiliateDetails: async (affiliateCode: string) => null,
   setInsertAffiliateIdentifier: async (referringLink: string) => {},
   setInsertAffiliateIdentifierChangeCallback: (callback: InsertAffiliateIdentifierChangeCallback | null) => {},
   handleInsertLinks: async (url: string) => false,
@@ -145,6 +164,9 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
         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(companyCode, verboseLogging);
     } else {
       console.warn(
         '[Insert Affiliate] SDK initialized without a company code.'
@@ -381,14 +403,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 {
@@ -517,7 +551,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 {
@@ -594,7 +628,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 {
@@ -728,6 +762,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
@@ -1146,9 +1270,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' });
         }
       }
       
@@ -1174,7 +1298,94 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     return isValidCharacters && referringLink.length >= 3 && referringLink.length <= 25;
   };
 
-  async function setShortCode(shortCode: string): Promise<void> {
+  const checkAffiliateExists = async (affiliateCode: string): Promise<boolean> => {
+    try {
+      const activeCompanyCode = await getActiveCompanyCode();
+      if (!activeCompanyCode) {
+        verboseLog('Cannot check affiliate: no company code available');
+        return false;
+      }
+
+      const url = 'https://api.insertaffiliate.com/V1/checkAffiliateExists';
+      const payload = {
+        companyId: activeCompanyCode,
+        affiliateCode: affiliateCode
+      };
+
+      verboseLog(`Checking if affiliate exists: ${affiliateCode}`);
+
+      const response = await axios.post(url, payload, {
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+
+      verboseLog(`Affiliate check response: ${JSON.stringify(response.data)}`);
+
+      if (response.status === 200 && response.data) {
+        const exists = response.data.exists === true;
+        if (exists) {
+          verboseLog(`Affiliate ${affiliateCode} exists and is valid`);
+        } else {
+          verboseLog(`Affiliate ${affiliateCode} does not exist`);
+        }
+        return exists;
+      } else {
+        verboseLog(`Unexpected response checking affiliate: status ${response.status}`);
+        return false;
+      }
+    } catch (error) {
+      verboseLog(`Error checking affiliate exists: ${error}`);
+      return false;
+    }
+  };
+
+  const getAffiliateDetails = async (affiliateCode: string): Promise<AffiliateDetails> => {
+    try {
+      const activeCompanyCode = await getActiveCompanyCode();
+      if (!activeCompanyCode) {
+        verboseLog('Cannot get affiliate details: no company code available');
+        return null;
+      }
+
+      const url = 'https://api.insertaffiliate.com/V1/checkAffiliateExists';
+      const payload = {
+        companyId: activeCompanyCode,
+        affiliateCode: affiliateCode
+      };
+
+      verboseLog(`Getting affiliate details for: ${affiliateCode}`);
+
+      const response = await axios.post(url, payload, {
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+
+      verboseLog(`Affiliate details response: ${JSON.stringify(response.data)}`);
+
+      if (response.status === 200 && response.data && response.data.exists === true) {
+        const affiliate = response.data.affiliate;
+        if (affiliate) {
+          verboseLog(`Retrieved affiliate details: ${JSON.stringify(affiliate)}`);
+          return {
+            affiliateName: affiliate.affiliateName || '',
+            affiliateShortCode: affiliate.affiliateShortCode || '',
+            deeplinkurl: affiliate.deeplinkurl || ''
+          };
+        }
+      }
+
+      verboseLog(`Affiliate ${affiliateCode} not found or invalid response`);
+      return null;
+    } catch (error) {
+      verboseLog(`Error getting affiliate details: ${error}`);
+      console.error('[Insert Affiliate] Error getting affiliate details:', error);
+      return null;
+    }
+  };
+
+  async function setShortCode(shortCode: string): Promise<boolean> {
     console.log('[Insert Affiliate] Setting short code.');
     await generateThenSetUserID();
 
@@ -1182,8 +1393,18 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     const capitalisedShortCode = shortCode.toUpperCase();
     isShortCode(capitalisedShortCode);
 
-    // If all checks pass, set the Insert Affiliate Identifier
-    await storeInsertAffiliateIdentifier({ link: capitalisedShortCode });
+    // Check if the affiliate exists before storing
+    const exists = await checkAffiliateExists(capitalisedShortCode);
+
+    if (exists) {
+      // If affiliate exists, set the Insert Affiliate Identifier
+      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> {
@@ -1352,7 +1573,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}`;
       }
 
@@ -1376,7 +1597,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}`;
       }
 
@@ -1389,7 +1610,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}`;
       }
 
@@ -1412,14 +1633,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) {
@@ -1428,38 +1649,44 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
     }
   };
   
-  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();
       verboseLog(`Triggering callback with identifier: ${currentIdentifier}`);
       insertAffiliateIdentifierChangeCallbackRef.current(currentIdentifier);
     }
+
+    // Report this new affiliate association to the backend (fire and forget)
+    const fullIdentifier = await returnInsertAffiliateIdentifier();
+    if (fullIdentifier) {
+      reportAffiliateAssociationIfNeeded(fullIdentifier, source);
+    }
   }
 
   const validatePurchaseWithIapticAPI = async (
@@ -1779,6 +2006,7 @@ const DeepLinkIapProvider: React.FC<T_DEEPLINK_IAP_PROVIDER> = ({
         userId,
         OfferCode,
         setShortCode,
+        getAffiliateDetails,
         returnInsertAffiliateIdentifier,
         isAffiliateAttributionValid,
         getAffiliateStoredDate,

package/src/index.ts

@@ -4,4 +4,4 @@ import useDeepLinkIapProvider from "./useDeepLinkIapProvider";
 export { DeepLinkIapProvider, useDeepLinkIapProvider };
 
 // Export types
-export type { InsertAffiliateIdentifierChangeCallback } from "./DeepLinkIapProvider";
+export type { InsertAffiliateIdentifierChangeCallback, AffiliateDetails } from "./DeepLinkIapProvider";

package/src/useDeepLinkIapProvider.tsx

@@ -13,6 +13,7 @@ const useDeepLinkIapProvider = () => {
     getAffiliateStoredDate,
     trackEvent,
     setShortCode,
+    getAffiliateDetails,
     setInsertAffiliateIdentifier,
     setInsertAffiliateIdentifierChangeCallback,
     handleInsertLinks,
@@ -32,6 +33,7 @@ const useDeepLinkIapProvider = () => {
     getAffiliateStoredDate,
     trackEvent,
     setShortCode,
+    getAffiliateDetails,
     setInsertAffiliateIdentifier,
     setInsertAffiliateIdentifierChangeCallback,
     handleInsertLinks,