Integration via XML

  • Updated

Integration via XML is an integration method when an advertiser creates an XML file of a certain structure, where the data about the actions performed on their website are uploaded. The Admitad Affiliate server with certain periodicity access this file and unload the data in the statistics.

Features of integration via XML:

  • You can restrict access to the file with a login and password.
  • With the relevant settings, publishers can receive information on the orders in real time.
  • In case of any operating failures, the orders can be easily restored in the Admitad Affiliate statistics.
  • If the processing queue increases, delays may occur in the appearance of data.
  • 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.
  • An XML file should contain only information on the actions of users, who were attracted by Admitad Affiliate 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 Affiliate 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 Affiliate 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 Affiliate 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 XML file.

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 Affiliate 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-xml.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 the admitad_uid value from the cookie and recording it in the database at the moment of a user’s authorization.
  3. Define price, quantity, and other parameters for each product item in the shopping cart.
  4. Export data to the XML file.

 

How to set GET parameter admitad_uid in 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'];
} 

 

XML file structure

Required parameters

Parameter name Description Type Comment
 uid Admitad ID  string

the generated value, received in the admitad_uid parameter when a 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

order_id your internal order ID string, 1-100 characters

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 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 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 code string, 3 characters defined in ISO 4217; alphabetic values only
position_id  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 quantity of items in the cart integer a variable, value N depends on the contents of the user’s shopping cart
quantity quantity of each item integer or fractional, non-negative  
payment_type action type string, 4 characters a constant, possible values: “lead” or “sale”
product_id your internal product ID string, 1-100 characters your internal product ID should be the same as in the product feed.
price price of an item in the cart integer or fractional, non-negative  
datetime_action date and time of an action string, 19 characters in the format "YYYY-MM-DD hh:mm:ss"

 

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

 

Example of an XML file for a cart with one item

<?xml version="1.0" encoding="UTF-8"?>
<payment_list version="2">
   <payment>
       <uid>admitad_uid</uid>
       <order_id>15</order_id>
       <product_id>125</product_id>
       <tracking>Hand Tools - Chainsaw</tracking>
       <quantity>1</quantity>
       <currency_code>RUB</currency_code>
       <price>2000</price>
       <position_id>1</position_id>
       <payment_type>sale</payment_type>
       <action_code>1</action_code>
       <tariff_code>1</tariff_code>
       <position_count>1</position_count>
       <datetime_action>2019-12-31 00:00:00</datetime_action>
    </payment>
</payment_list>

 

Example of an XML file for a cart with several items

<?xml version="1.0" encoding="UTF-8"?>
<payment_list version="2">
   <payment>
       <uid>admitad_uid</uid>
       <order_id>15</order_id>
       <product_id>125</product_id>
       <tracking>Hand Tools - Chainsaw</tracking>
       <quantity>1</quantity>
       <currency_code>RUB</currency_code>
       <price>2000</price>
       <position_id>1</position_id>
       <payment_type>sale</payment_type>
       <action_code>1</action_code>
       <tariff_code>1</tariff_code>
       <position_count>3</position_count>
       <datetime_action>2019-12-31 00:00:00</datetime_action>
   </payment>
   <payment>
       <uid>admitad_uid</uid>
       <order_id>15</order_id>
       <product_id>57</product_id>
       <tracking>Table lamp</tracking>
       <quantity>2</quantity>
       <currency_code>RUB</currency_code>
       <price>1790</price>
       <position_id>2</position_id>
       <payment_type>sale</payment_type>
       <action_code>2</action_code>
       <tariff_code>2</tariff_code>
       <position_count>3</position_count>
       <datetime_action>2019-12-31 00:00:00</datetime_action>
   </payment>
   <payment>
       <uid>admitad_uid</uid>
       <order_id>15</order_id>
       <product_id>71</product_id>
       <tracking>Welding machine</tracking>
       <quantity>1</quantity>
       <currency_code>RUB</currency_code>
       <price>4050</price>
       <position_id>3</position_id>
       <payment_type>sale</payment_type>
       <action_code>2</action_code>
       <tariff_code>1</tariff_code>
       <position_count>3</position_count>
       <datetime_action>2019-12-31 00:00:00</datetime_action>
   </payment>
</payment_list>

Each product item must be added as a separate <payment> tag. The tag should contain the data about price, quantity, sequence number of the item 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.

1. Make sure there is a coupon entry field on the checkout page

2. Enter the unique promo code from the checkout page to the parameter promocode.

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

 

3. Having the unique promo code, the order should be included in the XML upload file regardless of the admitad_uid.
    The order should be transmitted to Admitad Affiliate if

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

     The unique promo code order information should not be transmitted to any other channel. 

 

Example of an XML-file for a unique promo code order

<?xml version="1.0" encoding="UTF-8"?>
<payment_list version="2">
    <payment>
        <uid>admitad_uid</uid>
        <order_id>15</order_id>
        <product_id>125</product_id>
        <tracking>Hand tools - chainsaw</tracking>
        <quantity>1</quantity>
        <currency_code>USD</currency_code>
        <price>20</price>
        <position_id>1</position_id>
        <payment_type>sale</payment_type>
        <action_code>1</action_code>
        <tariff_code>1</tariff_code>
        <position_count>1</position_count>
        <datetime_action>2019-12-31 00:00:00</datetime_action>
        <promocode>10OFF</promocode>
    </payment>
</payment_list>

 

Test procedure

1. After you create an XML file with the required structure and set up the algorithm for exporting action data to it, contact the Admitad Affiliate tracking department and get a test link.

2. Place test orders. Make sure that:

  • admitad_uid is processed on 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.
  • the information on all actions and rates of your affiliate program is sent to the XML file;
  • each product item of the cart has its own <payment> tag;
  • the parameter values that are transferred to the XML file are correct for all items in the cart. Pay special attention to the order amount and order ID.
  • tracking is set for the mobile version of the website, quick order forms, 1-click order forms, etc.

3. If the request has been received by the Admitad Affiliate server without errors, the action will appear in the statistics in your account (Your account — Reports — On actions).

​ ​integration-via-xml_zLKyiAp.png

 

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

4. If the action has not appeared in the statistics within an hour, make sure that:

  • you sent the Admitad Affiliate specialist a correct link to the file;
  • the file structure corresponds to the specified above;
  • you used the correct case in the tags.

To identify the error, go to a request log (Tools — Request for payment). The error text is specified in the Result field. Correct the error and run a test again.

Was this article helpful?