InsertAffiliateReactNative SDK

The official React Native SDK for Insert Affiliate - track affiliate-driven in-app purchases and reward your partners automatically.

What does this SDK do? It connects your React Native app to Insert Affiliate's platform, enabling you to track which affiliates drive subscriptions and automatically pay them commissions when users make in-app purchases.

Table of Contents

• Quick Start (5 Minutes)
• Essential Setup
  • 1. Initialize the SDK
  • 2. Configure In-App Purchase Verification
  • 3. Set Up Deep Linking
• Verify Your Integration
• Advanced Features
• Troubleshooting
• Support

🚀 Quick Start (5 Minutes)

Get up and running with minimal code to validate the SDK works before tackling IAP and deep linking setup.

Prerequisites

• React Native 0.60+
• iOS 13.0+ / Android API 21+
• Company Code from your Insert Affiliate dashboard

Installation

Step 1: Install the SDK package

npm install insert-affiliate-react-native-sdk

Step 2: Install required peer dependencies

npm install @react-native-async-storage/async-storage @react-native-clipboard/clipboard @react-native-community/netinfo react-native-device-info axios

Step 3: Install iOS pods (iOS only)

For bare React Native projects:

cd ios && pod install && cd ..

For Expo managed workflow: Skip this step - pods are installed automatically when you run npx expo prebuild or npx expo run:ios.

Your First Integration

In index.js - Wrap your app with the provider:

