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

package/readme.md

@@ -1,72 +1,65 @@
 # InsertAffiliateReactNative SDK
 
-## Overview
+![Version](https://img.shields.io/badge/version-1.0.0-brightgreen) ![React Native](https://img.shields.io/badge/React%20Native-0.60%2B-blue) ![Platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey)
 
-The **InsertAffiliateReactNative SDK** is designed for React Native applications, providing seamless integration with the [Insert Affiliate platform](https://insertaffiliate.com). The InsertAffiliateReactNative SDK simplifies affiliate marketing for iOS apps with in-app-purchases, allowing developers to create a seamless user experience for affiliate tracking and monetisation.
+The official React Native SDK for [Insert Affiliate](https://insertaffiliate.com) - track affiliate-driven in-app purchases and reward your partners automatically.
 
-### Features
+**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.
 
-- **Unique Device ID**: Creates a unique ID to anonymously associate purchases with users for tracking purposes.
-- **Affiliate Identifier Management**: Set and retrieve the affiliate identifier based on user-specific links.
-- **In-App Purchase (IAP) Initialisation**: Easily reinitialise in-app purchases with the option to validate using an affiliate identifier.
+## Table of Contents
 
-## Getting Started
+- [Quick Start (5 Minutes)](#-quick-start-5-minutes)
+- [Essential Setup](#%EF%B8%8F-essential-setup)
+  - [1. Initialize the SDK](#1-initialize-the-sdk)
+  - [2. Configure In-App Purchase Verification](#2-configure-in-app-purchase-verification)
+  - [3. Set Up Deep Linking](#3-set-up-deep-linking)
+- [Verify Your Integration](#-verify-your-integration)
+- [Advanced Features](#-advanced-features)
+- [Troubleshooting](#-troubleshooting)
+- [Support](#-support)
 
-To get started with the InsertAffiliateReactNative SDK:
+---
+
+## 🚀 Quick Start (5 Minutes)
+
+Get up and running with minimal code to validate the SDK works before tackling IAP and deep linking setup.
 
-1. [Install the SDK](#installation)
-2. [Set up the provider in Index.js and initialize the SDK in App.tsx](#basic-usage)
-3. [Set up in-app purchases (Required)](#in-app-purchase-setup-required)
-4. [Set up deep linking in Index.js (Required)](#deep-link-setup-required)
+### Prerequisites
 
-## Installation
+- **React Native 0.60+**
+- **iOS 13.0+** / **Android API 21+**
+- **Company Code** from your [Insert Affiliate dashboard](https://app.insertaffiliate.com/settings)
 
-To integrate the InsertAffiliateReactNative SDK into your app:
+### Installation
+
+**Step 1:** Install the SDK package
 
-1. Install the NPM package and its required peer dependencies.
 ```bash
 npm install insert-affiliate-react-native-sdk
 ```
 
-2. Install the required peer dependencies:
+**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
 ```
 
-### Required Dependencies
-
-The SDK requires the following peer dependencies to function properly:
+**Step 3:** Install iOS pods (iOS only)
 
-- **`@react-native-async-storage/async-storage`** (>= 1.0.0) - For persistent storage of affiliate identifiers and user data
-- **`@react-native-clipboard/clipboard`** (>= 1.16.0) - For clipboard-based affiliate link detection (Insert Links feature)
-- **`@react-native-community/netinfo`** (>= 11.4.0) - For network connectivity detection and system information collection
-- **`react-native-device-info`** (>= 10.0.0) - For device information and system data collection
-- **`axios`** (>= 1.0.0) - For API communication with Insert Affiliate services
-- **`react`** (>= 16.0.0) - React framework
-- **`react-native`** (>= 0.60.0) - React Native framework
-
-**Note**: These dependencies must be installed in your app for the SDK to work. If any are missing, you'll get runtime errors when the SDK tries to use them.
-
-## Architecture Overview
-
-The SDK uses a clean, two-file architecture:
-
-- **`index.js`** (Entry Point): Provider wrapper and deep link handling
-- **`App.tsx`** (UI Logic): SDK initialization and your app components
-
-This separation ensures clean code organization and proper initialization timing.
+```bash
+cd ios && pod install && cd ..
+```
 
-## Basic Usage
+### Your First Integration
 
-Follow the steps below to install the SDK.
+**In `index.js`** - Wrap your app with the provider:
 
-### Step 1: Entry Point in `Index.js`
 ```javascript
 import React from 'react';
-import {AppRegistry} from 'react-native';
+import { AppRegistry } from 'react-native';
 import App from './App';
-import {name as appName} from './app.json';
-import {DeepLinkIapProvider} from 'insert-affiliate-react-native-sdk';
+import { name as appName } from './app.json';
+import { DeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
 
 const RootComponent = () => {
   return (
@@ -79,433 +72,411 @@ const RootComponent = () => {
 AppRegistry.registerComponent(appName, () => RootComponent);
 ```
 
-#### Step 2: SDK initialization in `App.tsx`
-
-First, wrap your with our provider and call the `initialize` method early in your app's lifecycle:
+**In `App.tsx`** - Initialize the SDK:
 
 ```javascript
-const Child = () => {
+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 }}");
+      initialize(
+        "YOUR_COMPANY_CODE",  // Get from https://app.insertaffiliate.com/settings
+        true                   // Enable verbose logging for setup
+      );
     }
   }, [initialize, isInitialized]);
-}
 
-const App = () => {
-  return <Child />;
+  return (
+    <View>
+      <Text>My App</Text>
+    </View>
+  );
 };
+
+export default App;
 ```
-- Replace `{{ your_company_code }}` with the unique company code associated with your Insert Affiliate account. You can find this code in your dashboard under [Settings](http://app.insertaffiliate.com/settings).
 
-### Verbose Logging (Optional)
+**Expected Console Output:**
 
-By default, the SDK operates silently to avoid interrupting the user experience. However, you can enable verbose logging to see visual confirmation when affiliate attribution is processed. This is particularly useful for debugging during development or TestFlight testing.
+When the SDK initializes successfully, you'll see:
 
-#### Enable Verbose Logging
+```
+[Insert Affiliate] SDK initialized with company code: YOUR_COMPANY_CODE
+[Insert Affiliate] [VERBOSE] SDK marked as initialized
+```
 
-```javascript
-const Child = () => {
-  const { initialize, isInitialized } = useDeepLinkIapProvider();
+**If you see these logs, the SDK is working!** Now proceed to Essential Setup below.
 
-  useEffect(() => {
-    if (!isInitialized) {
-      // Enable verbose logging (second parameter)
-      initialize("{{ your-company-code }}", true);
-    }
-  }, [initialize, isInitialized]);
-}
-```
+**Important:** Disable verbose logging in production by setting the second parameter to `false`.
+
+---
+
+## ⚙️ Essential Setup
 
-**When verbose logging is enabled, you'll see detailed logs with the `[Insert Affiliate] [VERBOSE]` prefix that show:**
+Complete these three required steps to start tracking affiliate-driven purchases.
 
-- **Initialization Process**: SDK startup, company code validation, AsyncStorage operations
-- **Data Management**: User ID generation, referrer link storage, company code state management
-- **Deep Link / Insert Link Processing**: Input validation, short code detection, API conversion process
-- **API Communication**: Request/response details for all server calls
-- **Event Tracking**: Event parameters, payload construction, success/failure status
-- **Purchase Operations**: Transaction storage, token validation, webhook processing
+### 1. Initialize the SDK
 
-**Example verbose output:**
+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
 ```
-[Insert Affiliate] [VERBOSE] Starting SDK initialization...
-[Insert Affiliate] [VERBOSE] Company code provided: Yes
-[Insert Affiliate] [VERBOSE] Verbose logging enabled
-[Insert Affiliate] SDK initialized with company code: your-company-code
-[Insert Affiliate] [VERBOSE] Company code saved to AsyncStorage
-[Insert Affiliate] [VERBOSE] SDK marked as initialized
-[Insert Affiliate] [VERBOSE] Loading stored data from AsyncStorage...
-[Insert Affiliate] [VERBOSE] User ID found: Yes
-[Insert Affiliate] [VERBOSE] Referrer link found: Yes
-[Insert Affiliate] [VERBOSE] Company code found: Yes
+
+<details>
+<summary><strong>Advanced Initialization Options</strong> (click to expand)</summary>
+
+```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
+);
 ```
 
-**Benefits of verbose logging:**
-- **Debug Deep Linking Issues**: See exactly what links are being processed and how they're converted
-- **Monitor API Communication**: Track all server requests, responses, and error details
-- **Identify Storage Problems**: Understand AsyncStorage read/write operations and state sync
-- **Performance Insights**: Monitor async operation timing and identify bottlenecks
-- **Integration Troubleshooting**: Quickly identify configuration or setup issues
+**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)
+
+</details>
 
-⚠️ **Important**: Disable verbose logging in production builds to avoid exposing sensitive debugging information and to optimize performance.
+---
+
+### 2. Configure In-App Purchase Verification
 
-### Insert Link and Clipboard Control (BETA)
-We are currently beta testing our in-house deep linking provider, Insert Links, which generates links for use with your affiliates.
+**Insert Affiliate requires a receipt verification method to validate purchases.** Choose **ONE** of the following:
 
-For larger projects where accuracy is critical, we recommend using established third-party deep linking platforms to generate the links you use within Insert Affiliate - such as Appsflyer or Branch.io, as described in the rest of this README.
+| Method | Best For | Setup Time | Complexity |
+|--------|----------|------------|------------|
+| [**RevenueCat**](#option-1-revenuecat-recommended) | Most developers, managed infrastructure | ~10 min | Simple |
+| [**Adapty**](#option-2-adapty) | Paywall A/B testing, analytics | ~10 min | Simple |
+| [**Iaptic**](#option-3-iaptic) | Custom requirements, direct control | ~15 min | Medium |
+| [**App Store Direct**](#option-4-app-store-direct) | No 3rd party fees (iOS) | ~20 min | Medium |
+| [**Google Play Direct**](#option-5-google-play-direct) | No 3rd party fees (Android) | ~20 min | Medium |
 
-If you encounter any issues while using Insert Links, please raise an issue on this GitHub repository or contact us directly at michael@insertaffiliate.com
+<details open>
+<summary><h4>Option 1: RevenueCat (Recommended)</h4></summary>
 
-#### Initialize with Insert Links
+**Step 1: Code Setup**
 
-When using Insert Affiliate's built-in deep link handling (Insert Links), you can enable these features during initialization:
+Complete the [RevenueCat SDK installation](https://www.revenuecat.com/docs/getting-started/installation/reactnative) first, then add to your `App.tsx`:
 
 ```javascript
-const Child = () => {
-  const { initialize, isInitialized } = useDeepLinkIapProvider();
+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 }}", 
-        false, // Enable for debugging
-        true,  // Enables Insert Links
-        true,  // Enable Insert Links Clipboard access to avoid permission prompt
-        604800 // Optional: Attribution timeout in seconds (7 days)
-      );
+      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 />;
+};
 ```
 
-**When to use `insertLinksEnabled`:**
-- Set to `true` (default: `false`) if you are using Insert Affiliate's built-in deep link and universal link handling (Insert Links)
-- Set to `false` if you are using an external provider for deep links
+**Step 2: Webhook Setup**
 
-**When to use `insertLinksClipboardEnabled`:**
-- Set to `true` (default: `false`) if you are using Insert Affiliate's built-in deep links (Insert Links) **and** would like to improve the effectiveness of our deep links through the clipboard
-- **Important caveat**: This will trigger a system prompt asking the user for permission to access the clipboard when the SDK initializes
+1. In RevenueCat, [create a new webhook](https://www.revenuecat.com/docs/integrations/webhooks)
+2. Configure webhook settings:
+   - **Webhook URL**: `https://api.insertaffiliate.com/v1/api/revenuecat-webhook`
+   - **Event Type**: "All events"
+3. In your [Insert Affiliate dashboard](https://app.insertaffiliate.com/settings):
+   - 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](#3-set-up-deep-linking)
 
-## In-App Purchase Setup [Required]
-Insert Affiliate requires a Receipt Verification platform to validate in-app purchases. You must choose **one** of our supported partners:
-- [RevenueCat](https://www.revenuecat.com/)
-- [Iaptic](https://www.iaptic.com/account)
-- [App Store Direct Integration](#option-3-app-store-direct-integration)
-- [Google Play Store Direct Integration](#option-4-google-play-store-direct-integration)
+</details>
 
-### Option 1: RevenueCat Integration
-#### Step 1. Code Setup
-First, complete the [RevenueCat SDK installation](https://www.revenuecat.com/docs/getting-started/installation/reactnative). Then modify your `App.tsx`:
+<details>
+<summary><h4>Option 2: Adapty</h4></summary>
 
-```javascript
-import React, {useEffect} from 'react'; 
-import {AppRegistry} from 'react-native';
-import App from './App';
-import {name as appName} from './app.json';
-import {useDeepLinkIapProvider, DeepLinkIapProvider} from 'insert-affiliate-react-native-sdk';
-
-// ... //
-const {
-    initialize,
-    isInitialized,
-    returnInsertAffiliateIdentifier
-} = useDeepLinkIapProvider();
-
-React.useEffect(() => {
-    const handleAffiliateLogin = async () => {
-        try {
-            if (isInitialized) {
-                const affiliateIdentifier = await returnInsertAffiliateIdentifier();
-                
-                if (affiliateIdentifier) {
-                    await Purchases.setAttributes({"insert_affiliate" : affiliateIdentifier});
-                }
-            }
-        } catch (error) {
-            console.error('Error during affiliate login flow:', error);
-        }
-    };
+**Step 1: Install Adapty SDK**
 
-    handleAffiliateLogin();
-}, [isInitialized, returnInsertAffiliateIdentifier]);
-// ... //
+```bash
+npm install react-native-adapty
+cd ios && pod install && cd ..
 ```
 
-#### Step 2. Webhook Setup
+Complete the [Adapty SDK installation](https://adapty.io/docs/sdk-installation-reactnative) for any additional platform-specific setup.
 
-1. Go to RevenueCat and [create a new webhook](https://www.revenuecat.com/docs/integrations/webhooks)
+**Step 2: Code Setup**
 
-2. Configure the webhook with these settings:
-   - Webhook URL: `https://api.insertaffiliate.com/v1/api/revenuecat-webhook`
-   - Authorization header: Use the value from your Insert Affiliate dashboard (you'll get this in step 4)
-   - Set "Event Type" to "All events"
+```javascript
+import React, { useEffect } from 'react';
+import { adapty } from 'react-native-adapty';
+import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
 
-3. In your [Insert Affiliate dashboard settings](https://app.insertaffiliate.com/settings):
-   - Navigate to the verification settings
-   - Set the in-app purchase verification method to `RevenueCat`
+const ADAPTY_PUBLIC_SDK_KEY = 'YOUR_ADAPTY_PUBLIC_SDK_KEY'; // From https://app.adapty.io/
 
-4. Back in your Insert Affiliate dashboard:
-   - Locate the `RevenueCat Webhook Authentication Header` value
-   - Copy this value
-   - Paste it as the Authorization header value in your RevenueCat webhook configuration
+const App = () => {
+  const { initialize, isInitialized, setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();
 
+  // Initialize both SDKs
+  useEffect(() => {
+    const initSDKs = async () => {
+      // Initialize Adapty
+      await adapty.activate(ADAPTY_PUBLIC_SDK_KEY);
 
-### Option 2: Iaptic Integration
-#### 1. Code Setup
-First, complete the [Iaptic account setup](https://www.iaptic.com/signup) and code integration.
+      // Initialize Insert Affiliate
+      if (!isInitialized) {
+        initialize("YOUR_COMPANY_CODE");
+      }
+    };
+    initSDKs();
+  }, [initialize, isInitialized]);
 
-Then after setting up the in app purchase (IAP) with Iaptic, call Insert Affiliate's ```validatePurchaseWithIapticAPI``` on purchase.
+  // Set Adapty attribute when affiliate identifier changes
+  useEffect(() => {
+    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
+      if (identifier) {
+        await adapty.updateProfile({
+          codableCustomAttributes: {
+            insert_affiliate: identifier,
+          },
+        });
+      }
+    });
 
-```javascript
-import React from 'react';
-import { ActivityIndicator, Button, StyleSheet, Text, View } from 'react-native';
-import { DeepLinkIapProvider, useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import { useIAP, requestSubscription, withIAPContext, getProducts, getSubscriptions, initConnection } from "react-native-iap"; 
-
-const Child = () => {
-    const {
-        initialize,
-        isInitialized,
-        validatePurchaseWithIapticAPI,
-    } = useDeepLinkIapProvider();
-
-    const [iapLoading, setIapLoading] = useState(false);
-    const { currentPurchase, connected } = useIAP();
-    
-    // ***...***
-    // Fetch & Load your subscription/purchases and handling the IAP purchase here as per the Iaptic Documentation...
-    // ***...***
-
-    // Initialize the Insert Affiliate SDK at the earliest possible moment
-    useEffect(() => {
-        if (!isInitialized) {
-          initialize("{{ your_company_code }}");
-        }
-    }, [initialize, isInitialized]);
-
-    // Validate the purchase with Iaptic through Insert Affiliate's SDK for Affiliate Tracking
-    useEffect(() => {
-        if (currentPurchase) {
-            validatePurchaseWithIapticAPI(
-                currentPurchase,
-                '{{ your_iaptic_app_id }}',
-                '{{ your_iaptic_app_name }}',
-                '{{ your_iaptic_public_key }}',
-              ).then((isValid: boolean) => {
-                if (isValid) {
-                  console.log("Purchase validated successfully.");
-                } else {
-                  console.error("Purchase validation failed.");
-                }
-            });
-        }
-    }, [currentPurchase, handlePurchaseValidation]);
-    
-    return (
-        <View>
-            <Button
-                disabled={iapLoading}
-                title={`Click to Buy Subscription`}
-                onPress={() => handleBuySubscription("oneMonthSubscription")}
-            />
-            {iapLoading && <ActivityIndicator size={"small"} color={"black"} />}
-        </View>
-    );
-};
+    return () => setInsertAffiliateIdentifierChangeCallback(null);
+  }, [setInsertAffiliateIdentifierChangeCallback]);
 
-const App = () => {
-  return (
-    <Child />
-  );
+  return <YourAppContent />;
 };
-
-export default App;
 ```
-- Replace `{{ your_iaptic_app_id }}` with your **Iaptic App ID**. You can find this [here](https://www.iaptic.com/account).
-- Replace `{{ your_iaptic_app_name }}` with your **Iaptic App Name**. You can find this [here](https://www.iaptic.com/account).
-- Replace `{{ your_iaptic_public_key }}` with your **Iaptic Public Key**. You can find this [here](https://www.iaptic.com/settings).
-- Replace `{{ your_company_code }}` with the unique company code associated with your Insert Affiliate account. You can find this code in your dashboard under [Settings](http://app.insertaffiliate.com/settings).
 
-#### 2. Webhook Setup
-1. Open the [Insert Affiliate settings](https://app.insertaffiliate.com/settings):
-  - Navigate to the Verification Settings section
-  - Set the In-App Purchase Verification method to `Iaptic`
-  - Copy the `Iaptic Webhook URL` and the `Iaptic Webhook Sandbox URL`- you'll need it in the next step.
-2. Go to the [Iaptic Settings](https://www.iaptic.com/settings)
-- Paste the copied `Iaptic Webhook URL` into the `Webhook URL` field
-- Paste the copied `Iaptic Webhook Sandbox URL` into the `Sandbox Webhook URL` field
-- Click **Save Settings**.
-3. Check that you have completed the [Iaptic setup for the App Store Server Notifications](https://www.iaptic.com/documentation/setup/ios-subscription-status-url)
-4. Check that you have completed the [Iaptic setup for the Google Play Notifications URL](https://www.iaptic.com/documentation/setup/connect-with-google-publisher-api)
+**Step 3: Webhook Setup**
 
-### Option 3: App Store Direct Integration
+1. In your [Insert Affiliate dashboard](https://app.insertaffiliate.com/settings):
+   - Set **In-App Purchase Verification** to `Adapty`
+   - Copy the **Adapty Webhook URL**
+   - Copy the **Adapty Webhook Authorization Header** value
 
-Our direct App Store integration is currently in beta and currently supports subscriptions only. **Consumables and one-off purchases are not yet supported** due to App Store server-to-server notification limitations.
+2. In the [Adapty Dashboard](https://app.adapty.io/integrations):
+   - 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
 
-We plan to release support for consumables and one-off purchases soon. In the meantime, you can use a receipt verification platform from the other integration options.
+**Step 4: Verify Integration**
 
-#### Apple App Store Notification Setup
-To proceed, visit [our docs](https://docs.insertaffiliate.com/direct-store-purchase-integration#1-apple-app-store-server-notifications) and complete the required setup steps to set up App Store Server to Server Notifications.
+To confirm the affiliate identifier is set correctly:
+1. Go to [app.adapty.io/profiles/users](https://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}`
 
-#### Implementing Purchases
+**Adapty setup complete!** Now skip to [Step 3: Set Up Deep Linking](#3-set-up-deep-linking)
 
-##### 1. Import Required Modules  
+</details>
 
-Ensure you import the necessary dependencies, including `Platform` and `useDeepLinkIapProvider` from the SDK.  
+<details>
+<summary><h4>Option 3: Iaptic</h4></summary>
 
-```javascript
-import { Platform } from 'react-native';
-import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import { requestSubscription } from 'react-native-iap';
+**Step 1: Code Setup**
 
-const { returnUserAccountTokenAndStoreExpectedTransaction } = useDeepLinkIapProvider();
-```
+Complete the [Iaptic account setup](https://www.iaptic.com/signup) 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';
 
-##### 2. Handle the Purchase
-When a user initiates a subscription, retrieve the appAccountToken and pass it to the requestSubscription call:
+const App = () => {
+  const { initialize, isInitialized, validatePurchaseWithIapticAPI } = useDeepLinkIapProvider();
+  const { currentPurchase } = useIAP();
 
-```javascript
-const handleBuySubscription = async (product: SubscriptionAndroid | Subscription) => {
-    try {
-        let appAccountToken = null;
-
-        // Step 1: Retrieve the appAccountToken for iOS
-        if (Platform.OS === 'ios') {
-            appAccountToken = await returnUserAccountTokenAndStoreExpectedTransaction();
-        }
-
-        // Step 2: Request the subscription and pass the token for tracking
-        await requestSubscription({
-            sku: product?.productId,
-            ...(appAccountToken ? { applicationUsername: appAccountToken } : {}),
-        });
+  useEffect(() => {
+    if (!isInitialized) {
+      initialize("YOUR_COMPANY_CODE");
+    }
+  }, [initialize, isInitialized]);
 
-    } catch (error) {
-        console.error("Error processing subscription:", error);
+  // 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](https://www.iaptic.com/account)
+- `YOUR_IAPTIC_APP_NAME` with your [Iaptic App Name](https://www.iaptic.com/account)
+- `YOUR_IAPTIC_PUBLIC_KEY` with your [Iaptic Public Key](https://www.iaptic.com/settings)
 
-### Option 4: Google Play Store Direct Integration
-Our direct Google Play Store integration is currently in beta.
+**Step 2: Webhook Setup**
 
-#### Real Time Developer Notifications (RTDN) Setup
+1. Open [Insert Affiliate settings](https://app.insertaffiliate.com/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](https://www.iaptic.com/settings):
+   - Paste the Webhook URLs into the corresponding fields
+   - Click **Save Settings**
+3. Complete the [Iaptic App Store Server Notifications setup](https://www.iaptic.com/documentation/setup/ios-subscription-status-url)
+4. Complete the [Iaptic Google Play Notifications setup](https://www.iaptic.com/documentation/setup/connect-with-google-publisher-api)
 
-Visit [our docs](https://docs.insertaffiliate.com/direct-google-play-store-purchase-integration) and complete the required set up steps for Google Play's Real Time Developer Notifications.
+**Iaptic setup complete!** Now proceed to [Step 3: Set Up Deep Linking](#3-set-up-deep-linking)
 
-#### Implementing Purchases
+</details>
 
-##### 1. Import Required Modules  
+<details>
+<summary><h4>Option 4: App Store Direct</h4></summary>
 
-Ensure you import the necessary dependencies, including `Platform` and `useDeepLinkIapProvider` from the SDK.  
+**Step 1: Apple App Store Notification Setup**
+
+Visit [our docs](https://docs.insertaffiliate.com/direct-store-purchase-integration#1-apple-app-store-server-notifications) and complete the required App Store Server to Server Notifications setup.
+
+**Step 2: Implementing Purchases**
 
 ```javascript
-import React, {useEffect, useState} from 'react';
 import { Platform } from 'react-native';
-import { DeepLinkIapProvider, useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import { currentPurchase, requestSubscription } from 'react-native-iap';
-
-const { storeExpectedStoreTransaction } = useDeepLinkIapProvider();
+import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
+import { requestSubscription } from 'react-native-iap';
 
-useEffect(() => {
-    if (currentPurchase) {
-        if (Platform.OS === 'android' && currentPurchase.purchaseToken) {
-            // Step 1: Store the expected transaction for Google Play purchases
-            storeExpectedStoreTransaction(
-              currentPurchase.purchaseToken
-            );
-        }
-    }
-}, [currentPurchase, storeExpectedStoreTransaction]);
-```
+const { returnUserAccountTokenAndStoreExpectedTransaction } = useDeepLinkIapProvider();
 
+const handleBuySubscription = async (product) => {
+  try {
+    let appAccountToken = null;
 
+    if (Platform.OS === 'ios') {
+      appAccountToken = await returnUserAccountTokenAndStoreExpectedTransaction();
+    }
 
-## Deep Link Setup [Required]
+    await requestSubscription({
+      sku: product.productId,
+      ...(appAccountToken ? { applicationUsername: appAccountToken } : {}),
+    });
+  } catch (error) {
+    console.error("Error processing subscription:", error);
+  }
+};
+```
 
-Insert Affiliate requires a Deep Linking platform to create links for your affiliates. Our platform works with **any** deep linking provider. Below are examples for popular providers including Branch.io and AppsFlyer:
-1. **Create a deep link** in your chosen third-party platform and pass it to our dashboard when an affiliate signs up. 
-2. **Handle deep link clicks** in your app by passing the clicked link:
-   ```javascript
-   await setInsertAffiliateIdentifier(referringLink)
-   ```
-3. **Integrate with a Receipt Verification platform** by using the result from `setInsertAffiliateIdentifier` to log in or set your application’s username. Examples below include [**Iaptic**](https://github.com/Insert-Affiliate/InsertAffiliateReactNativeSDK?tab=readme-ov-file#example-with-iaptic) and [**RevenueCat**](https://github.com/Insert-Affiliate/InsertAffiliateReactNativeSDK?tab=readme-ov-file#example-with-revenuecat)
+**App Store Direct setup complete!** Now proceed to [Step 3: Set Up Deep Linking](#3-set-up-deep-linking)
 
+</details>
 
+<details>
+<summary><h4>Option 5: Google Play Direct</h4></summary>
 
-### Deep Linking with Insert Links
+**Step 1: RTDN Setup**
 
-Insert Links by Insert Affiliate supports deferred deep linking into your app. This allows you to track affiliate attribution when end users are referred to your app by clicking on one of your affiliates Insert Links.
+Visit [our docs](https://docs.insertaffiliate.com/direct-google-play-store-purchase-integration) and complete the required Real Time Developer Notifications setup.
 
-#### Initial Setup
+**Step 2: Implementing Purchases**
 
-1. Before you can use Insert Links, you must complete the setup steps in [our docs](https://docs.insertaffiliate.com/insert-links)
+```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';
 
-2. **Initialization** of the Insert Affiliate SDK with Insert Links
+const App = () => {
+  const { storeExpectedStoreTransaction } = useDeepLinkIapProvider();
+  const { currentPurchase } = useIAP();
 
-You must enable *insertLinksEnabled* when [initialising our SDK](https://github.com/Insert-Affiliate/InsertAffiliateReactNativeSDK?tab=readme-ov-file#initialize-with-insert-links)
+  useEffect(() => {
+    if (currentPurchase && Platform.OS === 'android' && currentPurchase.purchaseToken) {
+      storeExpectedStoreTransaction(currentPurchase.purchaseToken);
+    }
+  }, [currentPurchase, storeExpectedStoreTransaction]);
 
-**Handle Insert Links** in your React Native app
+  return <YourAppContent />;
+};
+```
 
-The React Native SDK handles deep links in ALL scenarios:
+**Google Play Direct setup complete!** Now proceed to [Step 3: Set Up Deep Linking](#3-set-up-deep-linking)
 
-- **App Not Running (Cold Start)**: When user clicks a deep link and app is not running, the app launches and processes the URL
-- **App Running (Warm Start)**: When user clicks a deep link while app is already running, processes the URL immediately  
-- **App Backgrounded**: When user clicks a deep link while app is backgrounded, brings app to foreground and processes the URL
-- **Automatic Processing**: Parses Insert Link URLs and sets affiliate identifiers without additional code
+</details>
 
-3. **Platform Specific** Setup
+---
 
-##### iOS Additional Setup (required)
+### 3. Set Up Deep Linking
 
-To enable deep linking and universal links on iOS, you need to configure your app's Info.plist and AppDelegate files.
+**Deep linking lets affiliates share unique links that track users to your app.** Choose **ONE** deep linking provider:
 
-**AppDelegate Setup**
+| Provider | Best For | Complexity | Setup Guide |
+|----------|----------|------------|-------------|
+| [**Insert Links**](#option-1-insert-links-simplest) | Simple setup, no 3rd party | Simple | [View](#option-1-insert-links-simplest) |
+| [**Branch.io**](#option-2-branchio) | Robust attribution, deferred deep linking | Medium | [View](#option-2-branchio) |
+| [**AppsFlyer**](#option-3-appsflyer) | Enterprise analytics, comprehensive attribution | Medium | [View](#option-3-appsflyer) |
 
-Update your `ios/YourApp/AppDelegate.mm` (or `AppDelegate.m`) file:
+<details open>
+<summary><h4>Option 1: Insert Links (Simplest)</h4></summary>
 
-```objc
-#import <React/RCTLinkingManager.h>
+Insert Links is Insert Affiliate's built-in deep linking solution - no third-party SDK required.
 
-// Handle URL opening when app is already running (iOS 9+)
-- (BOOL)application:(UIApplication *)application
-            openURL:(NSURL *)url
-            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
-{
-  return [RCTLinkingManager application:application openURL:url options:options];
-}
+**Prerequisites:**
+- Complete the [Insert Links setup](https://docs.insertaffiliate.com/insert-links) in the Insert Affiliate dashboard
 
-// Handle URL opening (iOS 8 and below - for backward compatibility)
-- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
-  sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
-{
-  return [RCTLinkingManager application:application openURL:url
-                      sourceApplication:sourceApplication annotation:annotation];
-}
+**Step 1: Initialize with Insert Links enabled**
 
-// Handle universal links (iOS 9+)
-- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
- restorationHandler:(void(^)(NSArray * __nullable restorableObjects))restorationHandler
-{
-  return [RCTLinkingManager application:application
-                   continueUserActivity:userActivity
-                     restorationHandler:restorationHandler];
-}
+```javascript
+useEffect(() => {
+  if (!isInitialized) {
+    initialize(
+      "YOUR_COMPANY_CODE",
+      true,   // verboseLogging
+      true,   // insertLinksEnabled
+      false   // insertLinksClipboardEnabled (set true for better attribution, triggers permission)
+    );
+  }
+}, [initialize, isInitialized]);
 ```
 
-4. **Receipt Verification Integration Examples when Using Insert Links**
-
-The SDK provides a callback mechanism that triggers whenever the affiliate identifier changes. This is perfect for integrating with receipt verification platforms.
+**Step 2: Set up the identifier change callback**
 
-##### With RevenueCat
+Choose the example that matches your IAP verification platform:
 
-Set up the callback to automatically update RevenueCat when the affiliate identifier changes:
+**With RevenueCat:**
 
 ```javascript
 import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
@@ -515,29 +486,24 @@ const App = () => {
   const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();
 
   useEffect(() => {
-    // Set up callback to handle affiliate identifier changes
     setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
       if (identifier) {
-        // Update RevenueCat with the affiliate identifier
-        await Purchases.setAttributes({"insert_affiliate": identifier});
+        await Purchases.setAttributes({ "insert_affiliate": identifier });
       }
     });
 
-    // Cleanup on unmount
-    return () => {
-      setInsertAffiliateIdentifierChangeCallback(null);
-    };
+    return () => setInsertAffiliateIdentifierChangeCallback(null);
   }, []);
 
   return <YourAppContent />;
 };
 ```
 
-##### With Apphud
+**With Adapty:**
 
 ```javascript
 import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import Apphud from 'react-native-apphud';
+import { adapty } from 'react-native-adapty';
 
 const App = () => {
   const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();
@@ -545,25 +511,26 @@ const App = () => {
   useEffect(() => {
     setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
       if (identifier) {
-        // Update Apphud with the affiliate identifier
-        await Apphud.setUserProperty("insert_affiliate", identifier, false);
+        await adapty.updateProfile({
+          codableCustomAttributes: {
+            insert_affiliate: identifier,
+          },
+        });
       }
     });
 
-    return () => {
-      setInsertAffiliateIdentifierChangeCallback(null);
-    };
+    return () => setInsertAffiliateIdentifierChangeCallback(null);
   }, []);
 
   return <YourAppContent />;
 };
 ```
 
-##### With Iaptic
+**With Apphud:**
 
 ```javascript
 import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import InAppPurchase from 'react-native-iaptic';
+import Apphud from 'react-native-apphud';
 
 const App = () => {
   const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();
@@ -571,840 +538,392 @@ const App = () => {
   useEffect(() => {
     setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
       if (identifier) {
-        // Initialize Iaptic with the affiliate identifier
-        await InAppPurchase.initialize({
-          iapProducts: iapProductsArray,
-          validatorUrlString: "https://validator.iaptic.com/v3/validate?appName={{ your_iaptic_app_name }}&apiKey={{ your_iaptic_app_key_goes_here }}",
-          applicationUsername: identifier
-        });
+        await Apphud.setUserProperty("insert_affiliate", identifier, false);
       }
     });
 
-    return () => {
-      setInsertAffiliateIdentifierChangeCallback(null);
-    };
+    return () => setInsertAffiliateIdentifierChangeCallback(null);
   }, []);
 
   return <YourAppContent />;
 };
 ```
 
+**With Iaptic:**
 
-### Deep Linking with Branch.io
-To set up deep linking with Branch.io, follow these steps:
-
-1. Create a deep link in Branch and pass it to our dashboard when an affiliate signs up.
-  - Example: [Create Affiliate](https://docs.insertaffiliate.com/create-affiliate).
-2. Modify Your Deep Link Handling in `Index.js`
-  - After setting up your Branch integration, add the following code to your app:
-
-
-#### Example with RevenueCat
 ```javascript
-import {useDeepLinkIapProvider, DeepLinkIapProvider} from 'insert-affiliate-react-native-sdk';
-
-//...
-const DeepLinkHandler = () => {
-    const {setInsertAffiliateIdentifier} = useDeepLinkIapProvider();
-    
-    useEffect(() => {
-      const branchSubscription = branch.subscribe(async ({error, params}) => {
-        if (error) {
-          console.error('Error from Branch:', error);
-          return;
-        }
-
-        if (params['+clicked_branch_link']) {
-          const referringLink = params['~referring_link'];
-          if (referringLink) {
-            try {
-              let insertAffiliateIdentifier = await setInsertAffiliateIdentifier(referringLink);
-
-              if (insertAffiliateIdentifier) {
-                await Purchases.setAttributes({"insert_affiliate" : insertAffiliateIdentifier});
-              }
-
-            } catch (err) {
-              console.error('Error setting affiliate identifier:', err);
-            }
-          }
-        }
-      });
-
-      return () => {
-        branchSubscription();
-      };
-    }, [setInsertAffiliateIdentifier]);
-
-  return <App />;
-};
-
-const RootComponent = () => {
-  return (
-    <DeepLinkIapProvider>
-      <DeepLinkHandler />
-    </DeepLinkIapProvider>
-  );
-};
-
-AppRegistry.registerComponent(appName, () => RootComponent);
-
-//...
-```
+import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
+import InAppPurchase from 'react-native-iaptic';
 
-#### Example with Iaptic / App Store Direct Integration / Google Play Direct Integration
-```javascript
-import branch from 'react-native-branch';
-import {useDeepLinkIapProvider, DeepLinkIapProvider} from 'insert-affiliate-react-native-sdk';
-
-const DeepLinkHandler = () => {
-  const {setInsertAffiliateIdentifier} = useDeepLinkIapProvider();
-  
-  React.useEffect(() => {
-    const branchSubscription = branch.subscribe(async ({error, params}) => {
-      if (error) {
-        console.error('Error from Branch:', error);
-        return;
-      }
+const App = () => {
+  const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();
 
-      if (params['+clicked_branch_link']) {
-        const referringLink = params['~referring_link'];
-        if (referringLink) {
-          try {
-            await setInsertAffiliateIdentifier(referringLink);
-            console.log('Affiliate identifier set successfully.');
-          } catch (err) {
-            console.error('Error setting affiliate identifier:', err);
-          }
-        }
+  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 () => branchSubscription();
-  }, [setInsertAffiliateIdentifier]);
-
-  return <App />;
-};
+    return () => setInsertAffiliateIdentifierChangeCallback(null);
+  }, []);
 
-const RootComponent = () => {
-  return (
-    <DeepLinkIapProvider>
-      <DeepLinkHandler />
-    </DeepLinkIapProvider>
-  );
+  return <YourAppContent />;
 };
 ```
 
-### Deep Linking with AppsFlyer
-To set up deep linking with AppsFlyer, follow these steps:
-
-1. Create a [OneLink](https://support.appsflyer.com/hc/en-us/articles/208874366-Create-a-OneLink-link-for-your-campaigns) in AppsFlyer and pass it to our dashboard when an affiliate signs up.
-  - Example: [Create Affiliate](https://docs.insertaffiliate.com/create-affiliate).
-2. Initialize AppsFlyer SDK and set up deep link handling in your app.
-
-#### Platform Setup
-Complete the deep linking setup for AppsFlyer by following their official documentation:
-- [AppsFlyer Deferred Deep Link Integration Guide](https://dev.appsflyer.com/hc/docs/deeplinkintegrate)
-
-This covers all platform-specific configurations including:
-- iOS: Info.plist configuration, AppDelegate setup, and universal links
-- Android: AndroidManifest.xml intent filters, MainActivity setup, and App Links
-- Testing and troubleshooting for both platforms
-
-#### Example with RevenueCat
+**With App Store / Google Play Direct:**
 
 ```javascript
-import React, { useEffect } from 'react';
-import { Platform } from 'react-native';
-import appsFlyer from 'react-native-appsflyer';
-import { useDeepLinkIapProvider, DeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import Purchases from 'react-native-purchases';
+import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
 
-const DeepLinkHandler = () => {
-  const { setInsertAffiliateIdentifier, isInitialized } = useDeepLinkIapProvider();
+const App = () => {
+  const { setInsertAffiliateIdentifierChangeCallback } = useDeepLinkIapProvider();
 
   useEffect(() => {
-    if (!isInitialized) return;
-
-    // Initialize AppsFlyer
-    const initAppsFlyer = async () => {
-      try {
-        const initOptions = {
-          devKey: 'your-appsflyer-dev-key',
-          isDebug: true,
-          appId: Platform.OS === 'ios' ? 'your-ios-app-id' : 'your-android-package-name',
-        };
-
-        await appsFlyer.initSdk(initOptions);
-      } catch (error) {
-        console.error('AppsFlyer initialization error:', error);
-      }
-    };
-
-    // Handle deep link data
-    const handleDeepLink = async (deepLinkData) => {
-      if (deepLinkData && deepLinkData.data) {
-        let referringLink = deepLinkData.data.link || deepLinkData.data.deep_link_value;
-
-        if (referringLink) {
-          try {
-            let insertAffiliateIdentifier = await setInsertAffiliateIdentifier(referringLink);
-
-            if (insertAffiliateIdentifier) {
-              await Purchases.setAttributes({"insert_affiliate": insertAffiliateIdentifier});
-            }
-          } catch (err) {
-            console.error('Error setting affiliate identifier:', err);
-          }
-        }
+    setInsertAffiliateIdentifierChangeCallback(async (identifier) => {
+      if (identifier) {
+        console.log('Affiliate identifier stored:', identifier);
+        // Identifier is stored automatically for direct store integration
       }
-    };
-
-    // Listen for both deep link types
-    appsFlyer.onDeepLink(handleDeepLink);
-    appsFlyer.onAppOpenAttribution(handleDeepLink);
-    appsFlyer.onInstallConversionData(handleDeepLink);
-
-    initAppsFlyer();
-  }, [setInsertAffiliateIdentifier, isInitialized]);
+    });
 
-  return <App />;
-};
+    return () => setInsertAffiliateIdentifierChangeCallback(null);
+  }, []);
 
-const RootComponent = () => {
-  return (
-    <DeepLinkIapProvider>
-      <DeepLinkHandler />
-    </DeepLinkIapProvider>
-  );
+  return <YourAppContent />;
 };
-
-AppRegistry.registerComponent(appName, () => RootComponent);
 ```
 
-#### Example with Iaptic / App Store Direct Integration / Google Play Direct Integration
-
-```javascript
-import React, { useEffect } from 'react';
-import { Platform } from 'react-native';
-import appsFlyer from 'react-native-appsflyer';
-import { useDeepLinkIapProvider, DeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-
-const DeepLinkHandler = () => {
-  const { setInsertAffiliateIdentifier, isInitialized } = useDeepLinkIapProvider();
-
-  useEffect(() => {
-    if (!isInitialized) return;
-
-    // Initialize AppsFlyer
-    const initAppsFlyer = async () => {
-      try {
-        const initOptions = {
-          devKey: 'your-appsflyer-dev-key',
-          isDebug: true,
-          appId: Platform.OS === 'ios' ? 'your-ios-app-id' : 'your-android-package-name',
-        };
-
-        await appsFlyer.initSdk(initOptions);
-      } catch (error) {
-        console.error('AppsFlyer initialization error:', error);
-      }
-    };
-
-    // Handle deep link data
-    const handleDeepLink = async (deepLinkData) => {
-      if (deepLinkData && deepLinkData.data) {
-        let referringLink = deepLinkData.data.link || deepLinkData.data.deep_link_value;
-
-        if (referringLink) {
-          try {
-            await setInsertAffiliateIdentifier(referringLink);
-          } catch (err) {
-            console.error('Error setting affiliate identifier:', err);
-          }
-        }
-      }
-    };
+**Step 3: iOS Native Setup (Required)**
 
-    // Listen for both deep link types
-    appsFlyer.onDeepLink(handleDeepLink);
-    appsFlyer.onAppOpenAttribution(handleDeepLink);
-    appsFlyer.onInstallConversionData(handleDeepLink);
+Update your `ios/YourApp/AppDelegate.mm`:
 
-    initAppsFlyer();
-  }, [setInsertAffiliateIdentifier, isInitialized]);
+```objc
+#import <React/RCTLinkingManager.h>
 
-  return <App />;
-};
+- (BOOL)application:(UIApplication *)application
+            openURL:(NSURL *)url
+            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
+{
+  return [RCTLinkingManager application:application openURL:url options:options];
+}
 
-const RootComponent = () => {
-  return (
-    <DeepLinkIapProvider>
-      <DeepLinkHandler />
-    </DeepLinkIapProvider>
-  );
-};
+- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
+ restorationHandler:(void(^)(NSArray * __nullable restorableObjects))restorationHandler
+{
+  return [RCTLinkingManager application:application
+                   continueUserActivity:userActivity
+                     restorationHandler:restorationHandler];
+}
 ```
 
-## Additional Features
-
-### 1. Event Tracking (Beta)
+**Testing Deep Links:**
 
-The **InsertAffiliateReactNative SDK** now includes a beta feature for event tracking. Use event tracking to log key user actions such as signups, purchases, or referrals. This is useful for:
-- Understanding user behaviour.
-- Measuring the effectiveness of marketing campaigns.
-- Incentivising affiliates for designated actions being taken by the end users, rather than just in app purchases (i.e. pay an affilaite for each signup).
-
-At this stage, we cannot guarantee that this feature is fully resistant to tampering or manipulation.
-
-#### Using `trackEvent`
-
-To track an event, use the `trackEvent` function. Make sure to set an affiliate identifier first; otherwise, event tracking won't work. Here's an example:
+```bash
+# iOS Simulator
+xcrun simctl openurl booted "YOUR_IOS_URL_SCHEME://TEST_SHORT_CODE"
 
-```javascript
-const {
-  referrerLink,
-  subscriptions,
-  iapLoading,
-  validatePurchaseWithIapticAPI,
-  userId,
-  userPurchase,
-  trackEvent, // Required for trackEvent
-} = useDeepLinkIapProvider();
-
-<Button
-  title={'track event'}
-  onPress={() => {
-    trackEvent('event_name')
-      .then(() => console.log('Event tracked successfully!'))
-  }}
-/>
+# Android Emulator
+adb shell am start -W -a android.intent.action.VIEW -d "YOUR_ANDROID_URL_SCHEME://TEST_SHORT_CODE"
 ```
 
-### 2. Discounts for Users → Offer Codes / Dynamic Product IDs
+**Insert Links setup complete!** Skip to [Verify Your Integration](#-verify-your-integration)
 
-The SDK allows you to apply dynamic modifiers to in-app purchases based on whether the app was installed via an affiliate. These modifiers can be used to swap the default product ID for a discounted or trial-based one - similar to applying an offer code.
+</details>
 
-#### How It Works
+<details>
+<summary><h4>Option 2: Branch.io</h4></summary>
 
-When a user clicks an affiliate link or enters a short code linked to an offer (set up in the **Insert Affiliate Dashboard**), the SDK auto-populates the `OfferCode` field with a relevant modifier (e.g., `_oneWeekFree`). You can append this to your base product ID to dynamically display the correct subscription.
+Branch.io provides robust attribution and deferred deep linking capabilities.
 
-#### Basic Usage
+**Key Integration Steps:**
+1. Install and configure [Branch SDK for React Native](https://help.branch.io/developers-hub/docs/react-native)
+2. Subscribe to Branch deep link events
+3. Extract `~referring_link` from Branch callback
+4. Pass to Insert Affiliate SDK using `setInsertAffiliateIdentifier()`
 
-##### 1. Automatic Offer Code Fetching
-If an affiliate short code is stored, the SDK automatically fetches and saves the associated offer code modifier.
+**[View complete Branch.io integration guide](docs/deep-linking-branch.md)**
 
-##### 2. Access the Offer Code Modifier
-The offer code modifier is available through the context:
+Includes full examples for:
+- RevenueCat integration
+- Adapty integration
+- Apphud integration
+- Iaptic integration
+- App Store / Google Play Direct integration
 
-```javascript
-const { OfferCode } = useDeepLinkIapProvider();
-```
+**After completing Branch setup**, skip to [Verify Your Integration](#-verify-your-integration)
 
-##### Setup Requirements
+</details>
 
-#### Insert Affiliate Setup Instructions
+<details>
+<summary><h4>Option 3: AppsFlyer</h4></summary>
 
-1. Go to your Insert Affiliate dashboard at [app.insertaffiliate.com/affiliates](https://app.insertaffiliate.com/affiliates)
-2. Select the affiliate you want to configure
-3. Click "View" to access the affiliate's settings
-4. Assign an iOS IAP Modifier to the affiliate (e.g., `_oneWeekFree`, `_threeMonthsFree`)
-5. Assign an Android IAP Modifier to the affiliate (e.g., `-oneweekfree`, `-threemonthsfree`)
-5. Save the settings
+AppsFlyer provides enterprise-grade analytics and comprehensive attribution.
 
-Once configured, when users click that affiliate's links or enter their short codes, your app will automatically receive the modifier and can load the appropriate discounted product.
+**Key Integration Steps:**
+1. Install and configure [AppsFlyer SDK for React Native](https://dev.appsflyer.com/hc/docs/react-native-plugin)
+2. Create AppsFlyer OneLink in dashboard
+3. Listen for `onDeepLink`, `onAppOpenAttribution`, and `onInstallConversionData` callbacks
+4. Pass to Insert Affiliate SDK using `setInsertAffiliateIdentifier()`
 
-#### App Store Connect Configuration
-1. Create both a base and a promotional product:
-   - Base product: `oneMonthSubscription`
-   - Promo product: `oneMonthSubscription_oneWeekFree`
-2. Ensure **both** products are approved and available for sale.
+**[View complete AppsFlyer integration guide](docs/deep-linking-appsflyer.md)**
 
-#### Google Play Console Configuration
-There are multiple ways you can configure your products in Google Play Console:
+Includes full examples for:
+- RevenueCat integration
+- Adapty integration
+- Apphud integration
+- Iaptic integration
+- Store Direct integration
+- Deferred deep linking setup
 
-1. **Multiple Products Approach**: Create both a base and a promotional product:
-   - Base product: `oneMonthSubscription`
-   - Promo product: `oneMonthSubscription-oneweekfree`
+**After completing AppsFlyer setup**, proceed to [Verify Your Integration](#-verify-your-integration)
 
-2. **Single Product with Multiple Base Plans**: Create one product with multiple base plans, one with an offer attached
+</details>
 
-3. **Developer Triggered Offers**: Have one base product and apply the offer through developer-triggered offers
+---
 
-4. **Base Product with Intro Offers**: Have one base product that includes an introductory offer
+## ✅ Verify Your Integration
 
-Any of these approaches are suitable and work with the SDK. The important part is that your product naming follows the pattern where the offer code modifier can be appended to identify the promotional version.
+Before going live, verify everything works correctly:
 
-**If using the Multiple Products Approach:**
-- Ensure **both** products are activated and available for purchase.
-- Generate a release to at least **Internal Testing** to make the products available in your current app build
+### Integration Checklist
 
-**Product Naming Pattern:**
-- Follow the pattern: `{baseProductId}{OfferCode}`
-- Example: `oneMonthSubscription` + `_oneWeekFree` = `oneMonthSubscription_oneWeekFree`
+- [ ] **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
 
-#### RevenueCat Dashboard Configuration
+**Test Deep Link (iOS Simulator):**
 
-#### RevenueCat Dashboard Configuration:
-1. Create separate offerings:
-   - Base offering: `premium_monthly`
-   - Modified offering: `premium_monthly_oneWeekFree`
+```bash
+xcrun simctl openurl booted "https://your-deep-link-url/abc123"
+```
 
-2. Add both product IDs under different offerings in RevenueCat.
+**Test Deep Link (Android Emulator):**
 
-3. Ensure modified products follow this naming pattern: {baseProductId}_{cleanOfferCode}. e.g. premium_monthly_oneWeekFree
+```bash
+adb shell am start -W -a android.intent.action.VIEW -d "https://your-deep-link-url/abc123"
+```
 
+**Check Stored Affiliate Identifier:**
 
-### Integration Example
 ```javascript
-import React, { useEffect, useState } from 'react';
-import { View, Button, Text } from 'react-native';
-import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import Purchases from 'react-native-purchases';
-
-const PurchaseHandler = () => {
-  const { OfferCode } = useDeepLinkIapProvider();
-  const [subscriptions, setSubscriptions] = useState([]);
-
-  const fetchSubscriptions = async () => {
-    const offerings = await Purchases.getOfferings();
-    let packagesToUse = [];
-
-    if (OfferCode) {
-    
+const affiliateId = await returnInsertAffiliateIdentifier();
+console.log('Current affiliate ID:', affiliateId);
+```
 
-      // Construct modified product IDs from base products
-      const baseProducts = offerings.current.availablePackages;
+### Common Setup Issues
 
-      for (const basePackage of baseProducts) {
-        const baseProductId = basePackage.product.identifier;
-        const modifiedProductId = `${baseProductId}_${OfferCode}`;
+| 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 |
 
-        // Search all offerings for the modified product
-        const allOfferings = Object.values(offerings.all);
-        let foundModified = false;
+---
 
-        for (const offering of allOfferings) {
-          const modifiedPackage = offering.availablePackages.find(pkg =>
-            pkg.product.identifier === modifiedProductId
-          );
+## 🔧 Advanced Features
 
-          if (modifiedPackage) {
-            packagesToUse.push(modifiedPackage);
-            foundModified = true;
-            break;
-          }
-        }
+<details>
+<summary><h3>Event Tracking (Beta)</h3></summary>
 
-        // Fallback to base product if no modified version
-        if (!foundModified) {
-          packagesToUse.push(basePackage);
-        }
-      }
-    } else {
-      packagesToUse = offerings.current.availablePackages;
-    }
+Track custom events beyond purchases (e.g., signups, referrals) to incentivize affiliates for specific actions.
 
-    setSubscriptions(packagesToUse);
-  };
-
-  const handlePurchase = async (subscriptionPackage) => {
-    try {
-      await Purchases.purchasePackage(subscriptionPackage);
-    } catch (error) {
-      console.error('Purchase failed:', error);
-    }
-  };
-
-  useEffect(() => {
-    fetchSubscriptions();
-  }, [OfferCode]);
+```javascript
+const { trackEvent } = useDeepLinkIapProvider();
 
-  return (
-    <View>
-      {subscriptions.map((pkg) => (
-        <Button
-          key={pkg.identifier}
-          title={`Buy: ${pkg.product.identifier}`}
-          onPress={() => handlePurchase(pkg)}
-        />
-      ))}
-      {OfferCode && (
-        <Text>Special offer applied: {OfferCode}</Text>
-      )}
-    </View>
-  );
-};
+// Track custom event (affiliate identifier must be set first)
+await trackEvent('user_signup');
 ```
----
 
-#### Native Receipt Verification Example
+**Use Cases:**
+- Pay affiliates for signups instead of purchases
+- Track trial starts, content unlocks, or other conversions
 
-For apps using `react-native-iap` directly:
+</details>
 
-```javascript
-import React, { useState, useEffect } from 'react';
-import { View, Text, Button, Platform } from 'react-native';
-import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import { 
-  initConnection, 
-  getSubscriptions, 
-  requestSubscription,
-  useIAP 
-} from 'react-native-iap';
-
-const NativeIAPPurchaseView = () => {
-  const { OfferCode, returnUserAccountTokenAndStoreExpectedTransaction } = useDeepLinkIapProvider();
-  const [availableProducts, setAvailableProducts] = useState([]);
-  const [loading, setLoading] = useState(false);
-  const { currentPurchase, connected } = useIAP();
-  
-  const baseProductIdentifier = "oneMonthSubscription";
-  
-  // Dynamic product identifier that includes offer code
-  const dynamicProductIdentifier = OfferCode 
-    ? `${baseProductIdentifier}${OfferCode}`  // e.g., "oneMonthSubscription_oneWeekFree"
-    : baseProductIdentifier;
-
-  const fetchProducts = async () => {
-    try {
-      setLoading(true);
-      
-      // Try to fetch the dynamic product first
-      let productIds = [dynamicProductIdentifier];
-      
-      // Also include base product as fallback
-      if (OfferCode) {
-        productIds.push(baseProductIdentifier);
-      }
-      
-      const products = await getSubscriptions({ skus: productIds });
-      
-      // Prioritize the dynamic product if it exists
-      let sortedProducts = products;
-      if (OfferCode && products.length > 1) {
-        sortedProducts = products.sort((a, b) => 
-          a.productId === dynamicProductIdentifier ? -1 : 1
-        );
-      }
-      
-      setAvailableProducts(sortedProducts);
-      console.log(`Loaded products for: ${productIds.join(', ')}`);
-      
-    } catch (error) {
-      try {
-        // Fallback logic
-        const baseProducts = await getSubscriptions({ skus: [baseProductIdentifier] });
-        setAvailableProducts(baseProducts);
-      } catch (fallbackError) {
-        console.error('Failed to fetch base products:', fallbackError);
-      }
-    } finally {
-      setLoading(false);
-    }
-  };
+<details>
+<summary><h3>Short Codes</h3></summary>
 
-  const handlePurchase = async (productId) => {
-    // Implement the purchase handling logic as outlined in the remaining SDK integration steps.
-  };
+Short codes are unique, 3-25 character alphanumeric identifiers that affiliates can share (e.g., "SAVE20" in a TikTok video description).
 
-  useEffect(() => {
-    if (connected) {
-      fetchProducts();
-    }
-  }, [connected, OfferCode]);;
-
-  const primaryProduct = availableProducts[0];
+**Validate and Store Short Code:**
 
-  return (
-    <View style={{ padding: 20 }}>
-      <Text style={{ fontSize: 18, fontWeight: 'bold', marginBottom: 10 }}>
-        Premium Subscription
-      </Text>
-      
-      {OfferCode && (
-        <View style={{ backgroundColor: '#e3f2fd', padding: 10, marginBottom: 15, borderRadius: 8 }}>
-          <Text style={{ color: '#1976d2', fontWeight: 'bold' }}>
-            🎉 Special Offer Applied: {OfferCode}
-          </Text>
-        </View>
-      )}
-      
-      {loading ? (
-        <Text>Loading products...</Text>
-      ) : primaryProduct ? (
-        <View>
-          <Text style={{ fontSize: 16, marginBottom: 5 }}>
-            {primaryProduct.title}
-          </Text>
-          <Text style={{ fontSize: 14, color: '#666', marginBottom: 5 }}>
-            Price: {primaryProduct.localizedPrice}
-          </Text>
-          <Text style={{ fontSize: 12, color: '#999', marginBottom: 15 }}>
-            Product ID: {primaryProduct.productId}
-          </Text>
-          
-          <Button
-            title={loading ? "Processing..." : "Subscribe Now"}
-            onPress={() => handlePurchase(primaryProduct.productId)}
-            disabled={loading}
-          />
-          
-          {primaryProduct.productId === dynamicProductIdentifier && OfferCode && (
-            <Text style={{ fontSize: 12, color: '#4caf50', marginTop: 10 }}>
-              ✓ Promotional pricing applied
-            </Text>
-          )}
-        </View>
-      ) : (
-        <View>
-          <Text style={{ color: '#f44336', marginBottom: 10 }}>
-            Product not found: {dynamicProductIdentifier}
-          </Text>
-          <Button
-            title="Retry"
-            onPress={fetchProducts}
-          />
-        </View>
-      )}
-      
-      {availableProducts.length > 1 && (
-        <View style={{ marginTop: 20 }}>
-          <Text style={{ fontSize: 14, fontWeight: 'bold', marginBottom: 10 }}>
-            Other Options:
-          </Text>
-          {availableProducts.slice(1).map((product) => (
-            <Button
-              key={product.productId}
-              title={`${product.title} - ${product.localizedPrice}`}
-              onPress={() => handlePurchase(product.productId)}
-            />
-          ))}
-        </View>
-      )}
-    </View>
-  );
+```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');
+  }
 };
 ```
 
-##### Key Features of Native IAP Integration:
-
-1. **Dynamic Product Loading**: Automatically constructs product IDs using the offer code modifier
-2. **Fallback Strategy**: If the promotional product isn't found, falls back to the base product
-3. **Visual Feedback**: Shows users when promotional pricing is applied
-4. **Error Handling**: Graceful handling when products aren't available
-
+**Get Affiliate Details Without Setting:**
 
-### 3. Short Codes (Beta)
+```javascript
+const { getAffiliateDetails } = useDeepLinkIapProvider();
 
-#### What are Short Codes?
+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);
+}
+```
 
-Short codes are unique identifiers that affiliates can use to promote products or subscriptions. These codes are ideal for influencers or partners, making them easier to share than long URLs.
+Learn more: [Short Codes Documentation](https://docs.insertaffiliate.com/short-codes)
 
-**Example Use Case**: An influencer promotes a subscription with the short code "JOIN12345" within their TikTok video's description. When users enter this code within your app during sign-up or before purchase, the app tracks the subscription back to the influencer for commission payouts.
+</details>
 
-For more information, visit the [Insert Affiliate Short Codes Documentation](https://docs.insertaffiliate.com/short-codes).
+<details>
+<summary><h3>Dynamic Offer Codes / Discounts</h3></summary>
 
-#### Setting a Short Code
+Automatically apply discounts or trials when users come from specific affiliates.
 
-Use the `setShortCode` method to associate a short code with an affiliate. This is ideal for scenarios where users enter the code via an input field, pop-up, or similar UI element.
+**How It Works:**
+1. Configure an offer code modifier in your [Insert Affiliate dashboard](https://app.insertaffiliate.com/affiliates) (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
 
-Short codes must meet the following criteria:
-- Between **3-25 characters long**.
-- Contain only **letters, numbers, and underscores** (alphanumeric characters and underscores).
-- Replace {{ user_entered_short_code }} with the short code the user enters through your chosen input method, i.e. an input field / pop up element
+**Quick Example:**
 
-**Return Value**: `setShortCode` returns a `Promise<boolean>`:
-- Returns `true` if the short code exists and was successfully validated and stored
-- Returns `false` if the short code does not exist or validation failed
+```javascript
+const { OfferCode } = useDeepLinkIapProvider();
 
-This allows you to provide immediate feedback to users about whether their entered code is valid.
+const baseProductId = "oneMonthSubscription";
+const dynamicProductId = OfferCode
+  ? `${baseProductId}${OfferCode}`  // e.g., "oneMonthSubscription_oneWeekFree"
+  : baseProductId;
 
-```javascript
-  import {
-    DeepLinkIapProvider,
-  } from 'insert-affiliate-react-native-sdk';
-
-  const {
-    setShortCode,
-  } = useDeepLinkIapProvider();
-
-  // Basic usage (without validation feedback)
-  <Button
-    title={'Set Short Code'}
-    onPress={() => setShortCode('JOIN_123')}
-  />
-
-  // Recommended usage with validation feedback
-  <Button
-    title={'Set Short Code'}
-    onPress={async () => {
-      const isValid = await setShortCode('JOIN_123');
-      if (isValid) {
-        // Show success message to user
-        Alert.alert('Success', 'Affiliate code applied successfully!');
-      } else {
-        // Show error message to user
-        Alert.alert('Error', 'Invalid affiliate code. Please check and try again.');
-      }
-    }}
-  />
+// Use dynamicProductId when fetching/purchasing products
 ```
 
-**Important**: The SDK will automatically validate the short code with the Insert Affiliate backend before storing it. Only valid short codes that exist in your company's affiliate list will be stored. Invalid codes will be rejected and not associated with the user.
+**[View complete Dynamic Offer Codes guide](docs/dynamic-offer-codes.md)**
 
-### Attribution Timeout
+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
 
-You can configure how long an affiliate link attribution remains active after being clicked. This allows you to control the attribution window for commissions.
+</details>
 
-#### Basic Usage
+<details>
+<summary><h3>Attribution Timeout Control</h3></summary>
 
-When initializing the SDK, you can specify the attribution timeout in seconds:
+Control how long affiliate attribution remains active after a user clicks a link.
 
-```javascript
-const Child = () => {
-  const { initialize, isInitialized } = useDeepLinkIapProvider();
+**Set Timeout During Initialization:**
 
-  useEffect(() => {
-    if (!isInitialized) {
-      // Set attribution timeout to 7 days (7 * 24 * 60 * 60 = 604800 seconds)
-      initialize(
-        "{{ your-company-code }}", 
-        false, // verbose logging
-        false, // insert links enabled
-        false, // insert links clipboard enabled  
-        604800 // attribution timeout in seconds
-      );
-    }
-  }, [initialize, isInitialized]);
-}
+```javascript
+// 7-day attribution window (604800 seconds)
+initialize(
+  "YOUR_COMPANY_CODE",
+  false,  // verboseLogging
+  false,  // insertLinksEnabled
+  false,  // insertLinksClipboardEnabled
+  604800  // affiliateAttributionActiveTime
+);
 ```
 
-**When to use `affiliateAttributionActiveTime`:**
-- Set to a number in seconds to define how long affiliate attributions remain active
-- Set to `null` or omit to disable attribution timeout (attribution never expires)
-- Common values: 86400 (1 day), 604800 (7 days), 2592000 (30 days)
-
-#### Common Timeout Values
+**Check Attribution Validity:**
 
 ```javascript
-// 1 day
-initialize("your-company-code", false, false, false, 86400);
+const { isAffiliateAttributionValid, getAffiliateStoredDate } = useDeepLinkIapProvider();
 
-// 7 days (default for many platforms)
-initialize("your-company-code", false, false, false, 604800);
-
-// 30 days
-initialize("your-company-code", false, false, false, 2592000);
-
-// No timeout (attribution never expires)
-initialize("your-company-code", false, false, false); // or pass null/undefined
+const isValid = await isAffiliateAttributionValid();
+const storedDate = await getAffiliateStoredDate();
 ```
 
-#### Advanced Usage
+**Common Timeout Values:**
+- 1 day: `86400`
+- 7 days: `604800` (recommended)
+- 30 days: `2592000`
+- No timeout: omit parameter (default)
 
-The SDK provides methods to work with attribution timeouts:
+**Bypass Timeout Check:**
 
 ```javascript
-const {
-  returnInsertAffiliateIdentifier,
-  isAffiliateAttributionValid,
-  getAffiliateStoredDate
-} = useDeepLinkIapProvider();
-
-// Get affiliate identifier (respects timeout)
-const identifier = await returnInsertAffiliateIdentifier();
-
-// Get affiliate identifier ignoring timeout
+// Get identifier even if attribution has expired
 const rawIdentifier = await returnInsertAffiliateIdentifier(true);
+```
 
-// Check if attribution is still valid
-const isValid = await isAffiliateAttributionValid();
+</details>
 
-// Get the date when affiliate was first stored
-const storedDate = await getAffiliateStoredDate();
-```
+---
 
-#### How It Works
+## 🔍 Troubleshooting
 
-1. **Attribution Storage**: When an affiliate link is clicked and processed, the SDK stores both the affiliate identifier and the current timestamp
-2. **Timeout Check**: When `returnInsertAffiliateIdentifier()` is called, the SDK checks if the stored attribution is still within the timeout window
-3. **Expired Attribution**: If the attribution has expired, the method returns `null` instead of the affiliate identifier
-4. **Bypass Option**: You can bypass the timeout check by passing `true` to `returnInsertAffiliateIdentifier(true)`
+### Initialization Issues
 
-This ensures that affiliates are only credited for purchases made within the specified attribution window, providing fair and accurate commission tracking.
+**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
 
-### Getting Affiliate Details
+### Deep Linking Issues
 
-You can retrieve detailed information about an affiliate by their short code or deep link using the `getAffiliateDetails` method. This is useful for displaying affiliate information to users or showing personalized content based on the referrer.
+**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
 
-#### Method Signature
+**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"
+  ```
 
-```typescript
-getAffiliateDetails(affiliateCode: string): Promise<AffiliateDetails>
+### Purchase Tracking Issues
 
-type AffiliateDetails = {
-  affiliateName: string;
-  affiliateShortCode: string;
-  deeplinkurl: string;
-} | null;
-```
+**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
 
-#### Usage Example
+### Verbose Logging
 
-```javascript
-import { useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-import type { AffiliateDetails } from 'insert-affiliate-react-native-sdk';
+Enable detailed logs during development to diagnose issues:
 
-const MyComponent = () => {
-  const { getAffiliateDetails } = useDeepLinkIapProvider();
+```javascript
+initialize("YOUR_COMPANY_CODE", true);  // second parameter enables verbose logging
+```
 
-  const handleGetAffiliateInfo = async (code: string) => {
-    const details = await getAffiliateDetails(code);
+**Important:** Disable verbose logging in production builds.
 
-    if (details) {
-      console.log('Affiliate Name:', details.affiliateName);
-      console.log('Short Code:', details.affiliateShortCode);
-      console.log('Deep Link:', details.deeplinkurl);
+### Getting Help
 
-      // Example: Show affiliate name in UI
-      Alert.alert(
-        'Affiliate Found',
-        `This code belongs to ${details.affiliateName}`
-      );
-    } else {
-      console.log('Affiliate not found');
-      Alert.alert('Error', 'Invalid affiliate code');
-    }
-  };
+- [Documentation](https://docs.insertaffiliate.com)
+- [Dashboard Support](https://app.insertaffiliate.com/help)
+- [Report Issues](https://github.com/Insert-Affiliate/InsertAffiliateReactNativeSDK/issues)
 
-  return (
-    <View>
-      <Button
-        title="Get Affiliate Info"
-        onPress={() => handleGetAffiliateInfo('JOIN_123')}
-      />
-    </View>
-  );
-};
-```
+---
 
-#### Return Value
+## 📚 Support
 
-- Returns an object with affiliate details if the code exists:
-  - `affiliateName`: The name of the affiliate
-  - `affiliateShortCode`: The affiliate's short code
-  - `deeplinkurl`: The affiliate's deep link URL
-- Returns `null` if:
-  - The affiliate code doesn't exist
-  - The company code is not initialized
-  - There's a network error or API issue
+- **Documentation**: [docs.insertaffiliate.com](https://docs.insertaffiliate.com)
+- **Dashboard Support**: [app.insertaffiliate.com/help](https://app.insertaffiliate.com/help)
+- **Issues**: [GitHub Issues](https://github.com/Insert-Affiliate/InsertAffiliateReactNativeSDK/issues)
+- **Company Code**: [Get yours from Settings](https://app.insertaffiliate.com/settings)
 
-#### Important Notes
+---
 
-- This method does **not** store or set the affiliate identifier - it only retrieves information
-- Use `setShortCode()` to actually associate an affiliate with a user
-- The method automatically strips UUIDs from codes (e.g., "ABC123-uuid" becomes "ABC123")
-- Works with both short codes and deep link URLs
+**Need help getting started?** Check out our [quickstart guide](https://docs.insertaffiliate.com) or [contact support](https://app.insertaffiliate.com/help).