Skip to content

Custom Integration advanced guide

Anuj Tenani edited this page Jan 18, 2024 · 19 revisions

Basic integration

  1. Login (or sign up) on the goaffpro platform.
  2. Click Add a Store to create a new store account. Choose SDK as the platform method
  3. Integrate the code provided on the relevant pages

Basic integration requires that you add the code at two places in your e-commerce store

  1. The general tracking code which needs to be added to ALL PAGES of your store. Generally this is added in the header section before the closing </head> tag. The tracking code looks something like below
<script type="text/javascript" src="https://api.goaffpro.com/loader.js?shop=your-unique-store-public-key"></script>

The aforementioned script automatically keeps track of your affiliate's links

  1. The conversion tracking code which needs to be added to the CONVERSION EVENT or the ORDER THANK YOU PAGE of your e-commerce store. Add this code AFTER the general tracking code.
<script type="text/javascript">
var goaffproOrder = {
   number:'#1001',
   total:1000
}
goaffproTrackConversion(goaffproOrder)
</script>

See example code for

Advanced Integration

Extended Order schema for conversion tracking

window.goaffpro_order = {
    id:'1001', // the internal order ID of your system (useful if you are using REST JSON file)
    number:'#1001', // human readable order number displayed to the admins
    total: 1000, // the order total (the final amount that the customer paid)
    subtotal: 850, // order subtotal (order total minus shipping and taxes)
    discount: 50, // the discount received by the customer
    tax: 100, // the tax charged on the order
    shipping: 50,  // the shipping charged on the order
    currency:'USD', //ISO-4217 three letter currency code of the order
    date: '2021-04-27T17:06:55.450Z',
    customer: { // customer details
        first_name:'John',
        last_name:'Doe',
        email:'johndoe@example.com',
        phone:'+1 555-111-222', // optional
        is_new_customer:true //optional
    },
    coupons:['EASY10OFF'], // an array of discount codes applied to the order
    line_items:[ // array of products sold in this order
        {
            name:'Product A', // name of the product
            quantity:2, //total quantities sold
            price: 450,
            sku:'PD-110-1', //product SKU
            product_id: '21413232', // Internal product ID (used if you are using REST JSON FILE)
            tax: 0, // tax charged on this product. USE this only if the product price has VAT included in the price
            discount: 50, // total discount received by the customer on this product. In this case, the customer got $25 discount per item.
        }
    ],
   status:"approved",
   commission: 45, // (not recommended) specify the commission to be given for this order
   delay: 60000, // the amount in milliseconds to delay the processing of this order. This is use full for up-sell where the second conversion event should take preference over the first order. So send the first conversion event with a suitable delay parameter
}
if(typeof window.goaffproTrackConversion !== "undefined"){
  window.goaffproTrackConversion(window.goaffpro_order)
}

Securing payload

You can also send encrypt the payload before you send it to goaffproTrackConversion() function. Turn on Secure Payloads in the Settings -> SDK Settings tab of the admin dashboard

You will receive a Payload Secret Key. You can then encode the goaffproOrder object server side as a JSON Web Token and then call the goaffproTrackConversion function

var goaffproOrder = "eyJhbGciOiJIUzI1NiJ9.ewogICBudW1iZXI6JyMxMDAx..."
goaffproTrackConversion(goaffproOrder)

The goaffproOrder object is encoded as a JSON Web Token with HS256 (HMAC) Algorithm. For more details about JSON Web Token and compatible libraries, see https://jwt.io

Dynamic loading

To load the script dynamically (i.e. without the script tag) you can use the following function in place of <script type="text/javascrip...></script>

window.goaffpro_order = {
   id:'order_id',
};

(function() {
    var elem = document.createElement("script");
    elem.type = "application/javascript";
    elem.src = "https://api.goaffpro.com/loader.js?shop=your-unique-store-public-key";
    document.body.appendChild(elem);
})();

REST JSON File (Draft Spec)