import React from 'react';
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';
import { DeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

const RootComponent = () => {
  return (
    <DeepLinkIapProvider>
      <App />
    </DeepLinkIapProvider>
  );
};

AppRegistry.registerComponent(appName, () => RootComponent);

In App.tsx - Initialize the SDK:

import React, { useEffect } from 'react';
import { View, Text } from 'react-native';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

const App = () => {
  const { initialize, isInitialized } = useDeepLinkIapProvider();

  useEffect(() => {
    if (!isInitialized) {
      initialize(
        "YOUR_COMPANY_CODE",  // Get from https://app.insertaffiliate.com/settings
        true                   // Enable verbose logging for setup
      );
    }
  }, [initialize, isInitialized]);

  return (
    <View>
      <Text>My App</Text>
    </View>
  );
};

export default App;

Expected Console Output:

When the SDK initializes successfully, you'll see:

[Insert Affiliate] SDK initialized with company code: YOUR_COMPANY_CODE
[Insert Affiliate] [VERBOSE] SDK marked as initialized

If you see these logs, the SDK is working! Now proceed to Essential Setup below.

Important: Disable verbose logging in production by setting the second parameter to false.

⚙️ Essential Setup

Complete these three required steps to start tracking affiliate-driven purchases.

1. Initialize the SDK

You've already done basic initialization above. Here are additional options:

Basic Initialization (Recommended for Getting Started)

initialize("YOUR_COMPANY_CODE", true);  // verbose logging enabled

initialize(
  "YOUR_COMPANY_CODE",
  true,    // verboseLogging - Enable for debugging (disable in production)
  true,    // insertLinksEnabled - Enable Insert Links (Insert Affiliate's built-in deep linking)
  true,    // insertLinksClipboardEnabled - Enable clipboard attribution (triggers permission prompt)
  604800,  // affiliateAttributionActiveTime - 7 days attribution timeout in seconds
  true     // preventAffiliateTransfer - Protect original affiliate from being replaced
);

Parameters:

• verboseLogging: Shows detailed logs for debugging (disable in production)
• insertLinksEnabled: Set to true if using Insert Links, false if using Branch/AppsFlyer
• insertLinksClipboardEnabled: Enables clipboard-based attribution for Insert Links
  • Improves attribution accuracy when deep linking fails
  • iOS will show a permission prompt: "[Your App] would like to paste from [App Name]"
• affiliateAttributionActiveTime: How long affiliate attribution lasts in seconds (omit for no timeout)
• preventAffiliateTransfer: When true, prevents a new affiliate link from overwriting an existing affiliate attribution (defaults to false)
  • Use this to ensure the first affiliate who acquired the user always gets credit
  • New affiliate links will be silently ignored if the user already has an affiliate

2. Configure In-App Purchase Verification

Insert Affiliate requires a receipt verification method to validate purchases. Choose ONE of the following:

| Method | Best For | Setup Time | Complexity | |--------|----------|------------|------------| | RevenueCat | Most developers, managed infrastructure | ~10 min | Simple | | Adapty | Paywall A/B testing, analytics | ~10 min | Simple | | Iaptic | Custom requirements, direct control | ~15 min | Medium | | App Store Direct | No 3rd party fees (iOS) | ~20 min | Medium | | Google Play Direct | No 3rd party fees (Android) | ~20 min | Medium |

Step 1: Code Setup

Complete the RevenueCat SDK installation first, then add to your App.tsx:

import React, { useEffect } from 'react';
import { AppState } from 'react-native';
import Purchases from 'react-native-purchases';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

const App = () => {
  const {
    initialize,
    isInitialized,
    setInsertAffiliateIdentifierChangeCallback,
    isAffiliateAttributionValid,
    getAffiliateExpiryTimestamp
  } = useDeepLinkIapProvider();

  useEffect(() => {
    if (!isInitialized) {
      initialize("YOUR_COMPANY_CODE");
    }
  }, [initialize, isInitialized]);

  // Set RevenueCat attributes when affiliate identifier changes
  // Note: Use preventAffiliateTransfer in initialize() to block affiliate changes in the SDK
  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier, offerCode) => {
      if (identifier) {
        // OPTIONAL: Prevent attribution for existing subscribers
        // Uncomment to ensure affiliates only earn from users they actually brought:
        // const customerInfo = await Purchases.getCustomerInfo();
        // const hasActiveEntitlement = Object.keys(customerInfo.entitlements.active).length > 0;
        // if (hasActiveEntitlement) return; // User already subscribed, don't attribute

        // Sync affiliate to RevenueCat
        await Purchases.setAttributes({
          "insert_affiliate": identifier,
          "affiliateOfferCode": offerCode || "",  // For RevenueCat Targeting
          "insert_timedout": ""  // Clear timeout flag on new attribution
        });
        await Purchases.syncAttributesAndOfferingsIfNeeded();
      }
    });

    return () => setInsertAffiliateIdentifierChangeCallback(null);
  }, [setInsertAffiliateIdentifierChangeCallback]);

  // Handle expired attribution - clear offer code and set timeout timestamp
  // NOTE: insert_affiliate is preserved for renewal webhook attribution
  // insert_timedout stores the TIMESTAMP when attribution expired (storedDate + timeout)
  // Webhook compares this against purchase dates to determine if purchases should be attributed:
  // - Purchases made BEFORE timeout → attributed (initial + all renewals)
  // - Purchases made AFTER timeout → not attributed (initial + all renewals)
  useEffect(() => {
    if (!isInitialized) return;

    const clearExpiredAffiliation = async () => {
      const isValid = await isAffiliateAttributionValid();
      if (!isValid) {
        const expiryTimestamp = await getAffiliateExpiryTimestamp();
        if (!expiryTimestamp) return; // No timeout configured

        await Purchases.setAttributes({
          "affiliateOfferCode": "",
          "insert_timedout": expiryTimestamp.toString()
        });
        await Purchases.syncAttributesAndOfferingsIfNeeded();
      }
    };

    // Check on app initialization
    clearExpiredAffiliation();

    // Check when app returns to foreground
    const subscription = AppState.addEventListener('change', (state) => {
      if (state === 'active') {
        clearExpiredAffiliation();
      }
    });

    return () => subscription?.remove();
  }, [isInitialized, isAffiliateAttributionValid, getAffiliateExpiryTimestamp]);

  return <YourAppContent />;
};

RevenueCat Targeting: Use the affiliateOfferCode attribute in your RevenueCat Targeting rules to show different offerings to affiliates (e.g., extended free trials). Set a rule like affiliateOfferCode is any of ["oneWeekFree", "twoWeeksFree"] to target users with specific offer codes.

Step 2: Webhook Setup

1. In RevenueCat, create a new webhook
2. Configure webhook settings:
   • Webhook URL: https://api.insertaffiliate.com/v1/api/revenuecat-webhook
   • Event Type: "All events"
3. In your Insert Affiliate dashboard:
   • Set In-App Purchase Verification to RevenueCat
   • Copy the RevenueCat Webhook Authentication Header value
