insert-affiliate-js-sdk 1.0.2 → 1.2.0

package/README.md

@@ -1,208 +1,498 @@
 # Insert Affiliate JavaScript SDK
 
-## Overview
+![Version](https://img.shields.io/badge/version-1.0.0-brightgreen) ![Platform](https://img.shields.io/badge/platform-Web%20%7C%20Capacitor-blue) ![License](https://img.shields.io/badge/license-MIT-lightgrey)
 
-The **Insert Affiliate JavaScript SDK** brings affiliate tracking to web and hybrid applications, providing seamless integration with the [Insert Affiliate platform](https://insertaffiliate.com). It is fully compatible with Capacitor, making it a great choice for modern cross-platform apps that require affiliate attribution and purchase tracking support.
+The official JavaScript SDK for [Insert Affiliate](https://insertaffiliate.com) - track affiliate-driven purchases on web and hybrid applications.
 
-This SDK is ideal for developers who want to integrate affiliate marketing into their app's monetisation strategy and track purchases via partners like RevenueCat.
+**What does this SDK do?** It connects your web or Capacitor app to Insert Affiliate's platform, enabling you to track which affiliates drive subscriptions and automatically pay them commissions when users make purchases.
 
-### Features
+## Table of Contents
 
-- **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 or short codes.
-- **Short Code Support (Beta)**: Allow users to enter affiliate short codes for tracking.
+- [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 Payment Verification](#2-configure-payment-verification)
+  - [3. Set Up Deep Linking](#3-set-up-deep-linking)
+- [Verify Your Integration](#-verify-your-integration)
+- [Advanced Features](#-advanced-features)
+- [API Reference](#-api-reference)
+- [Troubleshooting](#-troubleshooting)
+- [Support](#-support)
 
-### Supported Platforms
-- ✅ Capacitor (iOS / Android) – Fully tested
-- ✅ Web Browsers – Tested in modern desktop and mobile browsers
-- ⚠️ Other JavaScript Environments – May work, but not officially tested
+---
+
+## 🚀 Quick Start (5 Minutes)
 
-## Getting Started
-To get started with the Insert Affiliate JavaScript SDK:
+Get up and running with minimal code to validate the SDK works.
 
-1. [Install the SDK via NPM](#installation)
-2. [Initialise the SDK in your Main Javascript/Typescript File](#basic-usage)
-3. [Set up in-app purchases (Required)](#in-app-purchase-setup-required)
-4. [Set up deep linking (Required)](#deep-link-setup-required)
-5. [Use additional features like short codes and event tracking.](#additional-features)
+### Prerequisites
 
+- **Modern web browser** or **Capacitor 4+**
+- **Company Code** from your [Insert Affiliate dashboard](https://app.insertaffiliate.com/settings)
 
-## Installation
+### Supported Platforms
 
-Install the Insert Affiliate JavaScript SDK and required plugins:
+| Platform | Status |
+|----------|--------|
+| Capacitor (iOS / Android) | ✅ Fully tested |
+| Web Browsers | ✅ Tested in modern browsers |
+| Other JS Environments | ⚠️ May work, not officially tested |
+
+### Installation
 
 ```bash
 npm install insert-affiliate-js-sdk
 ```
 
-Then run
+For Capacitor apps, also run:
 ```bash
 npx cap sync
 ```
 
-## Basic Usage
-### Import the SDKs
+### Your First Integration
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+// Initialize with verbose logging for setup
+await InsertAffiliate.initialize('YOUR_COMPANY_CODE', true);
+```
+
+**Expected Console Output:**
+
+```
+[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.
+
+⚠️ **Disable verbose logging in production** by setting the second parameter to `false`.
+
+---
+
+## ⚙️ Essential Setup
 
-In your ```main.ts``` or ```main.js``` file:
+Complete these three steps to start tracking affiliate-driven purchases.
+
+### 1. Initialize the SDK
+
+Add SDK initialization to your main entry point (`main.ts`, `main.js`, or `App.tsx`):
 
 ```javascript
 import { InsertAffiliate } from 'insert-affiliate-js-sdk';
-await InsertAffiliate.initialize("your_company_code");
 
+await InsertAffiliate.initialize('YOUR_COMPANY_CODE');
+```
+
+<details>
+<summary><strong>Advanced Initialization Options</strong> (click to expand)</summary>
+
+```javascript
+// Enable verbose logging for debugging
+await InsertAffiliate.initialize('YOUR_COMPANY_CODE', true);
 ```
-- 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).
 
-## 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/)
+**Verbose logging shows:**
+- Initialization process and company code validation
+- Deep link processing and short code detection
+- API communication details
+- Storage operations
+
+</details>
+
+---
 
-### Option 1: RevenueCat Integration
+### 2. Configure Payment Verification
 
-#### Code Setup
-1. **Install RevenueCat SDK** - First, complete the set up of the relevant [RevenueCat SDK](https://www.revenuecat.com/docs/getting-started/installation) to set up in-app purchases and subscriptions.
+**Choose the payment method(s) that match your platform:**
 
-2. **Modify Initialisation Code** - Update the file where you initialise your deep linking (e.g., Branch.io) and RevenueCat to include a call to ```InsertAffiliate.returnInsertAffiliateIdentifier()```. This ensures that the Insert Affiliate identifier is passed to RevenueCat every time the app starts or a deep link is clicked.
+| Method | Best For | Setup Guide |
+|--------|----------|-------------|
+| [**RevenueCat**](#option-1-revenuecat) | Mobile IAP (iOS/Android) | [View](#option-1-revenuecat) |
+| [**Stripe**](#option-2-stripe) | Web-based payments | [View](#option-2-stripe) |
+| [**Both**](#hybrid-apps) | Hybrid apps with mobile + web payments | Set up both |
 
-3. **Implementation Example**
+<details open>
+<summary><h4>Option 1: RevenueCat</h4></summary>
+
+For mobile in-app purchases via Capacitor.
+
+**Step 1: Code Setup**
 
 ```javascript
 import { InsertAffiliate } from 'insert-affiliate-js-sdk';
 import { Purchases } from '@revenuecat/purchases-capacitor';
 
 window.addEventListener('DOMContentLoaded', async () => {
-    await Purchases.configure({ apiKey: 'your_revcat_api_key' });
-    
-    const affiliateIdentifier = await InsertAffiliate.returnInsertAffiliateIdentifier();
-    
-    if (affiliateIdentifier) {
-        await Purchases.setAttributes({ insert_affiliate: affiliateIdentifier });
-    }
+  await InsertAffiliate.initialize('YOUR_COMPANY_CODE');
+  await Purchases.configure({ apiKey: 'YOUR_REVENUECAT_API_KEY' });
+
+  const affiliateIdentifier = await InsertAffiliate.returnInsertAffiliateIdentifier();
+
+  if (affiliateIdentifier) {
+    await Purchases.setAttributes({ insert_affiliate: affiliateIdentifier });
+  }
+});
+```
+
+**Step 2: Webhook Setup**
+
+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. Paste the authentication header into RevenueCat's **Authorization header** field
+
+✅ **RevenueCat setup complete!**
+
+</details>
+
+<details>
+<summary><h4>Option 2: Stripe</h4></summary>
+
+For web-based subscriptions and payments.
+
+**Step 1: Connect Stripe Account**
+
+1. Go to your [Insert Affiliate dashboard settings](https://app.insertaffiliate.com/settings)
+2. Select **Stripe** as your verification method
+3. Click **Connect with Stripe** to authorize via Stripe Connect
+
+**Step 2: Pass Affiliate Data to Checkout**
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
+const companyId = await InsertAffiliate.returnCompanyId();
+
+const response = await fetch('/create-checkout-session', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    priceId: 'price_xxxxx',
+    insertAffiliate: affiliateId,
+    insertAffiliateCompanyId: companyId,
+    successUrl: window.location.origin + '/success',
+    cancelUrl: window.location.origin + '/canceled',
+  }),
+});
+```
+
+**Step 3: Store in Stripe Metadata (Backend)**
+
+```javascript
+const session = await stripe.checkout.sessions.create({
+  mode: 'subscription',
+  line_items: [{ price: priceId, quantity: 1 }],
+  metadata: {
+    insertAffiliate: insertAffiliate || '',
+    insertAffiliateCompanyId: insertAffiliateCompanyId || '',
+  },
+  subscription_data: {
+    metadata: {
+      insertAffiliate: insertAffiliate || '',
+      insertAffiliateCompanyId: insertAffiliateCompanyId || '',
+    },
+  },
+  success_url: successUrl,
+  cancel_url: cancelUrl,
 });
 ```
 
-#### Webhook Setup
+📖 **[View complete Stripe integration guide →](docs/stripe-integration.md)**
+
+Includes:
+- Stripe Billing with RevenueCat
+- RevenueCat Web Billing integration
+- RevenueCat Web Purchase Links
+- Callback-based integration
 
-Next, you must setup a webhook to allow us to communicate directly with RevenueCat to track affiliate purchases.
+✅ **Stripe setup complete!**
 
-1. Go to RevenueCat and [create a new webhook](https://www.revenuecat.com/docs/integrations/webhooks)
+</details>
 
-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"
+---
 
-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`
+### 3. Set Up Deep Linking
 
-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
+**Deep linking lets affiliates share unique links that track users to your app/website.**
 
+| Provider | Best For | Complexity |
+|----------|----------|------------|
+| [**Insert Links**](#option-1-insert-links-automatic) | Simplest setup, no 3rd party | Simple |
+| [**Branch.io**](#option-2-branchio) | Robust attribution | Medium |
+| [**AppsFlyer**](#option-3-appsflyer) | Enterprise analytics | Medium |
 
-## Deep Link Setup [Required]
-Insert Affiliate requires a Deep Linking platform to create links for your affiliates. Our platform works with **any** deep linking provider, and you only need to follow these steps:
-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
-   InsertAffiliate.setInsertAffiliateIdentifier(data["~referring_link"]);
-   ```
+<details open>
+<summary><h4>Option 1: Insert Links (Automatic)</h4></summary>
 
-### Deep Linking with Branch.io
-To set up deep linking with Branch.io, follow these steps:
+Insert Links is Insert Affiliate's built-in deep linking - no configuration needed for web.
 
-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
-    - After setting up your Branch integration, add the following code to initialise the Insert Affiliate SDK in your iOS app:
+The SDK automatically:
+1. Detects `insertAffiliate` parameter from URLs
+2. Validates and stores the affiliate identifier
+3. Triggers callbacks when affiliate changes
 
+**That's it!** Just initialize the SDK and affiliate links work automatically.
+
+Learn more: [Insert Links Documentation](https://docs.insertaffiliate.com/insert-links)
+
+</details>
+
+<details>
+<summary><h4>Option 2: Branch.io</h4></summary>
+
+**For web redirects:** Configure your Branch.io Quick Links to redirect to your web URL with the affiliate parameter:
+
+```
+https://yourwebsite.com/checkout?insertAffiliate={affiliateShortCode}
+```
+
+**For Capacitor apps:** Use the Branch.io Capacitor plugin:
 
 ```javascript
-import { BranchDeepLinks, BranchInitEvent } from 'capacitor-branch-deep-links';
+import { BranchDeepLinks } from 'capacitor-branch-deep-links';
 import { InsertAffiliate } from 'insert-affiliate-js-sdk';
 
-let branchInitialised = false;
-
-async function setUpBranchListener() {
-    if (branchInitialised) return;
-    branchInitialised = true;
-    
-    try {
-        await BranchDeepLinks.addListener('init', async (event: BranchInitEvent) => {
-            const clicked = event?.referringParams?.['+clicked_branch_link'];
-            const referringLink = event?.referringParams?.['~referring_link'];
-            
-            if (clicked && referringLink) {
-                await InsertAffiliate.setInsertAffiliateIdentifier(referringLink);
-            }
-        });
-        
-        BranchDeepLinks.addListener('initError', (error: any) => {
-            console.error('Branch init error:', error);
-        });
-    } catch (err) {
-        console.error('Error setting up Branch listener:', err);
-    }
-}
+BranchDeepLinks.addListener('init', async (event) => {
+  const clicked = event?.referringParams?.['+clicked_branch_link'];
+  const referringLink = event?.referringParams?.['~referring_link'];
 
+  if (clicked && referringLink) {
+    await InsertAffiliate.setInsertAffiliateIdentifier(referringLink);
+  }
+});
 ```
 
-## Additional Features
+📖 **[View complete deep linking guide →](docs/deep-linking-web.md)**
+
+</details>
+
+<details>
+<summary><h4>Option 3: AppsFlyer</h4></summary>
+
+Configure your AppsFlyer OneLinks to redirect to your web URL with the affiliate parameter:
+
+```
+https://yourwebsite.com/checkout?insertAffiliate={affiliateShortCode}
+```
 
-### 1. Event Tracking (Beta)
+The SDK automatically detects `insertAffiliate` from the URL and attributes the payment.
 
-Insert Affiliate 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).
+📖 **[View complete deep linking guide →](docs/deep-linking-web.md)**
 
-At this stage, we cannot guarantee that this feature is fully resistant to tampering or manipulation.
+</details>
 
-#### 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:
+## ✅ Verify Your Integration
+
+### Integration Checklist
+
+- [ ] **SDK Initializes**: Check console for `SDK initialized with company code` log
+- [ ] **Affiliate Detected**: Visit your site with `?insertAffiliate=TEST123` and verify it's captured
+- [ ] **Payment Tracked**: Make a test purchase and verify it appears in Insert Affiliate dashboard
+
+### Testing URL Parameters
+
+Visit your app with an affiliate parameter:
+```
+https://yourwebsite.com?insertAffiliate=TEST123
+```
+
+Check the affiliate was captured:
+```javascript
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
+console.log('Detected affiliate:', affiliateId); // Should output: TEST123
+```
+
+### Common Setup Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Company code not set" | Ensure `initialize()` is called before other SDK methods |
+| Affiliate not detected | Check URL parameter is exactly `insertAffiliate` (case-sensitive) |
+| Payment not tracked | Verify Stripe/RevenueCat webhook is configured correctly |
+
+---
+
+## 🔧 Advanced Features
+
+<details>
+<summary><h3>Event Tracking (Beta)</h3></summary>
+
+Track custom events beyond purchases to incentivize affiliates for specific actions.
 
 ```javascript
 import { InsertAffiliate } from 'insert-affiliate-js-sdk';
 
-async function trackSignupEvent() {
-    try {
-        await InsertAffiliate.trackEvent('your_event_name_here');
-    } catch (error) {
-        console.error('❌ Failed to track event:', error);
-    }
+// Track a signup event (affiliate identifier must be set first)
+await InsertAffiliate.trackEvent('user_signup');
+```
+
+**Use Cases:**
+- Pay affiliates for signups instead of purchases
+- Track trial starts or content unlocks
+
+</details>
+
+<details>
+<summary><h3>Short Codes</h3></summary>
+
+Short codes are unique, 3-25 character alphanumeric identifiers that affiliates can share (e.g., "SAVE20" in a TikTok description).
+
+**Validate and Store Short Code:**
+
+```javascript
+const isValid = await InsertAffiliate.setShortCode('SAVE20');
+
+if (isValid) {
+  alert('Affiliate code applied!');
+
+  // Check for associated offer
+  const offerCode = await InsertAffiliate.getOfferCode();
+  if (offerCode) {
+    alert(`You unlocked: ${offerCode}`);
+  }
+} else {
+  alert('Invalid affiliate code');
+}
+```
+
+**Get Affiliate Details Without Setting:**
+
+```javascript
+const details = await InsertAffiliate.getAffiliateDetails('SAVE20');
+
+if (details) {
+  console.log('Affiliate Name:', details.affiliateName);
+  console.log('Short Code:', details.affiliateShortCode);
+  console.log('Deep Link:', details.deeplinkUrl);
 }
 ```
 
-### 2. Short Codes (Beta)
+Learn more: [Short Codes Documentation](https://docs.insertaffiliate.com/short-codes)
 
-### What are Short Codes?
+</details>
 
-Short codes are unique, 3 to 25 character alphanumeric 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.
+<details>
+<summary><h3>Affiliate Change Callback</h3></summary>
 
-**Example Use Case**: An influencer promotes a subscription with the short code "JOIN123456" 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.
+Get notified when the affiliate identifier changes:
 
-For more information, visit the [Insert Affiliate Short Codes Documentation](https://docs.insertaffiliate.com/short-codes).
+```javascript
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
+  if (identifier) {
+    console.log('Affiliate changed:', identifier);
+
+    // Update UI
+    document.getElementById('affiliate-banner').style.display = 'block';
 
-### Setting a Short Code
+    // Track in analytics
+    analytics.track('affiliate_link_clicked', { identifier });
+  }
+});
 
-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.
+// Clear callback when done
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback(null);
+```
 
-Short codes must meet the following criteria:
-- Between **3 and 25 characters long**.
-- Contain only **letters and numbers** (alphanumeric characters).
-- 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
+</details>
 
+---
 
-#### Example Integration
-Below is an example SwiftUI implementation where users can enter a short code, which will be validated and associated with the affiliate's account:
+## 📖 API Reference
+
+### Core Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `initialize(companyCode, verbose?)` | Initialize the SDK | `Promise<void>` |
+| `returnInsertAffiliateIdentifier(ignoreTimeout?)` | Get current affiliate identifier | `Promise<string \| null>` |
+| `returnCompanyId()` | Get company ID | `Promise<string \| null>` |
+| `setInsertAffiliateIdentifier(link)` | Set affiliate from deep link | `Promise<string \| null>` |
+| `setShortCode(code)` | Validate and store short code | `Promise<boolean>` |
+| `getAffiliateDetails(code)` | Get affiliate info without storing | `Promise<AffiliateDetails \| null>` |
+| `trackEvent(eventName)` | Track custom event | `Promise<void>` |
+| `getOfferCode()` | Get offer code modifier | `Promise<string \| null>` |
+| `setInsertAffiliateIdentifierChangeCallback(fn)` | Set change callback | `void` |
+
+<details>
+<summary><strong>Detailed Method Documentation</strong></summary>
+
+#### `returnInsertAffiliateIdentifier(ignoreTimeout?)`
+
+Retrieves the current affiliate identifier.
+
+**Parameters:**
+- `ignoreTimeout` (optional, boolean): Set to `true` to get identifier even if attribution window expired
+
+**Returns:** `Promise<string | null>`
 
 ```javascript
-import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+// Respects attribution window
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
+
+// Ignores attribution window
+const affiliateIdAlways = await InsertAffiliate.returnInsertAffiliateIdentifier(true);
+```
+
+#### `returnCompanyId()`
+
+Retrieves the company ID used during initialization.
+
+**Returns:** `Promise<string | null>`
+
+```javascript
+const companyId = await InsertAffiliate.returnCompanyId();
+```
 
-// Example: user entered this in a form
-const userEnteredCode = 'B3SC6VRRKQ';
+</details>
 
-InsertAffiliate.setShortCode(userEnteredCode);
+---
+
+## 🔍 Troubleshooting
+
+### Initialization Issues
+
+**Error:** "Company code not set"
+- **Solution:** Call `initialize()` before any other SDK methods
+
+### Deep Linking Issues
+
+**Problem:** Affiliate parameter not detected
+- **Solution:** Ensure parameter name is exactly `insertAffiliate` (case-sensitive)
+- Initialize SDK before URL parameters are processed
+
+### Payment Tracking Issues
+
+**Problem:** Purchases not appearing in dashboard
+- **Solution:** Verify webhook configuration in Stripe/RevenueCat
+- Check both `insertAffiliate` and `insertAffiliateCompanyId` are in metadata
+
+### Verbose Logging
+
+Enable detailed logs to diagnose issues:
+
+```javascript
+await InsertAffiliate.initialize('YOUR_COMPANY_CODE', true);
 ```
+
+---
+
+## 📚 Support
+
+- **Documentation**: [docs.insertaffiliate.com](https://docs.insertaffiliate.com)
+- **Stripe Integration Guide**: [docs/stripe-integration.md](docs/stripe-integration.md)
+- **Deep Linking Guide**: [docs/deep-linking-web.md](docs/deep-linking-web.md)
+- **Dashboard**: [app.insertaffiliate.com](https://app.insertaffiliate.com)
+- **Issues**: [GitHub Issues](https://github.com/Insert-Affiliate/insert-affiliate-js-sdk/issues)
+
+---
+
+**Need help?** Check our [documentation](https://docs.insertaffiliate.com) or [contact support](https://app.insertaffiliate.com/help).