insert-affiliate-js-sdk 1.0.2 → 1.2.0

package/docs/deep-linking-web.md

@@ -0,0 +1,199 @@
+# Deep Linking for Web Payments
+
+This guide covers how to configure deep links from Branch.io, AppsFlyer, or Insert Links to correctly pass affiliate parameters to your web checkout.
+
+## Overview
+
+When using web-based payments (Stripe), your deep linking provider needs to redirect users to your web checkout page with the `insertAffiliate` parameter. The Insert Affiliate SDK will automatically detect this parameter and attribute the payment to the correct affiliate.
+
+## Insert Links (Automatic)
+
+If you're using [Insert Links](https://docs.insertaffiliate.com/insert-links) (Insert Affiliate's built-in deep linking solution), no additional configuration is needed for web payments.
+
+Insert Links automatically:
+1. Adds the `insertAffiliate` parameter to URLs
+2. Detects and processes attribution in your web app
+3. Tracks the payment to the correct affiliate
+
+Just initialize the SDK and you're done:
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+await InsertAffiliate.initialize('your_company_code');
+// Affiliate parameters are automatically detected from the URL
+```
+
+Learn more: [Insert Links Documentation](https://docs.insertaffiliate.com/insert-links)
+
+## Branch.io Web Redirect Setup
+
+Use these steps if you're using [Branch.io](https://docs.insertaffiliate.com/branch) Quick Links to send users to your web-hosted payment page.
+
+### Creating a Branch.io Quick Link for Web Checkout
+
+1. **Create a new Quick Link** in your Branch.io dashboard
+2. Go to the **Redirects** section
+3. **Select "Web URL"** as the redirect destination
+4. **Configure the URL** to point to your web app:
+   - Enter your web app's URL
+   - Append the parameter: `?insertAffiliate={affiliateShortCode}`
+   - Replace `{affiliateShortCode}` with the actual short code of the affiliate
+
+**Example URL:**
+```
+https://yourwebsite.com/checkout?insertAffiliate=ABC123
+```
+
+Once the user arrives on your site, the Insert Affiliate SDK automatically detects `insertAffiliate` and attributes the payment.
+
+### Branch.io with Capacitor (Hybrid Apps)
+
+For Capacitor apps using the Branch.io plugin:
+
+```javascript
+import { BranchDeepLinks, BranchInitEvent } from 'capacitor-branch-deep-links';
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+// Set up callback to capture affiliate identifier
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
+  if (identifier) {
+    console.log('Affiliate identifier captured:', identifier);
+  }
+});
+
+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) {
+        // This will automatically trigger the callback
+        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);
+  }
+}
+```
+
+## AppsFlyer Web Redirect Setup
+
+Use these steps if you're using [AppsFlyer](https://docs.insertaffiliate.com/appsflyer) OneLinks to send users to your web checkout.
+
+### Creating an AppsFlyer OneLink for Web Checkout
+
+1. **Create a new OneLink** in your AppsFlyer dashboard
+2. Open the link configuration settings
+3. Under **"When link is clicked on desktop web page"**, set the redirect URL
+4. Enter your web app's checkout URL
+5. Append the parameter: `?insertAffiliate={affiliateShortCode}`
+   - Replace `{affiliateShortCode}` with the actual short code of the affiliate
+
+**Example URL:**
+```
+https://yourwebsite.com/checkout?insertAffiliate=ABC123
+```
+
+The Insert Affiliate SDK will automatically detect the parameter and attribute the resulting payment.
+
+## How the SDK Detects Parameters
+
+When your web app loads, the Insert Affiliate SDK automatically:
+
+1. Checks the URL for `insertAffiliate` parameter
+2. Validates the affiliate code with the Insert Affiliate API
+3. Stores the affiliate identifier for later use
+4. Triggers any registered callbacks
+
+**Automatic URL Detection:**
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+// Initialize the SDK - it automatically checks URL parameters
+await InsertAffiliate.initialize('your_company_code');
+
+// The affiliate identifier is now available
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
+console.log('Detected affiliate:', affiliateId);
+```
+
+## Using the Change Callback
+
+For dynamic updates when an affiliate link is clicked:
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+// Set up callback before initialization
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
+  if (identifier) {
+    console.log('Affiliate identifier changed:', identifier);
+
+    // Update UI
+    const banner = document.getElementById('affiliate-banner');
+    if (banner) {
+      banner.textContent = 'You used a special affiliate link!';
+      banner.style.display = 'block';
+    }
+
+    // Track in analytics
+    analytics.track('affiliate_link_clicked', { identifier });
+  }
+});
+
+await InsertAffiliate.initialize('your_company_code');
+```
+
+## URL Parameter Reference
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `insertAffiliate` | The affiliate's short code | `?insertAffiliate=ABC123` |
+
+## Testing
+
+Test your deep link setup by visiting your web app with the affiliate parameter:
+
+```
+https://yourwebsite.com/checkout?insertAffiliate=TEST123
+```
+
+Then check the console for:
+```
+[Insert Affiliate] Affiliate identifier set: TEST123
+```
+
+## Troubleshooting
+
+**Problem:** Affiliate parameter not detected
+- **Solution:** Ensure the SDK is initialized before the URL parameters are processed
+- Check that the parameter name is exactly `insertAffiliate` (case-sensitive)
+
+**Problem:** Deep link opens app instead of web checkout
+- **Solution:** Configure your deep linking provider to redirect to web URL for web-only flows
+- Check the "Desktop redirect" settings in Branch.io or AppsFlyer
+
+**Problem:** Parameter lost after page navigation
+- **Solution:** The SDK stores the affiliate identifier in local storage, so it persists across pages
+- Verify local storage is not being cleared
+
+## Next Steps
+
+- Configure your deep linking provider to pass `insertAffiliate` parameter
+- Test with a sample affiliate short code
+- Integrate with your payment flow (see [Stripe Integration Guide](./stripe-integration.md))
+
+[Back to Main README](../README.md)

package/docs/stripe-integration.md

@@ -0,0 +1,237 @@
+# Stripe Integration Guide
+
+This guide covers all Stripe-based payment integrations for affiliate tracking with Insert Affiliate.
+
+## Prerequisites
+
+- Insert Affiliate SDK initialized in your web application
+- Stripe account connected to Insert Affiliate (see [Connect Stripe Account](#1-connect-your-stripe-account) below)
+
+## 1. Connect Your Stripe Account
+
+Before integrating the SDK code, you must connect your Stripe account to Insert Affiliate:
+
+1. Go to your [Insert Affiliate dashboard settings](https://app.insertaffiliate.com/settings)
+2. Navigate to the payment verification settings
+3. Select **Stripe** as your verification method
+4. Click **Connect with Stripe** to authorize the connection via Stripe Connect
+5. Once connected, Insert Affiliate will automatically receive your Stripe events
+
+## 2. Direct Stripe Checkout Integration
+
+For web-based subscriptions and payments using Stripe Checkout directly.
+
+### Frontend Code
+
+Retrieve the affiliate identifier and company ID before creating a checkout session:
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier();
+const companyId = await InsertAffiliate.returnCompanyId();
+
+const response = await fetch('https://your-backend.com/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',
+  }),
+});
+
+const { sessionId } = await response.json();
+// Redirect to Stripe Checkout
+```
+
+### Backend Code (Node.js)
+
+Store both the affiliate identifier and company ID in Stripe metadata:
+
+```javascript
+const stripe = require('stripe')('sk_test_xxxxx');
+
+app.post('/create-checkout-session', async (req, res) => {
+  const { priceId, insertAffiliate, insertAffiliateCompanyId, successUrl, cancelUrl } = req.body;
+
+  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,
+  });
+
+  res.json({ sessionId: session.id });
+});
+```
+
+**Required Metadata Fields:**
+- `insertAffiliate`: The affiliate's short code
+- `insertAffiliateCompanyId`: Your Insert Affiliate company ID
+
+Both fields are required for proper affiliate attribution and commission tracking.
+
+## 3. Stripe Billing with RevenueCat
+
+If you're using RevenueCat's [Stripe Billing](https://www.revenuecat.com/docs/web/integrations/stripe), you can track affiliate conversions through Insert Affiliate while using RevenueCat for subscription management.
+
+**Prerequisites:**
+- You must host your own web checkout page where Stripe Checkout is embedded
+- Follow RevenueCat's [Stripe integration guide](https://www.revenuecat.com/docs/web/integrations/stripe)
+
+**Integration:**
+
+Follow the same steps as [Direct Stripe Checkout Integration](#2-direct-stripe-checkout-integration) above. Since you've connected your Stripe account via Stripe Connect, Insert Affiliate will automatically receive all Stripe events. RevenueCat handles subscription management, while Insert Affiliate handles affiliate attribution through the Stripe metadata.
+
+## 4. RevenueCat Web Billing Integration
+
+If you're using [RevenueCat's Web SDK with Web Billing](https://www.revenuecat.com/docs/web/web-billing/overview), pass UTM parameters as purchase metadata.
+
+**Prerequisites:**
+- RevenueCat Web SDK installed and configured
+- RevenueCat Web Billing set up with Stripe
+- Insert Affiliate SDK initialized on your page
+- Stripe account connected via Stripe Connect
+
+### Implementation
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+import { Purchases } from '@revenuecat/purchases-js';
+
+// Initialize both SDKs
+await InsertAffiliate.initialize('your_company_code');
+const purchases = Purchases.configure('your_revenuecat_web_api_key');
+
+// Get affiliate information
+const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier(true);
+const companyId = await InsertAffiliate.returnCompanyId();
+
+// Prepare metadata with UTM parameters
+const metadata: Record<string, string> = {};
+
+if (affiliateId && affiliateId !== 'none') {
+  metadata.utm_source = 'insertAffiliate';
+  metadata.utm_medium = companyId || 'none';
+  metadata.utm_campaign = affiliateId;
+}
+
+// Get offerings and make purchase
+const offerings = await purchases.getOfferings();
+const selectedPackage = offerings.current?.availablePackages[0];
+
+if (selectedPackage) {
+  const { customerInfo } = await purchases.purchase({
+    rcPackage: selectedPackage,
+    metadata: metadata,
+  });
+  console.log('Purchase successful!');
+}
+```
+
+**UTM Parameter Mapping:**
+| Parameter | Value | Purpose |
+|-----------|-------|---------|
+| `utm_source` | `'insertAffiliate'` | Identifies Insert Affiliate conversions |
+| `utm_medium` | Your company ID | Links to your Insert Affiliate account |
+| `utm_campaign` | Affiliate identifier | Credits the specific affiliate |
+
+## 5. RevenueCat Web Purchase Links
+
+If you're using [RevenueCat Web Purchase Links](https://www.revenuecat.com/docs/web/web-billing/web-purchase-links) for online campaigns, append UTM parameters to the links.
+
+### URL Format
+
+Base URL:
+```
+https://pay.rev.cat/sandbox/viqxbcoudyfaeaae/
+```
+
+With affiliate parameters:
+```
+https://pay.rev.cat/sandbox/viqxbcoudyfaeaae/?utm_source=insertAffiliate&utm_medium={companyId}&utm_campaign={affiliateShortCode}
+```
+
+### Full Example
+
+```
+https://pay.rev.cat/sandbox/viqxbcoudyfaeaxa/?utm_source=insertAffiliate&utm_medium=12345&utm_campaign=AFF123
+```
+
+Where:
+- `utm_source=insertAffiliate` - Identifies this as an Insert Affiliate conversion
+- `utm_medium=12345` - Your Insert Affiliate company ID
+- `utm_campaign=AFF123` - The affiliate's short code
+
+The Insert Affiliate SDK automatically processes the UTM parameters when users open these URLs and attributes the resulting purchase to the correct affiliate.
+
+## Using the Callback for Automatic Integration
+
+The SDK provides a callback that fires whenever the affiliate identifier changes, making it easy to automatically update your checkout flow:
+
+```javascript
+import { InsertAffiliate } from 'insert-affiliate-js-sdk';
+
+let currentAffiliateId = null;
+
+InsertAffiliate.setInsertAffiliateIdentifierChangeCallback((identifier) => {
+  if (identifier) {
+    console.log('Affiliate identifier changed:', identifier);
+    currentAffiliateId = identifier;
+  }
+});
+
+// Later, when creating a Stripe checkout session
+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: currentAffiliateId,
+    insertAffiliateCompanyId: companyId,
+    successUrl: window.location.origin + '/success',
+    cancelUrl: window.location.origin + '/canceled',
+  }),
+});
+```
+
+## Troubleshooting
+
+**Problem:** Affiliate not credited for purchase
+- **Solution:** Verify both `insertAffiliate` and `insertAffiliateCompanyId` are included in Stripe metadata
+- Check that your Stripe account is connected via Stripe Connect in the Insert Affiliate dashboard
+
+**Problem:** Metadata not appearing in Stripe
+- **Solution:** Ensure metadata is passed to both `metadata` and `subscription_data.metadata` in the checkout session
+
+**Problem:** UTM parameters not being captured
+- **Solution:** Initialize the Insert Affiliate SDK before users interact with purchase flows
+- Verify the SDK is processing URL parameters on page load
+
+## Next Steps
+
+- Test with a test affiliate link to verify attribution
+- Make a test purchase to confirm tracking works end-to-end
+- Monitor conversions in your Insert Affiliate dashboard
+
+[Back to Main README](../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insert-affiliate-js-sdk",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",