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)

cd ios && pod install && cd ..

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
);

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)

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 Purchases from 'react-native-purchases';
import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';

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

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

  // Set RevenueCat attribute when affiliate identifier changes
  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
      if (identifier) {
        await Purchases.setAttributes({ "insert_affiliate": identifier });
      }
    });

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

  return <YourAppContent />;
};

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
cd ios && pod install && cd ..

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

Step 2: Code Setup

import React, { useEffect } 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();

  // Initialize both SDKs
  useEffect(() => {
    const initSDKs = async () => {
      // Initialize Adapty
      await adapty.activate(ADAPTY_PUBLIC_SDK_KEY);

      // Initialize Insert Affiliate
      if (!isInitialized) {
        initialize("YOUR_COMPANY_CODE");
      }
    };
    initSDKs();
  }, [initialize, isInitialized]);

  // Set Adapty attribute when affiliate identifier changes
  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
      if (identifier) {
        await adapty.updateProfile({
          codableCustomAttributes: {
            insert_affiliate: identifier,
          },
        });
      }
    });

    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) => {
      if (identifier) {
        await Purchases.setAttributes({ "insert_affiliate": identifier });
      }
    });

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

  return <YourAppContent />;
};

With Adapty:

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

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

  useEffect(() => {
    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
      if (identifier) {
        await adapty.updateProfile({
          codableCustomAttributes: {
            insert_affiliate: identifier,
          },
        });
      }
    });

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

  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];
}

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);

🔍 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: "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.