Orders

 

Foreword

Before starting implementation of the SalesTracker plugin, please make sure you have initialised the AT Internet JavaScript Tracker and selected the plugin from within the Tag Composer interface.

 

Tagging methods

The JavaScript plugin SalesTracker makes it possible to measure orders on your site.

The Tracker has a method “order.set()” enabling the accurate measurement of your objectives and sales.

Properties marked with a * need the SalesTracker option in order to be processed.

The method “order.set()” takes as a parameter an object whose properties are as follows:

• orderId: Order/reservation number (this parameter is mandatory).
• turnover: Indicative amount (primary goal turnover).
• * status: Order/reservation status (1/2/3/4) (see Appendix for more details).
• * newCustomer: New customer (true/false).
• * paymentMethod: Payment method (see Appendix for more details).
• * amount: Order totals (incl. tax, excl. tax, VAT).
• * delivery: Delivery (Costs including tax and excluding tax, delivery method).
• * discount: Discounts (incl. tax, excl. tax, promo code).
• * orderCustomVariables: Order/reservation variable.
• * confirmationRequired: PRE1-type page variable (true/false).

You should associate your SalesTracker tag with a Page tag, “tag.page.set(), so that it is treated. See Measuring pages for more information.

 

Tagging orders

 

Without SalesTracker option

Tagging orders without the SalesTracker option will only give you the order ID and the turnover information.

var tag = new ATInternet.Tracker.Tag();
// set page name
tag.page.set({
    name:'pageName'
});
// set order
tag.order.set({
    orderId: 8235, //order ID
    turnover: 2049 //Sales Turnover indicator
});
tag.dispatch();

 

With SalesTracker option

The tags placed on your site must pass all information linked to the purchase process to our servers (order/reservation number, payment method, total amount, etc.).

These tags are taken into account only on primary goal pages.

var tag = new ATInternet.Tracker.Tag();
// set page name
tag.page.set({
    name:'pageName'
});
// set order
tag.order.set({
    orderId: 8235, //order ID
    turnover: 2049, //Sales Turnover indicator
    status: 1, //order status
    newCustomer: true, //is this a new customer ? true/false
    paymentMethod: 1 //payment method
});
// set order amount
tag.order.set({
    amount: {
        amountTaxIncluded: 2049, //order amount (all taxes included)
        amountTaxFree: 1649.36, //order amount (tax free)
        taxAmount: 339.64 //tax
    }
});
// set order delivery
tag.order.set({
    delivery: {
        shippingFeesTaxIncluded: 19.9, //shipping cost (all taxes included)
        shippingFeesTaxFree: 16, //shipping cost (tax free)
        deliveryMethod: '1[Colissimo]' //delivery method
    }
});
// set order discount
tag.order.set({
    discount: {
        discountTaxIncluded: 9.9, //discount amount (all taxes included)
        discountTaxFree: 7.96, //discount amount (tax free)                
        promotionalCode: 'CDPR15485Q' //promo code
    }
});
// custom order variables
tag.order.set({ orderCustomVariables: [5, 30 ,14, '[contact tel]', 1]});
tag.dispatch();

Explanations

An order was placed for a total of 2049€ tax included (1649.36€ without tax) with a discount of 9.90€ (7.96€ without tax), of which 19.90€ is for delivery fees (16€ without tax), paid by “bank card”. Additionally, the order is “pending” and the promo code “CDPR15485Q” was used. This order was sent via “colissimo” shipping services.

The “turnover” variable

The “turnover” variable represents the main revenue variable.

In the above example, the value entered in the “turnover” variable corresponds to the total including tax. Nothing prevents you from, for example, retrieving a total without tax, without delivery fees. It’s up to you to define the main turnover variable, depending on your business activity and/or your expectations.

Variables specific to the order

Order totals (““amountTaxIncluded” and “amountTaxFree“) are disassociated from the total used notably in source analyses (“turnover”). We therefore make the distinction between countable variables (with and without tax) for the “SalesTracker” module, and a total variable that is customisable and invariable for interface analyses.

 

Order discounts

The variables “discountTaxIncluded” and “discountTaxFree” represent a “total” discount applied to the order.

Discounts can also apply to the product (= order content) (see section Cart / Order content for more information regarding product discounts).

Consequently:

• If both discounts are entered (order + product), the order discount must be equal or superior to the product discount. In this case, the product discount is included in the order discount.
• If the order discount is not entered, a sum of product discounts is applied at the order level.

 

