Tracker, Lead and Order

// Implementation Guide

 

AdAction enables you to manage, deliver and analyze your internet advertising. In order to evaluate online campaigns and optimize current activites based on visitor on-site behaviour AdAction clients need to implement tracking scripts on their web sites. AdAction tracking is based on three types of events:

  • Trackers
  • Orders
  • Leads

Every type of event registers an an action by a visitor and links the action to the advertising campaign statistics.

 

Trackers
A tracker is a generic action by a visitor that does not contain any additional details. Examples of tracker use are:

  • Landing pages
  • Campaign pages
  • Email content

The information registered by a tracker is linked to the client's current advertising campaigns. This will provide information on last viewed ad, last clicked ad, which creative content was displayed etc.

 

Orders
Order tracking enables the client to evaluate media spending and creative designs on the basis of generated orders or even ROI. Additionally when the order tracking is in place clients are able to target customers with specific advertising.

Order tracking requires four parameters:

  • Order number
  • Product group
  • Product name
  • Order value (excluding VAT)

In addition to the required parameters the following information should be included if possible:

  • Order status
  • Number of items
  • Profit margin for the product
  • Currency

One or several different products can be registered at the same time.

 

Leads
Leads are actions where a visitor has taken some active step to indicate interest in the client. Examples of when to use lead trackers are:

  • Product searches or shopping baskets
  • Ordering a mail-out catalog
  • Registration to newsletter

A lead tracker may contain additional data. Extra information may indicate which product and product category the visitor searched for, which catalog was ordered etc.

 

General Conventions
All strings going in or out of AdAction must be in UTF-8.

 

Metadata on Visitors
Encoding of Metadata
AdAction clients can benefit from using visitor metadata to relate AdAction data to internal Data Warehouse data, as well as improving the accuracy of the AdAction tracking. It is important that personally identifiable data is sent to AdAction in an anonymous manner. Sample code indicating how to encode personal metadata is available from AdAction for a number of programming languages. The technology is based on a cryptografic hash (such as MD5) that always compute to the same key given the same input, but is not possible to reverse.

Relevant metadata on visitors include:

  • Phone number
  • Email address
  • Social Security Number
  • Postal Code

All personal identifiers must be encoded before they are sent to AdAction for integrity reasons. E.g. a phone number is a personal identifier while a postal code is not.


Implementing Regular Trackers
Format Options


A regular tracker without metadata may be implemented in a number of ways. The most common implementation is a small HTML-code placed on the client web page where the action should be tracked. It is also possible to register actions in Flash animations or when clicking on links.

The tracker scripts used for the implementation may be downloaded from the AdAction administration or sent to you by email from AdAction staff.

Below are samples of the different tracker formats.
 

HTML
HTML iframe:

<iframe src="http://de17a.com/t/1234.iframe"
        height="1"
        width="1"
       >
</iframe>

HTML <img>:

<img src="http://de17a.com/t/1234.image"
        height="1"
        width="1"
        alt=""
        />

Every tracker contains a unique ID used to indicate which tracking event AdAction should register.

 

Secure Pages
Trackers may be invoked as unsecure (HTTP) or secure (HTTPS). If an unsecure tracker is placed on a secure page, the visitor may get a warning message from the browser. It is important to make sure the method used to invoke the tracker matches the method used to load the page.

<iframe>-trackers are prefered in most cases since an <iframe> is considered a separate window by the browser and will not pause the download of the rest of the page in case of any delays in the tracker.

In order to use an HTML tracker the <iframe>- or <img>-code should be placed anywhere in the HTML-code for the page that is being tracked.

There are no restrictions on where to put the tracker, however the higher up it is on the page the earlier the registration will be performed which will reduce the number of missed invocations.

 

Flash Trackers
If the tracking is performed on a pages build in Adobe Flash the tracker may be called through ActionScript.

ActionScript 2:

var highLayer = 999;
loadMovieNum("http://de17a.com/t/1234.swf", highLayer);
ActionScript 3:
var url:URLRequest = new URLRequest("http://de17a.com/t/1234.swf");
var tracker:Loader = new Loader();
tracker.load(url);
addChild(tracker);

Click Trackers
A tracker may also be used to track click events. When implementing click trackers the final destination adress must be added to the tracker code. To make sure AdAction is able to correctly parse the address it should be URL-encoded. This can easily be done with the JavaScript-function escape().

http://de17a.com/t/1234.click?url=http%3A//www.target-page.com

 

Verifying Trackers
To verify that the tracking is correctly implemented, page views should be tested using a tool that displays http requests. Some tools that can be used are Charles  http://www.charlesproxy.com, or Firebug  http://www.getfirebug.com or Fiddler  http://www.fiddlertool.com. When invoking an <iframe>-tracker the following requests should be logged:

 