4. Back in RevenueCat webhook config:
   • Paste the authentication header value into the Authorization header field

RevenueCat setup complete! Now skip to Step 3: Set Up Deep Linking

Step 1: Install Adapty SDK

npm install react-native-adapty

For bare React Native: Run cd ios && pod install && cd ..

For Expo managed workflow: Pods install automatically with npx expo prebuild or npx expo run:ios.

Complete the Adapty SDK installation for any additional platform-specific setup.

Step 2: Code Setup

import React, { useEffect, useRef } from 'react';
import { adapty } from 'react-native-adapty';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

const ADAPTY_PUBLIC_SDK_KEY = 'YOUR_ADAPTY_PUBLIC_SDK_KEY'; // From https://app.adapty.io/

const App = () => {
  const { initialize, isInitialized, setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();
  const adaptyActivationPromiseRef = useRef(null);

  // Initialize Adapty SDK
  useEffect(() => {
    const initAdapty = async () => {
      try {
        adaptyActivationPromiseRef.current = adapty.activate(ADAPTY_PUBLIC_SDK_KEY, {
          __ignoreActivationOnFastRefresh: __DEV__,
        });
        await adaptyActivationPromiseRef.current;
      } catch (error) {
        console.error('Failed to activate Adapty SDK:', error);
      }
    };

    if (!adaptyActivationPromiseRef.current) {
      initAdapty();
    }
  }, []);

  // Initialize Insert Affiliate SDK
  useEffect(() => {
    if (!isInitialized) {
      initialize("YOUR_COMPANY_CODE");
    }
  }, [initialize, isInitialized]);

  // Set Adapty attribute when affiliate identifier changes
  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
      if (identifier) {
        if (adaptyActivationPromiseRef.current) {
          try {
            // Wait for Adapty activation before updating profile
            await adaptyActivationPromiseRef.current;

            await adapty.updateProfile({
              codableCustomAttributes: {
                insert_affiliate: identifier,
              },
            });
          } catch (error) {
            console.error('Failed to update Adapty profile with affiliate identifier:', error);
          }
        } else {
          console.error('Adapty SDK is not initialized');
        }
      }
    });

    return () => setInsertAffiliateIdentifierChangeCallback(null);
  }, [setInsertAffiliateIdentifierChangeCallback]);

  return <YourAppContent />;
};

Step 3: Webhook Setup

1. In your Insert Affiliate dashboard:

   • Set In-App Purchase Verification to Adapty
   • Copy the Adapty Webhook URL
   • Copy the Adapty Webhook Authorization Header value

2. In the Adapty Dashboard:

   • Navigate to Integrations → Webhooks
   • Set Production URL to the webhook URL from Insert Affiliate
   • Set Sandbox URL to the same webhook URL
   • Paste the authorization header value into Authorization header value
   • Enable these options:
     • Exclude historical events
     • Send attribution
     • Send trial price
     • Send user attributes
   • Save the configuration

Step 4: Verify Integration

To confirm the affiliate identifier is set correctly:

1. Go to app.adapty.io/profiles/users
2. Find the test user who made a purchase
3. Look for insert_affiliate in Custom attributes with format: {SHORT_CODE}-{UUID}

Adapty setup complete! Now skip to Step 3: Set Up Deep Linking

Step 1: Code Setup

Complete the Iaptic account setup first, then add to your component:

import React, { useEffect, useState } from 'react';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
import { useIAP } from 'react-native-iap';

const App = () => {
  const { initialize, isInitialized, validatePurchaseWithIapticAPI } = useDeepLinkIapProvider();
  const { currentPurchase } = useIAP();

  useEffect(() => {
    if (!isInitialized) {
      initialize("YOUR_COMPANY_CODE");
    }
  }, [initialize, isInitialized]);

  // Validate purchases with Iaptic
  useEffect(() => {
    if (currentPurchase) {
      validatePurchaseWithIapticAPI(
        currentPurchase,
        'YOUR_IAPTIC_APP_ID',
        'YOUR_IAPTIC_APP_NAME',
        'YOUR_IAPTIC_PUBLIC_KEY'
      ).then((isValid) => {
        console.log(isValid ? "Purchase validated" : "Validation failed");
      });
    }
  }, [currentPurchase]);

  return <YourAppContent />;
};