Order/reservation variables

In addition to selecting a global profile based on your activity and industry (e-Commerce, travel, classified ads), it is possible to go even further in customising your measurement via use of specific variables in your source code.

You must integrate the following tag in your source code by completing, in advance, all values of the object “orderCustomVariables”:

var tag = new ATInternet.Tracker.Tag();
// set page
tag.page.set({
    name:'pageName'
});
// set order
tag.order.set({
...
    orderCustomVariables: [5, 30 ,14, '[contact tel]', 1] //custom variables
...      
});
tag.dispatch();

The object “orderCustomVariables” is an array. Each variable position is therefore important. In this example the value 5 occupies the first array position, it will then correspond to the custom variable n° 1 in the generated hit (parameter &o1= in hit). In case you do not want to send a custom variable but want to keep the position of the following variables, just leave the field empty (ex: orderCustomVariables: [”, 30 ,14, ‘[contact tel]’, 1]).

Variable types

Variables can take different formats (text, numbers, date, country, length).

Integrating the values of certain variables is done via import (done by you) of an Excel file (xls) or CSV, via a correspondence table. This operation must be done directly from within the interface’s Settings area.

• ID/date
  The “ID”-type variable is characterised by a piece of information that can itself group together several values.

• Text
  In the same way as ID/date-type variables, you can add customised “text”-type variables by completing the corresponding table. The main advantage is to be able to retrieve readable values immediately in your analyses.

• Value
  Variables of this type have the particularity of being able to collect summable information. As such, an average can be calculated.

• Length
  This variable type lets you introduce information closely linked to your activity. It also offers the possibility of summable variables (or with averages) in your analyses.

• Country
  In the same way, the “country”-type variable allows you to perfectly adapt measurement to your line of activity.

It is mandatory that “Text” and “Country”-type variables be entered between square brackets. The ISO norm is used for tagging countries. You can retrieve the list of ISO codes via the Settings zone of your interface.

 

Order content

The tagging of order content is made possible by the methods “cart.set()” and “cart.add()”. See section Cart / Order content for more details.

 

Measuring confirmation pages on external sites (banks)

The objective here is to be able to measure completed orders and reservations, despite the confirmation page being hosted by an external site (payment platforms).

We suggest simulating a tag when your site receives payment confirmation from the external site:
Step 1: the user leaves your site to continue with payment on the external (bank) site
Step 2: the user completes his/her payment, which is accepted. The bank sends validation to your site.
Step 3: your site, being completely transparent for the user, finalises the order and at the same time, calls the tag URL.

Server-side tag

The previous scenario involves implementation of specific tags:

• Tag to be placed on the last page the user sees before leaving for the bank page (page containing all order/reservation information and content) and requiring confirmation (“confirmationRequired”: true).

var tag = new ATInternet.Tracker.Tag();
// set page
tag.page.set({
    name:'pageName'
});
// set order
tag.order.set({
...
    confirmationRequired: true //is confirmation required ? true/false
...
});
// set order content
tag.cart.set({
    cartId: 123456 //cart ID
});
tag.cart.add({...})
tag.dispatch();

“cartId” contains the number of the order/reservation content, or the number of the order/reservation if it is known at this stage. See section Cart / Order content for more details.

• Tag to be placed in an ASPHTTP-type call, which must use a few specific variables (enabling the link with the previously mentioned tag).

In concrete terms, once payment is made, you will receive confirmation or cancellation of payment. A synchronisation operates (via the website or a separate treatment) between the payment process with your service provider, and your database, in order to obtain payment information on orders/reservations.

It’s at this time that a second tag should be put into place; this second tag enables you to consider the order as complete.

Integration in an ASP / HTTP call

A traditional tag is JavaScript code called directly from the customer, or in other words, the end user. Here you will notice that it’s the server hosting the site which directly calls the tag. To the extent that the JavaScript requires generation of HTML code (code not generated by the server at this time) the tag is called directly via its URL, without JavaScript, as follows:

http://logxxxx.xxx.com/hit.xiti?s=&s2=&p=&tp=conf1&idcart=&cmd=&st=

These are the different parameters of this tag:

• s=: level 1 site ID
• s2=: Level 2 site, in which the “page” must be classified.
• p=: name of the “page” exactly as it should appear in analyses. This page will be declared as a primary goal conversion page.
• tp=conf1: variable allowing recognition of this hit as an order/reservation confirmation.
• idcart=: number of the content of this order/reservation.
• cmd=: number of this order/reservation.
• st=: value of order status (see Appendix)
  • “1” for pending order

