Clickout API
When you uncloak the affiliate URLs on the server-side then you need to use our Clickout API. The Clickout endpoint takes in an affiliate link with user data. This data gets registered in our database as a click and a modified affiliate URL including our clickid placed into a subid parameter will be returned. This modified URL has to be used for the redirect in order to correctly attribute a conversion to the click.
- Implement a fallback to redirect the user normally to the affiliate URL if the API request takes too long or returns an error.
POST: Â https://api.wecantrack.com/api/v1/clickout
Request
Header
Content-Type: application/json
Body Parameters
String | URL-encode according to RFC 3986
Required
Required
The Affiliate URL which will be used to direct the user to it
String | URL-encode according to RFC 3986
Optional
Required
The URL where the user clicked out from (usually this can be found in the header referrer)
String | URL-encode according to RFC 3986
Optional
Optional
The URL where the user is redirected from
String
Optional
Required
This is the We Can Track cookie set by our Javascript Tag called _wctrck. It is used to attribute click data to session data.
String
Optional
Recommended
This is the Google Analytics cookie called _ga
JSON
Optional
Optional
Custom data that needs to be attached with the clickout
String
Optional
Optional
Custom indexed 1 to 5 to be used on complex queries.
String (case insensitive)
Optional
Optional
This ID needs to reference back to a click in your database. Currently this is a custom functionality, please reach out to us to make use of this parameter. While you are already able to define click IDs in the click data our system won’t recognise them in the conversion data before we add a relevant regex for it. Please send us examples of your click IDs.
Please also make sure you keep this ID as short as possible.
String
Optional
Optional
Define a click ID placeholder variable through which you can control where exactly our click ID should be placed within the URL you provide us. This can be helpful for (affiliate) URLs that are currently not recognised by our system due to unknown link pattern. If the placeholder field is available in the request, our system will use the placeholder functionality and not any link patterns provided in the system. If no placeholder field is given in the request it will use the available link patterns from our system.
String
Optional
Optional
IP Address
String
Optional
Optional
User Agent
Body example
{
"affiliate_url" : "https%3A%2F%2Fwww.awin1.com%2Fcread.php%3Fawinmid%3DXXXX%26awinaffid%3DXXXXX%26clickref%3DXXXXX",
"clickout_url" : "https%3A%2F%2Fexample.com%2Fpage",
"_ga" : "GA1.2.XXXXXX.XXXXXX",
"_wctrck" : "9jInZ4YnZuZlPjx...",
"metadata" : {
"deal_id" : 123,
"deal_title" : "title",
"anything" : "anything"
},
"custom_index_1" : "index1",
"custom_index_2" : "index2",
"user_click_reference" : "CLICK_ID_1234"
}
Response
Header
Content-Type: application/json
200 Body - OK
The affiliate_url attribute will contain the modified affiliate URL which will be needed to direct the user to it.
{
"affiliate_url": "https%3A%2F%2Fwww.awin1.com%2Fcread.php%3Fawinmid%3DXXXX%26awinaffid%3DXXXXX%26clickref%3DXXXXXWCT191123233005gxs9q"
}
200 Body - Warnings
These requests are successful but currently failing because of some user configuration, the warning message will explain what to do.
{
"warning": "Warning message"
}
Code Examples
In order to get a more clearer picture of how it works, we’ll demonstrate how we would integrate the API.
Explanation
When a user clicks out on a cloaked linked it will go through the click_out function. The get_affiliate_url() uncloaks the URL and stores the affiliate URL in the $affiliate_url variable.
After that we will use Guzzle or CURL or any other HTTP Clients to request the WeCanTrack Clickout API in order to retrieve the modified affiliate URL.
In the request we give it a timeout so that if the request is taking too long for some reason it will stop the request and continue with the rest of the code. We then check if there’s any error in the request, if there is one, we log it and return the original $affiliate_url.
Guzzle Implementation
public function click_out($cloaked_url)
{
$affiliate_url = example_get_affiliate_url($cloaked_url);
try {
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.wecantrack.com']);
$response = $client->request(
'POST',
'api/v1/clickout',
[
'headers' => [
'Content-Type' => 'application/json',
'X-API-Key' => 'XXXXXX-XXXX-XXXX-XXXX-XXXXXXXX',
],
'json' => [
'affiliate_url' => rawurlencode('https://www.awin1.com/cread.php?awinmid=XXXX&awinaffid=XXXXX&clickref2=XXXXX'),
'clickout_url' => !empty($_SERVER['HTTP_REFERER']) ? rawurlencode($_SERVER['HTTP_REFERER']) : null,
'_ga' => !empty($_COOKIE['_ga']) ? $_COOKIE['_ga'] : null,
'_wctrck' => !empty($_COOKIE['_wctrck']) ? $_COOKIE['_wctrck'] : null
],
'timeout' => 2
]
);
$data = json_decode($response->getBody()->getContents(), true);
if (!empty($data['affiliate_url']) && $response->getStatusCode() === 200) {
return redirect(rawurldecode($data['affiliate_url']));
}
if (!empty($data['error'])) {
throw new \Exception($data['error']);
}
} catch (\Exception $e) {
//log error
}
return redirect($affiliate_url);
}
CURL Implementation
public function click_out($cloaked_url)
{
$affiliate_url = example_get_affiliate_url($cloaked_url);
$api_url = 'https://api.wecantrack.com/api/v1/clickout';
$headers = [
'x-api-key: XXXXXX-XXXX-XXXX-XXXX-XXXXXXXX',
'Content-Type: application/json'
];
$post_data = [
'affiliate_url' => rawurlencode($affiliate_url),
'clickout_url' => !empty($_SERVER['HTTP_REFERER']) ? rawurlencode($_SERVER['HTTP_REFERER']) : null,
'_ga' => !empty($_COOKIE['_ga']) ? $_COOKIE['_ga'] : null,
'_wctrck' => !empty($_COOKIE['_wctrck']) ? $_COOKIE['_wctrck'] : null
];
try {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post_data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_TIMEOUT, 2);
$data = json_decode(curl_exec($ch), true);
if($error_code = curl_errno($ch)){
//error codes: https://curl.haxx.se/libcurl/c/libcurl-errors.html
throw new \Exception('CURL Failed.. error code: '.$error_code);
}
if (!empty($data['affiliate_url'])) {
return urldecode($data['affiliate_url']);
}
if (!empty($data['error'])) {
throw new \Exception($data['error']);
}
} catch (\Exception $e) {
//log error
} finally {
curl_close($ch);
}
return $affiliate_url;
}