http://de17a.com/t/*.iframe

http://de17a.com/t/*.swf or http://de17a.com/t/*.image
http://de17a.com/j/*_a.js (unless already in the browser cache)

When invoking an <img>-tracker the following requests should be logged:

 http://de17a.com/t/*.image

The asterisk (*) indicates a tracker-ID for the tracker being tested.
Implementing Order Trackers

 

Order Example
An order tracker may only be invoked using JavaScript. The tracker contains a control script that defines functions for each client, and the code used to specify each order registration.

A sample of a complete order registration (for a client selling console games):

<script src="https://de17a.com/o/123.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">
  with (OrderRegistration) {
    // Order number
    reference_id = '1234567'; (1)

    // Customer number
    customer_id = 'abc123'; (2)

    // Order status
    status = ACCEPTED; (3)
   
    register({ (4)
      ti: '1234',                              // Tracker ID
      pn: 'PlayStation 3',                     // Product name
      pg: 'Game Consoles',                     // Product group
      va: '3999',                              // Order value (excluding VAT)
      ch: 'ffe7470430a737c4ce6dc74bea0155d5',  // Hash of credit card number
    });

    // visitor metadata
    user({ (5)
      eh: 'ed73f6b46391b95e1d03c6818a73b8b9'
    });
  }
</script>

The first <script>-tag retrieves the control script for client 123. The with (OrderRegistration)-block invokes the order registration in AdAction.

(1)
    Specificies a unique order number that connects several line items to a complete order. Usually the internal order number in the client's online order system. If the client's order system does not create a unique order number it is possible to use a mathematical random value. However the possibility to cross reference orders between AdAction and the client's order system will then be lost.
(2)
    Indicates the customer number for the person placing the order in the client order system.
(3)
    Specify the order status:   

  • ACCEPTED (paid in full)
  • PENDING (booked/not yet paid) 
  • CANCELED (interrupted or cancelled)
  • BOGUS (test order)

(4)
    The register()-function should be called for each kind of product in the order.

  • ti the unique ID of the tracker (generated by AdAction)
  • pn the product name
  • pg the product group
  • va the total value of the products with this product name
  • ch an MD5 cryptographic hash of the customers credit card number used as an anonymous but unique key.

ti, pn, pg and va are required to successfully register the order.
    The register()-function may be invoked serveral times with different products. In addition to the required parameters it may be relevant to use cn (number of the same product), cy (currency) and ma (profit margin). See below for more information.


(5)
    Used to register information on the visitor (refer to visitor metadata for more information)

There are no strict rules for where in the HTML-code the order tracker should be included (<head> or <body>), but just like regular trackers higher up on the pages will likely have fewer lost invocations. The natural position of <script>-tags are in the <head> section.
Currency, Profit Margin, and Number of Products

In addition to the required parameters information on cn (number of products), cy (currency) och ma (profit margin) may be included. If not specified the default values are (cn) = 1 indicating a single item, (cy) = default currency configured for the client in AdAction, (ma) = 1.0, indicating that the whole price of the product should be considered profit.


Conventions

To ensure the tracker data is as correct as possible please use the following conventions.

  • Always indicate order value exluding consumer tax (VAT)
  • Make sure product names and product groups are consistent and not changed frequently as they are included in some AdAction reports.
  • If profit margins are available they should be included to provide correct ROI numbers in AdAction reports.

Testing Order Registration
In order to easily verify that the invocation has been registered an extra test script may be added to the page. When the order tracker is successfully invoked the test script will display a red box indicating the values that were registered:

<script src="https://de17a.com/d/debug.js" type="text/javascript" charset="utf-8"></script>
<script src="https://de17a.com/o/123.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">
  with (OrderRegistration) {
    // Ordernummer
    reference_id = '1234567';

        // Order number
    customer_id = 'abc123';

    // Order status
    status = ACCEPTED;
   
    register({
      ti: '1234',                               // Tracker ID
      pn: 'PlayStation 3',                      // Product name
      pg: 'Game Consoles',                      // Product group
      va: '3999',                               // Order value(excl. VAT)
      ch: 'ffe7470430a737c4ce6dc74bea0155d5'    // Hash of credit card number
    });
   
    register({
      ti: '1234',                               // Tracker ID
      pn: 'Fallout 3',                          // Produkt name
      pg: 'Video Games',                        // Produkt group
      va: '599',                                // Order value(excl. VAT)
      ch: 'ffe7470430a737c4ce6dc74bea0155d5'    // Hash of credit card number
    });
   
    register({
      ti: '1234',                               // Tracker ID
      pn: 'Playstation 3 Wireless Controller',  // Product name
      pg: 'Game Consoles',                      // Product group
      cn: '2',                                  // Product count
      va: '499',                                // Order value(excl. VAT)
      ch: 'ffe7470430a737c4ce6dc74bea0155d5'    // Hash af credit card number
    });

    // visitor meta data
    user({
      eh: 'ed73f6b46391b95e1d03c6818a73b8b9'
    });
  }
