Server-side Tracking
Step 1 - Tracking Visits
Please copy/paste the following code into the <head>
section of every page on your website where you expect your affiliates to drive traffic. Make sure to replace YOUR-PUBLIC-KEY
below with the Public API key from your Refersion account.
<!-- REFERSION TRACKING: BEGIN -->
<script>
! function(e, n, t, i, o, c, s, a) {
e.TrackingSystemObject = "r", (s = n.createElement(t)).async = 1, s.src = "https://cdn.refersion.com/refersion.js", s.onload = function() {
r.pubKey = "YOUR-PUBLIC-KEY", r.settings.fp_off = !1;
r.initializeXDLS().then(() => {
r.launchDefault()
})
}, (a = n.getElementsByTagName(t)[0]).parentNode.insertBefore(s, a)
}(window, document, "script");
</script>
<!-- REFERSION TRACKING: END -->
Step 2 - Sending orders via a JSON webhook
You can report orders to Refersion by creating a Webhook. Usually, this option requires a greater amount of development work since you'll be "posting" order information to us directly from your server.
There are two requirements for this implementation:
- Sending us a
cart_id
using a short JavaScript code on your "thank you" page so that we may reference any future Webhook reported to the session. - An HTTP POST of the actual order information from your server, which contains the previously reported
cart_id
.
The cart_id
value
When we receive any Webhooks, we must associate it with a previously captured browser session. However, since Webhooks are reported from the server-side and not the browser-side, we can not access the relevant customer's session information. For this reason, we use the cart_id
value as a common identifier that we can reference. We ask you to report a cart_id
on your "thank you" page where we store session information and then a second time in the Webhook so that we may associate it with the aforementioned browser session from the JavaScript call.
The cart_id
may be any string value up to 255 characters.
For security, make sure that
cart_id
is not sequential or may be easily guessed such as a session ID or an encrypted version of several strings.
Code
<!-- REFERSION TRACKING: BEGIN -->
<script>
const rfsn = {
cart: "YOUR-CART-ID",
id: localStorage.getItem("rfsn_v4_id"),
url: window.location.href,
aid: localStorage.getItem("rfsn_v4_aid"),
cs: localStorage.getItem("rfsn_v4_cs")
};
r.sendCheckoutEvent(rfsn.cart, rfsn.id, rfsn.url, rfsn.aid, rfsn.cs);
</script>
<!-- REFERSION TRACKING: END -->
You must replace "YOUR-CART-ID" with the actual cart_id
value from your site. Please make sure to include the double-quotes.
In order to function properly, the click tracking code described in Step 1 and this code must run on the same domain and security level (http/https).
Posting the Webhook
Data must be reported as JSON string which contains the order data as well as the cart_id
. You Refersion API keys (public and secret) should be sent in the header of the request. Below is an example of the JSON that we are expecting.
{
"cart_id": "DDXqfBngTWuX8N8Asqr2mY3RkmHCXdM7Vz6mdHkjwrEnN5zyRY",
"order_id": "20150401102883",
"shipping": 9.99,
"tax": 0.57,
"discount": 2.25,
"discount_code": "HOLIDAY1",
"currency_code": "USD",
"customer":{
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"ip_address": "234.192.4.75"
},
"items": [
{
"price": 5.50,
"quantity": 2,
"sku": "PROD_A",
"name": "Product A"
},
{
"price": 10.00,
"quantity": 1,
"sku": "PROD_B",
"name": "Product B"
},
{
"price": 15.00,
"quantity": 3,
"sku": "PROD_C",
"name": "Product C"
}
]
}
To deliver this data to us to you must send it via an HTTP POST. Below is example PHP code using cURL.
<?php
// The complete data that you are sending
$order_data = array(...); // Omitting data for demonstration
// Convert array into JSON
$json_data = json_encode($order_data);
// The URL that you are posting to
$url = 'https://inbound-webhooks.refersion.com/tracker/orders/paid';
// Start cURL
$curl = curl_init($url);
// Verify that our SSL is active (for added security)
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, TRUE);
// Send as a POST
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
// The JSON data that you have already compiled
curl_setopt($curl, CURLOPT_POSTFIELDS, $json_data);
// Return the response
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
// Set headers to be JSON-friendly
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($json_data),
'Refersion-Public-Key: YOUR-PUBLIC-KEY',
'Refersion-Secret-Key: YOUR-SECRET-KEY')
);
// Seconds (30) before giving up
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 30);
// Execute post, capture response (if any) and status code
$result = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// Close connection
curl_close($curl);
Variable Descriptions
Transaction Data
A transaction represents the entire order that occurred, and contains the following values:
Value | Type | Required | Description |
---|---|---|---|
cart_id | String | Yes - Webhook only | Cart ID that matches what you're reported as rfsn.cart in the r.sendCheckoutEvent() function, as per above. |
order_id | String | Yes | Unique shopping cart order ID or transaction number used to reference the purchase that you're reporting. |
subscription_id | String | Yes - Subscriptions only | For subscription purchases only: A unique identifier that represents the whole subscription, which can be a reference to all of the individual order_ids within this subscription. Only available in webhook reporting. |
is_subscription | Boolean | Yes - Subscriptions only | If you are reporting an event which belongs to a subscription, set this to TRUE , otherwise leave blank.Only available in webhook reporting. |
auto_credit_affiliate_id | Number | No | (optional) The ID of the affiliate you'd like to credit the order to. |
shipping | Number | No | Total shipping and handling the customer was charged for the order. |
tax | Number | No | Total tax the customer was charged for the order. |
discount | Number | No | Total in discounts that were applied to the order. |
discount_code | String | No | The discount or coupon code that was used on the order. |
currency_code | String | Yes | The three letter currency code of the order totals that you are reporting. Example: USD, CAD, GBP. |
Customer Data
A customer represents the individual customer who purchased, and contains the following values:
Value | Type | Required | Description |
---|---|---|---|
first_name | String | No | Customer’s first name. |
last_name | String | No | Customer’s last name. |
String | No | Customer’s email address. | |
ip_address | String | No | The IP address of the customer. |
Item Data
An item represents an individual product that the customer had ordered, and contains the following values:
Value | Type | Required | Description |
---|---|---|---|
sku | String | Yes | A unique Product SKU or identifier ID. Can be blank, but we highly recommend that you populate the field. |
name | String | No | The name of the item. |
quantity | Number | Yes | Total quantity ordered of the product. |
price | Number | Yes | Price of each item. For example, if the customer ordered 10 items at $5 each, you should report $5, not $50. Do not include currency symbols. |