Replace:

• YOUR_IAPTIC_APP_ID with your Iaptic App ID
• YOUR_IAPTIC_APP_NAME with your Iaptic App Name
• YOUR_IAPTIC_PUBLIC_KEY with your Iaptic Public Key

Step 2: Webhook Setup

1. Open Insert Affiliate settings:
   • Set the In-App Purchase Verification method to Iaptic
   • Copy the Iaptic Webhook URL and Iaptic Webhook Sandbox URL
2. Go to Iaptic Settings:
   • Paste the Webhook URLs into the corresponding fields
   • Click Save Settings
3. Complete the Iaptic App Store Server Notifications setup
4. Complete the Iaptic Google Play Notifications setup

Iaptic setup complete! Now proceed to Step 3: Set Up Deep Linking

Step 1: Apple App Store Notification Setup

Visit our docs and complete the required App Store Server to Server Notifications setup.

Step 2: Implementing Purchases

import { Platform } from 'react-native';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
import { requestSubscription } from 'react-native-iap';

const { returnUserAccountTokenAndStoreExpectedTransaction } = useDeepLinkIapProvider();

const handleBuySubscription = async (product) => {
  try {
    let appAccountToken = null;

    if (Platform.OS === 'ios') {
      appAccountToken = await returnUserAccountTokenAndStoreExpectedTransaction();
    }

    await requestSubscription({
      sku: product.productId,
      ...(appAccountToken ? { applicationUsername: appAccountToken } : {}),
    });
  } catch (error) {
    console.error("Error processing subscription:", error);
  }
};

App Store Direct setup complete! Now proceed to Step 3: Set Up Deep Linking

Step 1: RTDN Setup

Visit our docs and complete the required Real Time Developer Notifications setup.

Step 2: Implementing Purchases

import React, { useEffect } from 'react';
import { Platform } from 'react-native';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
import { useIAP } from 'react-native-iap';

const App = () => {
  const { storeExpectedStoreTransaction } = useDeepLinkIapProvider();
  const { currentPurchase } = useIAP();

  useEffect(() => {
    if (currentPurchase && Platform.OS === 'android' && currentPurchase.purchaseToken) {
      storeExpectedStoreTransaction(currentPurchase.purchaseToken);
    }
  }, [currentPurchase, storeExpectedStoreTransaction]);

  return <YourAppContent />;
};

Google Play Direct setup complete! Now proceed to Step 3: Set Up Deep Linking

3. Set Up Deep Linking

Deep linking lets affiliates share unique links that track users to your app. Choose ONE deep linking provider:

| Provider | Best For | Complexity | Setup Guide | |----------|----------|------------|-------------| | Insert Links | Simple setup, no 3rd party | Simple | View | | Branch.io | Robust attribution, deferred deep linking | Medium | View | | AppsFlyer | Enterprise analytics, comprehensive attribution | Medium | View |

Insert Links is Insert Affiliate's built-in deep linking solution - no third-party SDK required.

Prerequisites:

• Complete the Insert Links setup in the Insert Affiliate dashboard

Step 1: Initialize with Insert Links enabled

useEffect(() => {
  if (!isInitialized) {
    initialize(
      "YOUR_COMPANY_CODE",
      true,   // verboseLogging
      true,   // insertLinksEnabled
      false   // insertLinksClipboardEnabled (set true for better attribution, triggers permission)
    );
  }
}, [initialize, isInitialized]);

Step 2: Set up the identifier change callback

Choose the example that matches your IAP verification platform:

With RevenueCat:

import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
import Purchases from 'react-native-purchases';

const App = () => {
  const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();

  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier, offerCode) => {
      if (identifier) {
        await Purchases.setAttributes({
          "insert_affiliate": identifier,
          "affiliateOfferCode": offerCode || ""  // For RevenueCat Targeting
        });
        await Purchases.syncAttributesAndOfferingsIfNeeded();
      }
    });

    return () => setInsertAffiliateIdentifierChangeCallback(null);
  }, []);

  return <YourAppContent />;
};

Note: For full RevenueCat integration with attribution timeout cleanup, see the complete example in Option 1 above.

With Adapty:

import React, { useEffect, useRef } from 'react';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
import { adapty } from 'react-native-adapty';

const App = () => {
  const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();
  const adaptyActivationPromiseRef = useRef(null);

  // Initialize Adapty SDK (see Option 2: Adapty for full setup)
  useEffect(() => {
    const initAdapty = async () => {
      try {
        adaptyActivationPromiseRef.current = adapty.activate('YOUR_ADAPTY_PUBLIC_SDK_KEY', {
          __ignoreActivationOnFastRefresh: __DEV__,
        });
        await adaptyActivationPromiseRef.current;
      } catch (error) {
        console.error('Failed to activate Adapty SDK:', error);
      }
    };

    if (!adaptyActivationPromiseRef.current) {
      initAdapty();
    }
  }, []);

  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
      if (identifier && adaptyActivationPromiseRef.current) {
        try {
          await adaptyActivationPromiseRef.current;
          await adapty.updateProfile({
            codableCustomAttributes: {
              insert_affiliate: identifier,
            },
          });
        } catch (error) {
          console.error('Failed to update Adapty profile:', error);
        }
      }
    });

    return () => setInsertAffiliateIdentifierChangeCallback(null);
  }, [setInsertAffiliateIdentifierChangeCallback]);

  return <YourAppContent />;
};

With Apphud:

import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
import Apphud from 'react-native-apphud';

const App = () => {
  const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();

  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
      if (identifier) {
        await Apphud.setUserProperty("insert_affiliate", identifier, false);
      }
    });

    return () => setInsertAffiliateIdentifierChangeCallback(null);
  }, []);

  return <YourAppContent />;
};

With Iaptic:

import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
import InAppPurchase from 'react-native-iaptic';

const App = () => {
  const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();

  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
      if (identifier) {
        InAppPurchase.stop();
        InAppPurchase.initialize({
          iapProducts: iapProductsArray,
          validatorUrlString: "https://validator.iaptic.com/v3/validate?appName=YOUR_APP_NAME&apiKey=YOUR_API_KEY",
          applicationUsername: identifier
        });
      }
    });

    return () => setInsertAffiliateIdentifierChangeCallback(null);
  }, []);

  return <YourAppContent />;
};

With App Store / Google Play Direct:

import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

const App = () => {
  const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();

  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
      if (identifier) {
        console.log('Affiliate identifier stored:', identifier);
        // Identifier is stored automatically for direct store integration
      }
    });

    return () => setInsertAffiliateIdentifierChangeCallback(null);
  }, []);

  return <YourAppContent />;
};

Step 3: iOS Native Setup (Required)

Update your ios/YourApp/AppDelegate.mm:

#import <React/RCTLinkingManager.h>

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
  return [RCTLinkingManager application:application openURL:url options:options];
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void(^)(NSArray * __nullable restorableObjects))restorationHandler
{
  return [RCTLinkingManager application:application
                   continueUserActivity:userActivity
                     restorationHandler:restorationHandler];
}

Step 4: Expo Router Setup (If Using Expo Router)

If you're using Expo Router, deep links will cause a "This screen does not exist" error because both the Insert Affiliate SDK and Expo Router try to handle the incoming URL. The SDK correctly processes the affiliate attribution, but Expo Router simultaneously attempts to navigate to the URL path (e.g., /insert-affiliate), which doesn't exist as a route.

To fix this, create app/+native-intent.tsx to intercept Insert Affiliate URLs before Expo Router processes them:

// app/+native-intent.tsx
// Tell Expo Router to skip navigation for Insert Affiliate URLs
// The SDK handles these via native Linking - we just prevent router errors

export function redirectSystemPath({ path }: { path: string }): string | null {
  // Skip navigation for Insert Affiliate deep links
  if (path.includes('insert-affiliate') || path.includes('insertAffiliate')) {
    return null; // SDK handles it via Linking API
  }
  return path; // Let Expo Router handle all other URLs normally
}

This ensures:

• The Insert Affiliate SDK still receives and processes the URL via the native Linking API
• Expo Router ignores the URL and doesn't attempt navigation
• No "screen not found" errors

See the Expo Router +native-intent docs for more details.

Testing Deep Links:

# iOS Simulator
xcrun simctl openurl booted "YOUR_IOS_URL_SCHEME://TEST_SHORT_CODE"