REST JSON file a simple JSON definition file which you can set in your store to have the app communicate with your back-end with simple HTTP calls. This file enables the app to do a number of functions like automatically create discount codes for affiliates when they signup, allows admins to set commission rates depending on products etc.

{
    base:{ // these are base configuration of http client which are merged with each function request to simplify the function calls
        url:"https://yourserverapi.com/baseendpoint", // the base endpoint
        auth :{ // if your endpoint is secured with HTTP basic auth
            // username:'admin',
           // password:'password'
        },
        headers:{ // or if it is secured with any custom header or if you want to send a custom header
            // Authorization: "Bearer goaffpro"
        },
    },
    getOrders:{
        /**
         * This function is used for "Add a sale" option. Sales -> All sales tab -> Create a new sale option
         * 
         * before the the timeperiod which can be chosen by the affiliate to retrieve orders before a date. before is optional and only
         * passed if the user chooses the filter
         * The output returned by this endpoint must be in the following format
         * [
         *     {
         *         "id": "1001", // internal order id of the system
         *         "number": "#1001" // human readable number of the system
         *     }
         * ]
         */
        url:'/orders?before={{ before }}'
    },
    getOrder:{
        /**
         * This function is used for "Add a sale" option. Sales -> All sales tab -> Create a new sale option
         * The output returned by this endpoint must be the basic or the extended order schema.
         */
        url:'/order/{{ id }}'
    },
    createDiscountCode:{
        /**
         * This function is used for creating the automatic coupon code when the affiliat signs up
         * Sends the coupon code be created as a JSON body
         * {
         *     code:'XYZ',
         *     discount_value:10,
         *     discount_type:'percentage',
         * }
         */
        url:'/coupons',
        method:'post',
    },
    deleteDiscountCode:{
        /**
         * This function is used to delete the created discount code when the affiliate is deleted OR when the affiliate updates their discount code
         * or when the admin deletes the discount code in the Coupons page of the app
         * Sends the coupon code be created as a JSON body
         */
        url:'/coupons/{{ code }}',
        method:'delete'
    },
    getProducts:{
        /**
         * This function is used in the product based commissions (Commissions page -> New product commission option)
         * @output Array
         * Must be in the format.
         * [
         *  { 
         *    id:'product id', // this is used to match the product ID in the order line items data
         *    name:'name of the product', // this is just to display the product name to the admins
         *  }
         * ]
         */
        url:'/products?search={{keyword}}',
        method:'get'
    },
    getCategories:{
        /**
         * This function is used in setting the collection based commissions (Commissions page -> New collection commission)
         * @output Array
         * [
         *  {
         *    id:'category id',
         *    name:'name of the category'
         *  }
         * ]
         */
        url:'/categories?search={{keyword}}',
    },
    getProductsInCategory:{
        /**
         * This function is used in setting the collection based commissions (Commissions page -> Collections section -> Sync all)
         * @output Array
         * [
         *   'Product Id 1',
         *   'Product Id 2',
         *   'Product Id 3'
         * ]
         */
        url:'/productsInCategory?category_id={{category_id}}'
    },
  	searchCustomers:{
        /** 
         * This function is used for customer-affiliate connect option.
         * @output Array
         * [
         *  {
         *    "id":"customer_id",
         *	  "email":"email address of the customer",
         *	  "name":"name of this customer"
         *	}
         * ]
         */
      url:'/searchCustomers?search={{keyword}}'
    }
}

Custom SDK Integration for supported platforms

The following code allows you to send order data for platforms where API integration is available. Ensure that the goaffpro SDK (see Step 1 of Basic Integration above) is loaded before the function call is made

<script type="text/javascript">
goaffproTrackConversion('order_id')
</script>

In case ORDER ID from store platform API is not available. The last_order can be sent as order ID to attribute the last received order from the store for conversion

<script type="text/javascript">
goaffproTrackConversion('last_order')
</script>
Clone this wiki locally