insert-affiliate-react-native-sdk 1.1.2 → 1.1.5

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
 
+### Initialisation in `App.tsx`
 
-```javascript
-import { DeepLinkIapProvider } from 'insert-affiliate-react-native-sdk';
-```
-
-## 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).
 
-## 2. When the User Makes a Purchase, Call Our SDK's "handleBuySubscription"
-Here’s a complete example of how to use the SDK:
+## 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/)
 
-In the code below, please remember to update your IAP_SKUS with the comma separated list of your in app purchase SKU's.
+### Option 1: Iaptic Integration
+First, complete the [Iaptic account setup](https://www.iaptic.com/signup) and code integration.
+
+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();
+    const {
+        initialize,
+        isInitialized,
+        handlePurchaseValidation,
+    } = 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[];
+    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]);
 
 
-  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>
-  );
+    // 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,4 +156,140 @@ 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);
+            });
+        }
+    }
+});
+
+```
+
+## Additional Features
+
+### 1. Event Tracking (Beta)
+
+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:
+
+```javascript
+const {
+  referrerLink,
+  subscriptions,
+  iapLoading,
+  handleBuySubscription,
+  userId,
+  userPurchase,
+  trackEvent, // Required for trackEvent
+} = useDeepLinkIapProvider();
+
+<Button
+  title={'track event'}
+  onPress={() => {
+    trackEvent('event_name')
+      .then(() => console.log('Event tracked successfully!'))
+  }}
+/>
+```
+
+### 2. Short Codes (Beta)
+
+#### What are Short Codes?
+
+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.
+
+**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')}
+  />
+```