# Android Emulator
adb shell am start -W -a android.intent.action.VIEW -d "YOUR_ANDROID_URL_SCHEME://TEST_SHORT_CODE"

Insert Links setup complete! Skip to Verify Your Integration

Branch.io provides robust attribution and deferred deep linking capabilities.

Key Integration Steps:

1. Install and configure Branch SDK for React Native
2. Subscribe to Branch deep link events
3. Extract ~referring_link from Branch callback
4. Pass to Insert Affiliate SDK using setInsertAffiliateIdentifier()

View complete Branch.io integration guide

Includes full examples for:

• RevenueCat integration
• Adapty integration
• Apphud integration
• Iaptic integration
• App Store / Google Play Direct integration

After completing Branch setup, skip to Verify Your Integration

AppsFlyer provides enterprise-grade analytics and comprehensive attribution.

Key Integration Steps:

1. Install and configure AppsFlyer SDK for React Native
2. Create AppsFlyer OneLink in dashboard
3. Listen for onDeepLink, onAppOpenAttribution, and onInstallConversionData callbacks
4. Pass to Insert Affiliate SDK using setInsertAffiliateIdentifier()

View complete AppsFlyer integration guide

Includes full examples for:

• RevenueCat integration
• Adapty integration
• Apphud integration
• Iaptic integration
• Store Direct integration
• Deferred deep linking setup

After completing AppsFlyer setup, proceed to Verify Your Integration

✅ Verify Your Integration

Before going live, verify everything works correctly:

Integration Checklist

• [ ] SDK Initializes: Check console for SDK initialized with company code log
• [ ] Affiliate Identifier Stored: Click a test affiliate link and verify identifier is stored
• [ ] Purchase Tracked: Make a test purchase and verify transaction appears in Insert Affiliate dashboard

Testing Commands

Test Deep Link (iOS Simulator):

xcrun simctl openurl booted "https://your-deep-link-url/abc123"

Test Deep Link (Android Emulator):

adb shell am start -W -a android.intent.action.VIEW -d "https://your-deep-link-url/abc123"

Check Stored Affiliate Identifier:

const affiliateId = await returnInsertAffiliateIdentifier();
console.log('Current affiliate ID:', affiliateId);

Common Setup Issues

| Issue | Solution | |-------|----------| | "Company code is not set" | Ensure initialize() is called before any other SDK methods | | "No affiliate identifier found" | User must click an affiliate link before making a purchase | | Deep link opens browser instead of app | Verify URL schemes in Info.plist (iOS) and AndroidManifest.xml (Android) | | Purchase not tracked | Check webhook configuration in IAP verification platform |

🔧 Advanced Features

Track custom events beyond purchases (e.g., signups, referrals) to incentivize affiliates for specific actions.

const { trackEvent } = useDeepLinkIapProvider();

// Track custom event (affiliate identifier must be set first)
await trackEvent('user_signup');

Use Cases:

• Pay affiliates for signups instead of purchases
• Track trial starts, content unlocks, or other conversions

Short codes are unique, 3-25 character alphanumeric identifiers that affiliates can share (e.g., "SAVE20" in a TikTok video description).

Validate and Store Short Code:

const { setShortCode } = useDeepLinkIapProvider();

const handleApplyCode = async (code) => {
  const isValid = await setShortCode(code);
  if (isValid) {
    Alert.alert('Success', 'Affiliate code applied!');
  } else {
    Alert.alert('Error', 'Invalid affiliate code');
  }
};

Get Affiliate Details Without Setting:

const { getAffiliateDetails } = useDeepLinkIapProvider();

const details = await getAffiliateDetails('SAVE20');
if (details) {
  console.log('Affiliate Name:', details.affiliateName);
  console.log('Short Code:', details.affiliateShortCode);
  console.log('Deep Link:', details.deeplinkurl);
}

Learn more: Short Codes Documentation

Automatically apply discounts or trials when users come from specific affiliates.

How It Works:

1. Configure an offer code modifier in your Insert Affiliate dashboard (e.g., _oneWeekFree)
2. SDK automatically fetches and stores the modifier when affiliate identifier is set
3. Use the modifier to construct dynamic product IDs

Quick Example:

const { OfferCode } = useDeepLinkIapProvider();

const baseProductId = "oneMonthSubscription";
const dynamicProductId = OfferCode
  ? `${baseProductId}${OfferCode}`  // e.g., "oneMonthSubscription_oneWeekFree"
  : baseProductId;

// Use dynamicProductId when fetching/purchasing products

View complete Dynamic Offer Codes guide

Includes full examples for:

• App Store Connect and Google Play Console setup
• RevenueCat integration with dynamic product selection
• Native react-native-iap integration
• Testing and troubleshooting

Control how long affiliate attribution remains active after a user clicks a link.

Set Timeout During Initialization:

// 7-day attribution window (604800 seconds)
initialize(
  "YOUR_COMPANY_CODE",
  false,  // verboseLogging
  false,  // insertLinksEnabled
  false,  // insertLinksClipboardEnabled
  604800  // affiliateAttributionActiveTime
);

Check Attribution Validity:

const { isAffiliateAttributionValid, getAffiliateStoredDate } = useDeepLinkIapProvider();

const isValid = await isAffiliateAttributionValid();
const storedDate = await getAffiliateStoredDate();

Common Timeout Values:

• 1 day: 86400
• 7 days: 604800 (recommended)
• 30 days: 2592000
• No timeout: omit parameter (default)

Bypass Timeout Check:

// Get identifier even if attribution has expired
const rawIdentifier = await returnInsertAffiliateIdentifier(true);

Prevent Affiliate Transfer

By default, clicking a new affiliate link will overwrite any existing attribution. Enable preventAffiliateTransfer to lock the first affiliate:

initialize(
  "YOUR_COMPANY_CODE",
  false,   // verboseLogging
  false,   // insertLinksEnabled
  false,   // insertLinksClipboardEnabled
  604800,  // affiliateAttributionActiveTime (7 days)
  true     // preventAffiliateTransfer - locks first affiliate
);

How it works:

• When enabled, once a user is attributed to an affiliate, that attribution is locked
• New affiliate links will not overwrite the existing attribution
• The callback still fires with the existing affiliate data (not the new one)
• Useful for preventing "affiliate stealing" where users click competitor links

Learn more: Prevent Affiliate Transfer Documentation

🔍 Troubleshooting

Initialization Issues

Error: "Company code is not set"

• Cause: SDK not initialized or initialize() called after other SDK methods
• Solution: Call initialize() in your main App component's useEffect before any other SDK methods

Deep Linking Issues

Problem: Deep link opens browser instead of app

• Cause: Missing or incorrect URL scheme configuration
• Solution:
  • iOS: Add URL scheme to Info.plist and configure associated domains
  • Android: Add intent filters to AndroidManifest.xml

Problem: "This screen does not exist" error with Expo Router

• Cause: Both Insert Affiliate SDK and Expo Router are trying to handle the same URL
• Solution: Create app/+native-intent.tsx to intercept Insert Affiliate URLs before Expo Router processes them. See Expo Router Setup in the Insert Links section.

Problem: "No affiliate identifier found"

• Cause: User hasn't clicked an affiliate link yet
• Solution: Test with simulator/emulator:

  # iOS
  xcrun simctl openurl booted "YOUR_DEEP_LINK_URL"
  # Android
  adb shell am start -W -a android.intent.action.VIEW -d "YOUR_DEEP_LINK_URL"

Purchase Tracking Issues

Problem: Purchases not appearing in Insert Affiliate dashboard

• Cause: Webhook not configured or affiliate identifier not passed to IAP platform
• Solution:
  • Verify webhook URL and authorization headers are correct
  • For RevenueCat: Confirm insert_affiliate attribute is set before purchase
  • Enable verbose logging and check console for errors

Verbose Logging

Enable detailed logs during development to diagnose issues:

initialize("YOUR_COMPANY_CODE", true);  // second parameter enables verbose logging

Important: Disable verbose logging in production builds.

Getting Help

• Documentation
• Dashboard Support
• Report Issues

📚 Support

• Documentation: docs.insertaffiliate.com
• Dashboard Support: app.insertaffiliate.com/help
• Issues: GitHub Issues
• Company Code: Get yours from Settings

Need help getting started? Check out our quickstart guide or contact support.