Custom Integration advanced guide - anujtenani/goaffpro GitHub Wiki
- Login (or sign up) on the goaffpro platform.
- Click Add a Store to create a new store account. Choose SDK as the platform method
- Integrate the code provided on the relevant pages
Basic integration requires that you add the code at two places in your e-commerce store
- The
general tracking codewhich 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
You can find the general tracking code in Settings -> Advanced settings tab -> Third party tracking section
- The
conversion tracking codewhich needs to be added to the CONVERSION EVENT or the ORDER THANK YOU PAGE of your e-commerce store. Add this code AFTER thegeneral tracking code.
<script type="text/javascript">
var goaffproOrder = {
number:'#1001',
total:1000,
forceSDK:true, // use this parameter to process this order as a CUSTOM ORDER (bypasses platform order enrichment)
}
goaffproTrackConversion(goaffproOrder)
</script>See example code for
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:'[email protected]',
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",
forceSDK:true, // use this parameter to process this order as a CUSTOM ORDER (bypasses platform order enrichment
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)
}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
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 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}}'
}
}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>