– This call’s “idcart” parameter must contain the same value as the parameter “cartId” seen previously. This matching enables the linking of the hit to the right visit.
– The parameter “p” must be entered (mandatory), or the hit is ignored.

Certain variables can be modified during the conf1 hit; if this is the case, it’s the variables passed in the conf1 hit that take precedence over those present in the pre1 hit. Only these variables can be modified on the conf1 hit: “cmd” (order number), “roimt” (total), “mtht” (total excluding tax), “mttc” (total including tax), “mp” “(payment method), “st” (order status).

Example in ASP

<% 
'Code corresponding to the database update 
'Example with the ASPHTTP component 
Set HttpObj = Server.CreateObject("AspHTTP.Conn") 
HTTPObj.Url = "http://logxxxx.xxx.com/hit.xiti?s=999999&s2=&p=payment_validated&tp=conf1&idcart=123&cmd=AZ234BG67&st=1" 
strResult = HTTPObj.GetURL 
'Remainder of page code 
%>

– st=1 indicates, for example, that order is in a “Pending” status.

Example in JSP

try{ 
java.net.URL url = new java.net.URL("http://logxxxx.xxx.com/hit.xiti?s=999999&s2=&p=payment_validated&tp=conf1&idcart=123&cmd=AZ234BG67&st=1"); 
((java.net.HttpURLConnection)url.openConnection()).getResponseMessage(); 
} 
catch(Exception ex){ }

Example in PHP

<?php 
$url = "http://logxxxx.xxx.com/hit.xiti?s=999999&s2=&p=payment_validated&tp=conf1&idcart=123&cmd=AZ234BG67&st=1&idtransact=2435242533"; 
$fd = fopen($url, "r"); 
fclose($fd); 
?>

 

Update orders

The update tag allows you to adjust your turnover and take into account changes in status and in order totals following the purchase process on your site (orders made by cheque, returns, changes in price or in pledged amounts, etc.)

Contrary to the server-side tag, an order can be updated 60 days after the order is taken into account. Beyond this period, the update request will be ignored.

Here is the tag:

http://[LOG].xiti.com/hit.xiti?typehit=updateorder&s=[NUMSITE]&guid=[GUID]&cmd=[NUMCD]&st=[ETAT]&roimt=[MONTANT]&mtht=[MONTANTHT]&mtttc=[MONTANTTTC]

These are the different parameters of this tag:

• s=: level 1 site ID.
• s2=: level 2 site in which the “page” must be classified.
• cmd=: order number value
• st=: value of order’s new status (see Appendix)
  • “2” for a cancelled order
  • “3” for a completed order
  • “4” for a returned order
• guid=: unique number defined per site and available in the tag setup via the Digital WorkSpace
• roimt=: new order total (roimt)
• mtht=: new order total without tax
• mtttc=: new order total with tax

The parameters “s”, “log” and “typehit” must not be changed.

The status and the total can be modified independently from one another. It is thus possible to correct a total without influencing the status of the order, and vice-versa.

Additionally, if one of the 3 total fields has been filled out, then all 3 totals will be updated in the available data in your interface.

The update tag applies only to primary goals with order number.

 

Appendix

 

Appendix: tagging rules

• Avoid “space”-type special characters and accented letters.
• If one of the text fields contains a space, the hit is ignored. Consequently, the order is not indicated in the database.
• Field labels should not contain special characters. If a label already exists for a given ID, the labels encoutered afterwards will not be saved.
• Label size:
  Order reference: 50 characters.
  All totals entered in the tagging are truncated to 2 figures after the separator and are considered valid if they are inferior to 999,999,999.99. Beyond this, the entered total will be considered as equal to 0.

 

Appendix: identifiers for payment methods and order statuses

Below label/identifier correspondences for payment methods.
It is possible to enrich this list with your own payment methods in configuration part of your interface.

Identifier	Label	Category
1	Credit card	Bank cards
2	Visa	Bank cards
3	MasterCard	Bank cards
4	Cheque	Cheque
5	Store credit cards	Credit cards
6	Financing	Credit cards
7	Wire transfer	Bank transfer
8	Direct debit	Direct debit
9	PayPal	Electronic money

Below label/identifier correspondences for order statuses.

Identifier	Label
0	No information
1	Pending
2	Cancelled
3	Approved
4	Returned

Last update: 03/03/2020