insert-affiliate-react-native-sdk 1.1.3 → 1.1.6

package/readme.md

@@ -2,53 +2,70 @@
 
 ## Overview
 
-The **InsertAffiliateReactNative SDK** is designed for React Native applications, providing seamless integration with the [Insert Affiliate platform](https://insertaffiliate.com). For more details and to access the Insert Affiliate dashboard, visit [app.insertaffiliate.com](https://app.insertaffiliate.com).
+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.
 
-## Features
+### Features
 
-- **Unique Device Identification**: Generates and stores a short unique device ID to identify users effectively.
+- **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 validation options using the affiliate identifier.
+- **In-App Purchase (IAP) Initialisation**: Easily reinitialise in-app purchases with the option to validate using an affiliate identifier.
 
 ## Peer Dependencies
 
 Before using this package, ensure you have the following dependencies installed:
 
 - [react-native-iap](https://www.npmjs.com/package/react-native-iap)
-- [react-native-branch](https://www.npmjs.com/package/react-native-branch)
 - [axios](https://www.npmjs.com/package/axios)
 
+## Getting Started
+
+To get started with the InsertAffiliateReactNative SDK:
+
+1. [Install the React Native Package](#installation)
+2. [Initialise the SDK in App.tsx](#basic-usage)
+3. [Set up in-app purchases (Required)](#in-app-purchase-setup-required)
+4. [Set up deep linking (Required)](#deep-link-setup-required)
+
 ## Installation
 
-To integrate the InsertAffiliateReactNative SDK into your project, run:
+To integrate the InsertAffiliateReactNative SDK into your app:
 
+1. Install the NPM package.
 ```bash
 npm install insert-affiliate-react-native-sdk
 ```
 
-## Usage
-### Importing the SDK
-Import the provider from the package:
-
+## Basic Usage
 
-```javascript
-import { DeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-```
+### Initialisation in `App.tsx`
 
-## 1. Integrating the Provider in Your Application (`App.tsx`)
-### Step 1: Wrap Your Application with the Iaptic Provider and Pass Context Properties
+First, wrap your with our provider and call the `initialise` method early in your app's lifecycle:
 
-- 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).
+```javascript
+const Child = () => {
+  const {
+    referrerLink,
+    subscriptions,
+    iapLoading,
+    handleBuySubscription,
+    userId,
+    userPurchase,
+    trackEvent,
+    initialize,
+    isInitialized,
+  } = useDeepLinkIapProvider();
 
-Here's the code with placeholders for you to swap out:
+  useEffect(() => {
+    initialize("{{ your-company-code }}");
+  }, [initialize, isInitialized]);
+  
+  // ...
+  
+}
 
-```javascript
 const App = () => {
   return (
     <DeepLinkIapProvider
-      iapSkus={IAP_SKUS}
       iapticAppId="{{ your_iaptic_app_id }}"
       iapticAppName="{{ your_iaptic_app_name }}"
       iapticPublicKey="{{ your_iaptic_public_key }}">
@@ -57,63 +74,81 @@ const 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).
+
+## 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:
+- [Iaptic](https://www.iaptic.com/account)
+- [RevenueCat](https://www.revenuecat.com/)
 
-## 2. When the User Makes a Purchase, Call Our SDK's "handleBuySubscription"
-Here’s a complete example of how to use the SDK:
+### Option 1: Iaptic Integration
+First, complete the [Iaptic account setup](https://www.iaptic.com/signup) and code integration.
 
-In the code below, please remember to update your IAP_SKUS with the comma separated list of your in app purchase SKU's.
+Then after setting up the in app purchase (IAP) with Iaptic, call Insert Affiliate's handlePurchaseValidation on purchase.
 
 ```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 {
-    referrerLink,
-    subscriptions,
-    iapLoading,
-    handleBuySubscription,
-    userId,
-    userPurchase,
-    isIapticValidated,
-  } = useDeepLinkIapProvider();
-
-  export const IAP_SKUS = Platform.select({
-    android: [''], // Here, put a comma separated list of the In App Purchase SKU's
-    ios: [''], // Here, put a comma separated list of the In App Purchase SKU's
-  }) as string[];
-
-
-  return (
-    <View>
-      {subscriptions.length ? (
-        <Button
-          disabled={iapLoading}
-          title={
-            userPurchase
-              ? `Successfully Purchased`
-              : `Click to Buy (${subscriptions[0].localizedPrice} / ${subscriptions[0].subscriptionPeriodUnitIOS})`
-          }
-          onPress={() => {
-            if (iapLoading) return;
-            if (!userPurchase) handleBuySubscription(subscriptions[0].productId); //
-          }}
-        />
-      ) : null}
-      {iapLoading && <ActivityIndicator size={'small'} color={'black'} />}
-    </View>
-  );
+    const {
+        initialize,
+        isInitialized,
+        handlePurchaseValidation,
+    } = 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) {
+            handlePurchaseValidation(currentPurchase).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("oneMonthSubscriptionTwo")}
+            />
+            {iapLoading && <ActivityIndicator size={"small"} color={"black"} />}
+        </View>
+    );
 };
 
 const App = () => {
   return (
     // Wrapped application code from the previous step...
     <DeepLinkIapProvider
-      iapSkus={IAP_SKUS}
-      iapticAppId="your_iaptic_app_id"
-      iapticAppName="your_iaptic_app_name"
-      iapticPublicKey="your_iaptic_public_key">
+      iapticAppId="{{ your_iaptic_app_id }}"
+      iapticAppName="{{ your_iaptic_app_name }}"
+      iapticPublicKey="{{ your_iaptic_public_key }}">
       <Child />
     </DeepLinkIapProvider>
   );
@@ -121,15 +156,89 @@ const App = () => {
 
 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).
+
+### Option 2: RevenueCat Integration
+<!--#### 1. Code Setup-->
+<!--First, complete the [RevenueCat SDK installation](https://www.revenuecat.com/docs/getting-started/installation/ios). Then modify your `AppDelegate.swift`:-->
+   
+COMING SOON...
+
+## Deep Link Setup [Required]
+
+### Step 1: Add the Deep Linking Platform Dependency
+
+In this example, the deep linking functionality is implemented using [Branch.io](https://dashboard.branch.io/).
+
+Any alternative deep linking platform can be used by passing the referring link to ```InsertAffiliateSwift.setInsertAffiliateIdentifier(referringLink: "{{ link }}")``` as in the below Branch.io example
+
+After setting up your Branch integration, add the following code to your ```index.js```
+
+<!--#### Example with RevenueCat-->
+<!--```swift-->
+<!--import SwiftUI-->
+<!--import BranchSDK-->
+<!--import InAppPurchaseLib-->
+<!--import InsertAffiliateSwift-->
+
+<!--class AppDelegate: UIResponder, UIApplicationDelegate {-->
+<!--  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {-->
+<!--    Branch.getInstance().initSession(launchOptions: launchOptions) { (params, error) in-->
+<!--      if let referringLink = params?["~referring_link"] as? String {-->
+<!--        InsertAffiliateSwift.setInsertAffiliateIdentifier(referringLink: referringLink) { result in-->
+<!--          guard let shortCode = result else {-->
+<!--            return-->
+<!--          }-->
+
+<!--          Purchases.shared.logIn(shortCode) { (customerInfo, created, error) in-->
+<!--            // customerInfo updated for my_app_user_id. If you are having issues, you can investigate here.-->
+<!--          }-->
+<!--      }-->
+<!--    }-->
+<!--    return true-->
+<!--  }-->
+<!--}-->
+<!--```-->
+
+#### Example with Iaptic
+```swift
+import branch from 'react-native-branch';
+import { DeepLinkIapProvider, useDeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
 
+branch.subscribe(async ({ error, params }) => {
+    if (error) {
+      console.error('Error from Branch: ' + error);
+      return;
+    }
+ 
+    if (params['+clicked_branch_link']) {
+        if (params["~referring_link"]) {
+            setInsertAffiliateIdentifier(params["~referring_link"], (shortLink) => {
+                console.log("Insert Affiliate - setInsertAffiliateIdentifier: ", params["~referring_link"], " - Stored shortLink ", shortLink);
+            });
+        }
+    }
+});
+
+```
 
-## Event Tracking (Beta)
+## Additional Features
 
-The **InsertAffiliateReactNative SDK** now includes a beta feature for event tracking. You can use this feature to track specific user actions within your app. However, please note that this feature is currently in beta, and while we aim to secure its functionality, we cannot guarantee that it is fully resistant to tampering or manipulation at this stage.
+### 1. Event Tracking (Beta)
 
-### Using `trackEvent`
+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).
 
-To track an event, then use the `trackEvent` function. Make sure to open an Affiliate's deep link before tracking the event; otherwise, event tracking won’t work. Here’s an example:
+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:
 
 ```javascript
 const {
@@ -139,7 +248,6 @@ const {
   handleBuySubscription,
   userId,
   userPurchase,
-  isIapticValidated,
   trackEvent, // Required for trackEvent
 } = useDeepLinkIapProvider();
 
@@ -152,15 +260,36 @@ const {
 />
 ```
 
-### Example Usage
-Set the Affiliate Identifier (required for tracking):
+### 2. Short Codes (Beta)
 
-```swift
-InsertAffiliateSwift.setInsertAffiliateIdentifier(referringLink: "your_affiliate_link")
-```
+#### What are Short Codes?
 
-#### Track an Event:
+Short codes are unique, 10-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.
 
-```swift
-InsertAffiliateSwift.trackEvent(eventName: "user_signup")
+**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.
+
+For more information, visit the [Insert Affiliate Short Codes Documentation](https://docs.insertaffiliate.com/short-codes).
+
+#### Setting a Short Code
+
+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.
+
+Short codes must meet the following criteria:
+- Exactly **10 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
+
+```javascript
+  import {
+    DeepLinkIapProvider,
+  } from 'insert-affiliate-react-native-sdk';
+
+  const {
+    setShortCode,
+  } = useDeepLinkIapProvider();
+
+  <Button
+    title={'Set Short Code'}
+    onPress={() => setShortCode('JOIN123456')}
+  />
 ```