A package for connecting with the Insert Affiliate Platform to add app based affiliate marketing.
npm install insert-affiliate-react-native-sdk!Version !React Native !Platform
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.
- 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
---
Get up and running with minimal code to validate the SDK works before tackling IAP and deep linking setup.
- React Native 0.60+
- iOS 13.0+ / Android API 21+
- Company Code from your Insert Affiliate dashboard
Step 1: Install the SDK package
``bash`
npm install insert-affiliate-react-native-sdk
Step 2: Install required peer dependencies
`bash`
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:
`bash`
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.
In index.js - Wrap your app with the provider:
`javascript
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 (
);
};
AppRegistry.registerComponent(appName, () => RootComponent);
`
In App.tsx - Initialize the SDK:
`javascript
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 (
);
};
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.
---
Complete these three required steps to start tracking affiliate-driven purchases.
You've already done basic initialization above. Here are additional options:
#### Basic Initialization (Recommended for Getting Started)
`javascript`
initialize("YOUR_COMPANY_CODE", true); // verbose logging enabled
Advanced Initialization Options (click to expand)
`javascript`
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/AppsFlyerinsertLinksClipboardEnabled
- : Enables clipboard-based attribution for Insert LinksaffiliateAttributionActiveTime
- Improves attribution accuracy when deep linking fails
- iOS will show a permission prompt: "[Your App] would like to paste from [App Name]"
- : 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
---
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 |
Option 1: RevenueCat (Recommended)
Step 1: Code Setup
Complete the RevenueCat SDK installation first, then add to your App.tsx:
`javascript
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
};
`
> 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-webhookRevenueCat
- Event Type: "All events"
3. In your Insert Affiliate dashboard:
- Set In-App Purchase Verification to RevenueCat Webhook Authentication Header
- Copy the 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
Option 2: Adapty
Step 1: Install Adapty SDK
`bash`
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
`javascript
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
};
`
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
Option 3: Iaptic
Step 1: Code Setup
Complete the Iaptic account setup first, then add to your component:
`javascript
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
};
`
Replace:
- YOUR_IAPTIC_APP_ID with your Iaptic App IDYOUR_IAPTIC_APP_NAME
- with your Iaptic App NameYOUR_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 IapticIaptic Webhook URL
- Copy the 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
Option 4: App Store Direct
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
`javascript
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
Option 5: Google Play Direct
Step 1: RTDN Setup
Visit our docs and complete the required Real Time Developer Notifications setup.
Step 2: Implementing Purchases
`javascript
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
};
`
Google Play Direct setup complete! Now proceed to Step 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 |
Option 1: Insert Links (Simplest)
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
`javascript`
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:
`javascript
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
};
`
> Note: For full RevenueCat integration with attribution timeout cleanup, see the complete example in Option 1 above.
With Adapty:
`javascript
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
};
`
With Apphud:
`javascript
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
};
`
With Iaptic:
`javascript
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
};
`
With App Store / Google Play Direct:
`javascript
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
};
`
Step 3: iOS Native Setup (Required)
Update your ios/YourApp/AppDelegate.mm:
`objc
#import
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:(NSDictionary
{
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:
`tsx
// 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:
`bashiOS Simulator
xcrun simctl openurl booted "YOUR_IOS_URL_SCHEME://TEST_SHORT_CODE"
Insert Links setup complete! Skip to Verify Your Integration
Option 2: Branch.io
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
Option 3: AppsFlyer
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:
$3
- [ ] 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$3
Test Deep Link (iOS Simulator):
`bash
xcrun simctl openurl booted "https://your-deep-link-url/abc123"
`Test Deep Link (Android Emulator):
`bash
adb shell am start -W -a android.intent.action.VIEW -d "https://your-deep-link-url/abc123"
`Check Stored Affiliate Identifier:
`javascript
const affiliateId = await returnInsertAffiliateIdentifier();
console.log('Current affiliate ID:', affiliateId);
`$3
| 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
Event Tracking (Beta)
Track custom events beyond purchases (e.g., signups, referrals) to incentivize affiliates for specific actions.
`javascript
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
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:
`javascript
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:
`javascript
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
Dynamic Offer Codes / Discounts
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 IDsQuick Example:
`javascript
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
Attribution Timeout Control
Control how long affiliate attribution remains active after a user clicks a link.
Set Timeout During Initialization:
`javascript
// 7-day attribution window (604800 seconds)
initialize(
"YOUR_COMPANY_CODE",
false, // verboseLogging
false, // insertLinksEnabled
false, // insertLinksClipboardEnabled
604800 // affiliateAttributionActiveTime
);
`Check Attribution Validity:
`javascript
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:
`javascript
// Get identifier even if attribution has expired
const rawIdentifier = await returnInsertAffiliateIdentifier(true);
`$3
By default, clicking a new affiliate link will overwrite any existing attribution. Enable
preventAffiliateTransfer to lock the first affiliate:`javascript
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
$3
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$3
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:
`bash
# 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"
`$3
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$3
Enable detailed logs during development to diagnose issues:
`javascript
initialize("YOUR_COMPANY_CODE", true); // second parameter enables verbose logging
``Important: Disable verbose logging in production builds.
- Documentation
- Dashboard Support
- Report Issues
---
- 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.