</script>

Debug information when testing order registration

In this example four line items are registered in a single order. One Playstation 3 console, one game and two wireless controllers. When the test script is included the red box above is displayed. Make sure that the test script does not remain on the page in the production release.

 

Implementing a Lead Tracker
Lead Trackers
The lead trackers are invoced similar to order trackers, but contain fewer parameters. A lead tracker used to indicate signups to a newsletter may look like this.

<script src="https://de17a.com/o/123.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">
  with (LeadRegistration) {
    // Customer number
    customer_id = 'abc123';
       
    register({
      ti: '1234',                        // Tracker ID
      pn: 'Newsletter (new products)',   // Lead name
      pg: 'Newsletter'                   // Lead group
    });

    // Visitor metadata
    user({
      eh: 'ed73f6b46391b95e1d03c6818a73b8b9'
    });
  }
</script>

Just like order registrations there are no strict rules on where to place the script on tha page ( <head> or <body>). The same test script used for order registration may be used to test lead trackers.

 

Visitor Metadata
Registration of visitor information
Visitor metadata should be provided both for lead an order trackers. To secure the anonymity and integrity of the visitor AdAction requires certain parameters to be encoded in a way that AdAction is not able to deduce the original information. The available parameters are:

  • eh: email address (encoded)
  • th: phone number (encoded)
  • mh: mobile number (encoded)
  • sh: social security number (encoded)
  • on: organization number
  • po: postal area
  • pc: postal code
  • co: company name
  • cc: company industry
  • cn: country

There are no requirements on which information to register. For a newsletter signup only the email address may be available. When registering orders most information should be available.

<script src="https://de17a.com/o/123.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">
  with (LeadRegistration) {
    // Vanlig lead-implentation
    register({ ... });

    user({
        eh: 'ed73f6b46391b95e1d03c6818a73b8b9',  // Email Hash
        th: '941bd222bdc6ab667efb2445627e7603',  // Phonenumber Hash
        mh: 'f5a1c6244fb3ab568075734d71205439',  // Mobile phonenumber Hash
        sh: '02d55ef0d7fdcc6ee5ada72f392b7702',  // Social security number Hash
        pc: '12139'                              // Postal Code
    })
  }
</script>

Code samples on how visitor metadata should be anonymized in a secure way are available in a number of programming languages and will be provided along with the tracking scripts from AdAction:

  • PHP
  • Ruby
  • Python
  • Java
  • C#

Pending orders

Orders with status "PENDING" can be rechecked by AdAction to make sure that only accepted orders is getting credit in statistical reports. This can for example be when the web application that handles your orders do not make credit control online or when your customer pays by invoice.

AdAction calls one URL each day using POST with orders that is still marked as PENDING in the system. The clients system then responds with updated status of the orders, if any. If the order is still in an unknown state, it should either be left out or marked as "PENDING". The response is a minimal xml response with updated status per order.

Unless no action has been made on a pending orders status, it will be marked as ACCEPTED after 7-30 days, depending on factors told by the client.

The security is handled by HTTP Basic-auth, which is recommended to be strengthened by using encrypted SSL certificates.

The status codes is returned in numbers:
0: Pending
1: Accepted
2: Cancelled

Example in PHP:

<?php
 $order_ids = explode(',', $_POST['order_ids']);
 echo "<?xml version='1.0'?>\n";
 echo "<orders>\n";
 foreach ($order_ids as $order_id) {
  switch(order_status($order_id)) {
   case "ok":
    $status = 1;
    break;
   case "aborted":
    $status = 2;
    break;
   case "waiting_for_money":
   default:
    $status = 0;
  }
  echo "\t<order id='{$order_id}' status='{$status}' />\n";
 }
 echo "</orders>";
?>

The response should result in an xml according to the following when an order with identifier "REF123" has been accepted and an order with identifier "REF005" has been cancelled.

<?xml version="1.0"?>

<orders>

    <order id="REF123" status="1" />

    <order id="REF005" status="2" />

</orders>

Introduction

See examples of trackers in html, flash and click

Verifying tracker calls

Examples of order, lead and meta data

Pending orders