Integration via postback request

  • Zaktualizowano

If your company belongs in the financial sector (banks, insurance companies, and other financial organizations), go to the article "Integration via postback request for financial programs."

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.
  • There are ready-made solutions for store integration based on popular CMSs (WooCommerce, OpenCart).
  • 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, quick order forms, or 1-click order forms they also must 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.png

 

Integration steps

1. Implement the algorithm for creating a cookie and inserting the admitad_uid value into it.

2. Implement the algorithm for getting admitad_uid value from the 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. Define price, quantity, and other parameters for each product item in the shopping cart.

5. Substitute these values into an array of postback request parameters.

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
currency_code, currency, c currency code string, 3 symbols defined in ISO 4217; alphabetic values only
position_id, pid  serial number of an item in the shopping cart integer a variable with the value varying between 1 and N, where N = position_count
position_count, pc, pn quantity of items in the cart integer a variable, value N depends on the contents of the user’s shopping cart
payment_type action type string, 4 symbols a constant, possible values: “lead” or “sale”
product_id, prid your internal product ID string, 1-100 symbols your internal product ID, the same as in your product feed
quantity quantity of each item integer or fractional  
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
price, cart, p, amount price of an item in the cart integer or fractional  

 

Optionally you can add the client_id parameter that will contain a client ID in your system.

 

Note:

This set of parameters is mandatory for the integration of online stores. If your website belongs to a different category of programs (financial, travel, or mobile programs, online services, online games), the set of required parameters can be changed.

For example, a tour operator does not have parameters that contain information on the items in the cart and can pass only a tour cost and an order number. Then the mandatory parameters will be order_id and price, and position_id and position_count will be excluded.

To find out which parameters are mandatory in your case, contact your account manager.

 

Example of a postback request for a cart with several items

Position

Product name

Price Quantity

Total amount

1 TV 20 000 2 40 000
2 iPhone 35 000 3 105 000
3 Notebook 50 000 1 50 000
      Total 195 000

 

https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
&action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
&price=20000&quantity=2&position_id=1&position_count=3&product_id=11&client_id=&payment_type=sale

https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
&action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
&price=35000&quantity=3&position_id=2&position_count=3&product_id=21&client_id=&payment_type=sale

https://ad.admitad.com/r?campaign_code=your_campaign_code&postback=1&postback_key=your_postback_key
&action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
&price=50000&quantity=1&position_id=3&position_count=3&product_id=31&client_id=&payment_type=sale

For each product item a separate request must be sent. Each request should contain different information about the price, quantity, sequence number in the shopping cart, etc.

 

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.

If you are going to work with unique promo codes:

1. Make sure that you have a "Promo code" field in the order form on the website.
2. 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=your_postback_key
&action_code=1&uid=03b374fa9c2f34069e8df0bda61b8627&order_id=123456&tariff_code=1&currency_code=RUB
&price=50000&quantity=1&position_id=3&position_count=3&product_id=31&client_id=&payment_type=sale
&promocode=admitad500

3. Make sure that all orders with unique promo codes are transmitted to Admitad.

Here are the cases when you should transmit an order to Admitad:

  • the order contains both admitad_uid and unique promo code,
  • the order contains only the unique promo code;
  • the order contains only admitad_uid.

Do not pass the information on the order with the unique promo code to other sources.

 

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, a 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 item in the shopping cart;
  • order ID and order amount are passed correctly;
  • postback requests are sent from the mobile version of the website, quick order forms, 1-click order forms, etc.

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_MDSyMxa.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.

 

Integration via plugins

If your store is based on such platforms as WooCommerce or OpenCart, you can use the plugin for quick integration with Admitad. Read more about it in the article Integration via plugins.

Czy ten artykuł był pomocny?