Migrating from referral code to click id based API tracking

Setting up a REST-API-based tracking flow ensures you get the most robust results. However, not all implementations use Tapfiliate’s best practices. As a result, businesses might be missing some of the most powerful opportunities provided by Tapfiliate. We suggest switching to a more beneficial flow, so please go here for instructions or keep reading if you need more info about why it’s better to switch.

One of those suboptimal flows is using affiliate referral codes directly to track conversions or customers.

If you’re set up this way, your flow probably works as follows:

You monitor incoming visitors to see if the ?ref= parameter is present in the URL.
If so, you persist this value for later use; probably in a cookie
You use this value to create a conversion or customers through the REST API.

However, there is an alternative that offers you significant benefits.

This method:

Will ensure that geo, device and browser data is populated throughout the platform. Thus you get better reports and make informed decisions about your program growth.
Will ensure that the cookie time limit is enforced. In that case you have more control over when you pay commissions, ex. if you don’t want to pay commissions for sales resulting from a click that happened a year ago.
Will allow you to see how many days occurred between the visit through the affiliate link and the actual conversion or customer registration.
Will ensure that affiliates can use the Meta Data feature
Is a prerequisite for being allowed to participate in the Admitad Network Beta

How to switch from referral-code-based tracking to the click-id-based method

Switching is easy and can be done as follows:

Use your existing flow and keep monitoring for the ?ref= query parameter. If it is present, get the value and create a click:
```
curl -X POST -H 'Content-Type: application/json' -H 'X-Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/clicks/ -d '
    {
        "referral_code": "ref-value-goes-here"
    }'
```
The response will be a JSON Object with one property id, which is the Click id. Persist this value in a cookie with a lifetime equal than or greater than the cookie time you configured in your account.
This is the minimal number of arguments needed. We do however advise passing additional information. Passing additional information is required for participants in the Admitad Network Beta.
Store the click id for later use, probably in a cookie. Just like you did before
Next, instead of the referral code, use the click id to create a Customer or a Conversion through the API. Instead of the referral_code you’ll send the click id as the click_id in the request.

That’s it! If you need any help whatsoever, please contact our customer support.

Passing additional information

To fully leverage all functionality you can pass the current user agent, the meta data the affiliate included in the url (required for Admitad Network Beta), the current page and the client ip address.

To obtain the click meta data from the url, grab any query parameter that is prefixed with tm_ and turn it in to an object by removing the prefix and using the rest as key/value object. An example in PHP:

$url = 'https://my-site.com/?ref=john&tm_uid=123&tm_publisher=abc'; 

$urlComponents = parse_url($url); 
parse_str($urlComponents['query'], $params); 

$metaData = [];
foreach($params as $key => $value) {
    if (substr($key, 0, 3) === 'tm_') {
        $mdKey = substr($key, 3, strlen($key))); // Original key minus tm_ prefix
        $metaData[$mdKey] => $value;
    }
}

echo json_encode($metaData); // {"uid": "123", "publisher": "abc"}

As a full request:

curl -X POST -H 'Content-Type: application/json' -H 'X-Api-Key: ((((YOUR API KEY HERE))))' https://api.tapfiliate.com/1.6/clicks/ -d '
    {
        "referral_code": "ref-value-goes-here",
        "meta_data": {
            "uid": "123", 
            "publisher": "abc"
        },
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.71 Safari/537.36",
        "ip": "127.0.0.1"
    }'