Integration via postback request for financial programs

  • Zaktualizowano

When integrating via postback request, the advertiser server sends a request with information about the actions performed on the advertiser’s website to the Admitad server. The Admitad server receives this data and records it in the statistics.

Features of integration via postback request:

  • The changes made on the website do not affect sending requests via postback requests.
  • It is a more secure solution because the request contains a private authorization key. Besides, requests are sent from pre-known IP addresses, and the request source can be checked at any moment in the logs.
  • To implement the solution, you need to have access to the server side of the website (back-end).
  • If you have a mobile version of the website or a mobile app, they are also to be integrated.
  • If there are several application forms on the website, they all are to be integrated.
  • Postback requests are sent from your server, not from a user’s browser.
  • Postback requests should be sent only for actions of users, who were attracted by Admitad publishers. To identify these users, the admitad_uid parameter is used.

What is admitad_uid?

When working with an affiliate program, a publisher places its affiliate link on their ad space. The affiliate link is generated on the basis of a transition link — a link that leads to the website of the program and contains GET parameters required by Admitad and UTM parameters of the advertiser. One of the GET parameters must necessarily pass the value of admitad_uid, the unique identifier that is generated by the Admitad server at the moment a user follows the affiliate link. The admitad_uid stores the service information about the publisher and the source of the transition, based on which the Admitad system detects who of the publishers attracted the user to the website and who should get reward for the user's actions.

An example of a transition link:
https://site.ru/?admitad _uid={{admitad_uid}}

The value of the admitad_uid parameter is to be received from the GET parameter upon the user's entry to the website, and saved for 90 days in the cookies. After the user’s authorization admitad_uid should be recorded in the database and associated with the user’s account. The user may follow the link to any page of the website, so admitad_uid is to be tracked on all pages. When the user performs an action, it must be checked, whether the user has admitad_uid. If so, the value of admitad_uid is to be passed to the postback request.

Cookie or its lifetime should not be changed in case a user comes from other free sources, such as organic search or an e-mail newsletter. Admitad uses the Last Paid Click attribution model, according to which actions should be credited to the last paid source of traffic.

 

General scheme of work

integration-via-postback-reque_oEinvvN.png

Integration steps

  1. Implement the algorithm for creating a cookie and inserting the admitad_uid value to it.
  2. Implement the algorithm for getting admitad_uid value from cookie and recording it in the database at the moment of a user’s authorization.
  3. Implement a mechanism for sending a postback request from your server (for example, cURL, Wget, file_get_contents).
  4. Writing functions to substitute dynamic values in a postback-request (for example, uid, order_id), etc.

There is no special answer of the Admitad server to a postback request. The status HTTP 200 OK is returned.

 

How to set GET parameter admitad_uid in the cookies using PHP

if (isset($_GET['admitad_uid'])) {
$days = 90;
setcookie('_aid', $_GET['admitad_uid'], time() + 60 * 60 * 24 * $days, '/');
}

function get_admitad_uid() {
if (!isset($_COOKIE[‘_aid’])) {
return null;
}

return $_COOKIE['_aid'];
} 

 

Setting up postback request

Required parameters

Parameter name
(aliases are in italics)

Description Type Comment
uid Admitad ID  string

the generated value, received in the admitad_uid parameter when the user comes to the website

If you allow contextual advertising in your program the gclid value generated by Google will be written in the admitad_uid parameter instead of the uid value when users clickthrough pulbishers' contextual ads.

For the tracking to work correctly, your server should receive and send the full value of the gclid parameter. See more on the length of the gclid parameter

campaign_code program code string, 10 symbols a constant, its value is specified in the postback request that was sent to you at the beginning of integration
order_id, oid your internal order ID string, 1-100 symbols

your internal order ID

Important! Be sure to find orders by this order_id in your CRM, as it will be used for verifications in the future.

action_code, ac, product, product_code action code integer a variable, its value is sent to you by a specialist of the tracking department at the beginning of integration
tariff_code, tc rate code integer a variable, its value is sent to you by a specialist of the tracking department at the beginning of integration
payment_type action type string, 4 symbols a constant, possible values: “lead” or “sale”
postback, pb key for authorizing a postback request string, 1 symbol a constant, value = 1
postback_key, postback_hash, pk key for identifying a postback request string, 32 symbols a constant, its value is specified in the postback request that was sent to you at the beginning of integration
If a program has a percent rate, the parameters below are also required:
price, cart, p, amount price of an item in the cart integer or fractional  
currency_code, currency, c currency code string, 3 symbols defined in ISO 4217; alphabetic values only

 

Example of a postback request

https://ad.admitad.com/r?campaign_code=constanta&postback=1&postback_key=constanta&action_code=1&
uid=&order_id=&tariff_code=1&price=1000&currency_code=RUB&payment_type=lead

 

Setting up data transfer of unique promo codes

Unique promo codes are promo codes that are linked to a specific publisher. Learn more about them here.
To use unique promo codes, add the parameter promocode that will pass the promo code value.

 Parameter name  Description  Type
 promocode  unique promo code  string, 255 characters

 

Example of a request

https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=constanta
&action_code=1&uid=&order_id=&tariff_code=1&currency_code=RUB&price=50000
&payment_type=lead&promocode=admitad500

If the code contains the promocode parameter, orders are assigned as follows:

  • if the promocode contains the value of a unique promo code, the priority is given to it;
  • if the promocode contains the value of a non-unique promo code or the value is missing (the user did not enter the promo code), the order is assigned based on the UID.

 

Test procedure

1. After you configure the algorithm for sending postback requests from the server, contact the Admitad tracking department and get a test link.

2. Place test orders. Make sure that:

  • admitad_uid is processed at all pages of the website;
  • admitad_uid is recorded in the cookie and in the database and is associated with a user’s account;
  • the lifetime of the cookie that contains admitad_uid meets the terms of the agreement, cookie is not deleted when a user uses organic search.
  • when a user performs an action, postback requests are sent from your server, not from the user’s browser;
  • the requests are sent for all actions and rates of your affiliate program;
  • the requests are sent for each unique application (we recommend to set ignoring of duplicated applications);
  • application ID is passed correctly;
  • postback request is set on the mobile version of the website and all application forms.

3. If the request has been received by the Admitad server without errors, the order will appear in the statistics in your account (Your account — Reports — On actions).
integration-via-postback-reque_Ra5B014.png
 

Inform the Admitad specialist that the tests have been completed successfully.

4. If the action has not appeared in the statistics within an hour, there is a problem in the algorithm of sending the request or the parameters of the request are invalid. Check if:

  • you have implemented the algorithm of sending postback requests correctly;
  • the request contains the campaign_code and postback_key that were sent to you at the beginning of the integration.

To identify the error, go to a request log (Tools — Request log). The error text is specified in the Result field. Correct the error and run a test again. You can find a guide on the Request log here.

Czy ten artykuł był pomocny?