IMRG Peermap API Documentation V 5.0

(1)

1 | peermap.com IMRG Peermap Documentation

IMRG Peermap API Documentation V 5.0

An Introduction to the IMRG Peermap Service ... 2

Using a Tag Manager ... 2

Inserting your Unique API Key within the Script ... 2

The JavaScript Snippet... 3

Adding the Test API Key ... 3

Insert the following code to use our JavaScript API key ... 3

API Functions ... 3

API Functions Reference ... 3

Calling the API Methods (Examples) ... 4

Addtobasket ... 4

Checkout ... 4

Order ... 5

Calling functions using JavaScript Event Listeners ... 5

Add to basket ... 5

Checkout ... 5

Order ... 5

Testing the JavaScript Implementation ... 6

Testing the Installation using Browser Tools... 6

Using the Test Tool and Test API Key ... 6

The Test Tool and IP Address ... 7

More Information ... 7

Appendix A ... 8

Using Google Tag Manager ... 8

Appendix B ... 14

Using Qubit Opentag ... 14

Appendix C ... 20

(2)

An Introduction to the IMRG Peermap Service

IMRG is leveraging a JavaScript tracking solution. The idea is to track users’ activity on e-retail sites enabling participants to benchmark a series of KPIs against market performance. IMRG tracks a subset of all e-retail website unique visitors by applying sampling rules. Actual daily values (orders, conversion rate and checkout abandonment) are inferred from the sampling results.

The proportion of all users sampled will vary depending on the expected number of website unique visitors, the estimated number of checkouts and daily orders.

In order to select the optimal sampling rate, IMRG may track all unique visitors once the Peermap API has been integrated. When day-on-day variance in website traffic and average daily unique visitors have been evaluated, IMRG reduces the sampling rate. Typically, the initial sampling rate can range from 80% to 100% for retailer participants.

By using a higher sampling rate in the first stage of integration, IMRG can gauge reporting accuracy and estimate sampling error at different sampling rates.

To track visitors to your e-retail website, IMRG uses a JavaScript code snippet which must be added to your tag management system or added to the html body tags on all pages of your website. Three additional snippets must be added to track events; counting baskets, checkouts and orders. These snippets also report basket value and order value when the Peermap API is called.

The aobmp4.js file reference in the JavaScript tag enables visitor session data to be passed to the IMRG database. Stored session data is then made available in your interactive Peermap dashboard in the form of dynamic, user-interactive charts.

The JavaScript API

Adding the JavaScript API & Snippets to the HTML Source Code

The JavaScript (.js) file defines API functions and the code can be included within the head or body tags (i.e. <head></head> or <body></body>). Placing the snippet just before the closing body tag (</body>) will ensure that the code fires once the page is fully rendered in the user’s browser. This JavaScript snippet must be included on every page of your website.

Using a Tag Manager

If you already use a tag manager, then adopt these to add the snippet to your site. You should be able to add the snippet to the head tags within the tag manager and it will be automatically added to every page on your site. You can then set the execution priorities in your tag manager to control the timing of the script execution (i.e. after other .js scripts have run).

For detailed instructions on using Google Tag Manager, Qubit OpenTag and Adobe Dynamic Tag Manager, please refer to the appendices.

Inserting your Unique API Key within the Script

Importantly, you will need to replace the “API-key-goes-here” below with the API key generated by IMRG once the installation has been tested. The API key should be included in the JavaScript (below) on every page of the site.

(3)

The JavaScript Snippet

Adding the Test API Key

IMRG has made available a service allowing participants to test their JavaScript implementation – the IMRG Test Tool. To initialise a session, you will need to satisfy two conditions in the following order:

 The IMRG test key must be inserted in the script (within the ‘push’ parameters) on every page of your eCommerce website as shown below. The IMRG test key is ‘a6z61bz2n5’.

 You must navigate to the Test Tool page (http://www.peermap.com/test-install) and click ‘Go’ to initialise a session.

Insert the following code to use our JavaScript API key

API Functions

API Functions Reference

JavaScript methods should be used on relevant pages of your website to ensure that IMRG is capturing your user session data. The following functions should call the Peermap API on your website for full API integration.

 init – this function initialises or re-initialises the tracker code on the page. The ‘init’ function creates a user cookie and determines whether the user is tracked based on the sampling rule set by IMRG.

The action will be valid for 24 hours; if the user returns to the site within the next 24 hours the ‘init’ function will be called again.

The ‘init’ function should be included and called on every page of your website.

 addtobasket - This method reports items added to the user’s basket – call this method whenever an item is added to a user’s shopping basket. This method is usually called using an event listener such as ‘onclick’ set to fire on every ‘addtobasket’ button on your website.

 checkout – this method reports a checkout. The snippet should be added to the first page of the ‘checkout’ process.

 order – this method reports orders placed – it should be called whenever a user completes an order. It could be included on the page appearing once the transaction is complete (E.g. the page set to thank the customer for their purchase or confirm the order).

(4)

Calling the API Methods (Examples)

In each example below, it is possible to record user actions using a variable or a function.

Addtobasket

The following example demonstrates how to report an ‘addtobasket’ action using the ‘addtobasket’ function. In this example an item with a price of £12.25 is added to the basket.

1. Using a variable: <script type="text/javascript"> var aobmp=aobmp||[];aobmp.push(['addtobasket','12.25']); </script> 2. Using a method: <script type="text/javascript"> aobmppush('addtobasket','12.25'); </script>

Checkout

Note that the checkout order value is not currently supported. 1. Using a variable: <script type="text/javascript"> var aobmp=aobmp||[];aobmp.push(['checkout','0']); </script> 2. Using a method <script type="text/javascript"> aobmppush('checkout','0'); </script>

(5)

Order

The following example demonstrates how to report an ‘order’ action by calling the ‘order’ function. In this example an item with a price of £22.50 is purchased at checkout.

1. Using a variable <script type="text/javascript"> var aobmp=aobmp||[];aobmp.push(['order','22.50']); </script> 2. Using a method <script type="text/javascript"> aobmppush('order','22.50'); </script>

Calling functions using JavaScript Event Listeners

You can also verify that JavaScript methods are called using the ‘onclick’ event for instance as in the examples below.

Add to basket

Checkout

Order

(6)

Testing the JavaScript Implementation

Testing the Installation using Browser Tools

You can test your implementation to see the init API call is succeeding within modern browsers using your browser tools (Google Developer Tools in Chrome or Firebug in Firefox).

Once the API script has been added and configured within the HTML, you can check the cookies file within your browser tools. This allows you to verify that ‘init’ is called on entering the site and cookies are set.

Evaluating the script in debug mode

Developers have the option to use 'debug mode' to evaluate script execution at runtime. Entering debug mode allows for informative popup messages to appear whilst stepping through/running the code. The JavaScript popup displays the aobmp variable, API key and cookies.

As an example, the format of the browser message displayed is: aobmp:checkout,0,addtobasket,20,init,a6z61bz2n5

API Key: a6z61bz2n5

Pcookie:5131e30b-c6ec-f417-7016-1c02415a60a3 TCookie:0

To call the debugger, simply replace the reference to “aobmp4.js” with "aobmp4_debug.js" in the API tag. In debug mode, the API script used is the following:

Using the Test Tool and Test API Key

IMRG has developed a Test Tool available to participants implementing user tracking.

You can use the Test Tool to ensure that the JavaScript cookie reports information on website users’ behaviour once all pages have been tagged.

For use, simply start by adding the test API key to the JavaScript tag. Click 'go' to start the test. The test API key is: a6z61bz2n5.

The test API key is not a unique key and can be used by all members to test tracking. To access the Test Tool, simply navigate to the URL below.

(7)

The Test Tool and IP Address

The Test Tool will record actions as you interact with your website in your browser. It is worth noting that by default the test is specific to your IP address and internet browser also (your IP address is detected using an API). To ensure you are able to view actions and values within your browser, you must ensure that the IP address corresponds to your PC/Laptop or Tablet’s IP address. The key-value pairs recorded will not be passed and will thus not be displayed in your browser window if you are using another IP address or have deleted the content in the text box.

More Information

For more information, you can consult our IMRG Frequently Asked Questions. The FAQ is available at

http://www.peermap.com/faq

If you have any further queries, you can also contact us at IMRG support: T: +44 (0) 203 696 0988

(8)

Appendix A

Using Google Tag Manager

Google Tag Manager (GTM) is a free tool that allows you to manage tags (such as tracking and marketing

optimization tags) on your website. You can add and update AdWords, Google Analytics, Floodlight and non-Google tags from the Google Tag Manager user interface instead of editing site code. In this instance we are tracking the Peermap API to track customer item price and order value.

Getting Started

1. Go to https://www.google.com/analytics/tag-manager/ 2. Sign in with your existing Google account

3. Create an account for your company

4. Create a container for your website, e.g. ABC.com to hold all the tags on your site 5. GTM will then generate a Javascript snippet to add to your site

6. Copy-paste this to every page on your site below the <body> tag

Create an AddToBasket Trigger

For this example, AddToBasket will be triggered on clicking a button if the element id is "addtobasket" 1. Within GTM, go to your created container

2. Create a new trigger by clicking the Trigger link on the left hand side

3. Click the New button, then rename the Trigger title, say AddToBasket Trigger 4. Select the Click event

5. Select All Elements from the dropdown under Configure Trigger, click Continue 6. Under Fire On, select Some Clicks button

7. Select Click ID from the dropdown list, select equals from the second dropdown, type in addtobasket in the input field. Please note that if you cannot see Click ID, go to Variables on the left hand side navigation and select the Click ID checkbox under the Clicks panel

(9)

Create a Checkout Trigger

1. Create a new Checkout Trigger

2. Choose Page View event, trigger type Page View

3. Fire on Page URL contains action=checkout (Page URL is a pre-defined option)

Create an Order Trigger

1. Create a new Order Trigger

2. Choose Page View event, trigger type Page View

(10)

Create Peermap Tag

This tag needs to be included in every page. The Api key a6z61bz2n5 is the test key and it needs to be swapped with the live key.

1. WIthin GTM, go to your created container

2. Create a new tag by clicking the Tag link on the left hand side 3. Click the New button

4. Name your tag, e.g. Peermap Tag 5. Click the Custom HTML Tag button

6. Copy-paste in the below code snippet and click Continue button <script type="text/javascript"> var aobmp=aobmp||[];aobmp.push(['init','a6z61bz2n5']);(function(){ var a=document.createElement("script");a.type="text/javascript";a.async=!0; a.src=("https:"==document.location.protocol?"https://":"http://")+ "peermapcontent.affino.com/AfoCustom/Peermap/Log/aobmp4.js"; var b=document.getElementsByTagName("script")[0];b.parentNode.insertBefore(a,b)})(); </script>

(11)

Create AddToBasket Tag

This tag tracks a product price. This tag is triggered when a clicks on the Add to basket button on your site. The Javascript code looks for an element with ID “Price”.

1. Create a new tag and name it AddToBasket for example 2. Select Custom HTML Tag

3. Copy-paste the below code snippet and click Continue button

4. Under Fire On, select More button

5. Choose the AddToBasket Trigger you create and click Save 6. Click Create Tag

(12)

Create Checkout Tag

This tag is triggered when url contains action=checkout 1. Create a new tag and name it Checkout for example 2. Select Custom HTML Tag

3. Copy-paste the below code snippet and click Continue button

5. Choose the Checkout Trigger you create and click Save 6. Click Create Tag

Create Order Tag

This tag tracks the order price. This tag is triggered when the url contains action=order. The Javascript code looks for an element with ID "Order-Total".

7. Create a new tag and name it Order for example 8. Select Custom HTML Tag

9. Copy-paste the below code snippet and click Continue button <script type="text/javascript">

var orderValue = document.getElementById("Order-Total").innerHTML; orderValue = orderValue.replace(/[^0-9.]/g,"");

var aobmp=aobmp||[];aobmp.push(["order",orderValue]);</script>

10. Under Fire On, select More button

11. Choose the Order Trigger you create and click Save 12. Click Create Tag

(13)

Publish

1. Click on Tags or Triggers on the left hand side 2. In the top right, click the Publish button 3. Click the Publish Now button

(14)

Appendix B

Using Qubit Opentag

Qubit Opentag is an open source tag management system. With Opentag, you simply install one tag and then get a dashboard to manage all the other tags you have on the site, it’s free for sites with less than a million page views. In this instance we are using the Peermap API to track customer item price and order value.

Getting Started

1. Go to https://opentag.qubitproducts.com/QDashboard/ 2. Log into your account or register for free

3. Click Create a container to add a new container for your website, enter a Container Name to hold all the tags on your site

4. Click on the < /> Embed button, copy-paste the code snippet provided to add to your site

5. Make sure that the Qubit Opentag is implemented in the <head> block of your pages to minimize page load time. For best results, Opentag must be implemented on all pages

The Qubit Opentag will load asynchronously, this means it will let other assets on the page load in parallel.

Create an AddToBasket Script

For this example, AddToBasket will be triggered when the urk contains "action=addtobasket" 1. Within Qubit, go to your created container

2. Click the Add New Script button 3. Select Custom Script under Script Type 4. Name the script, e.g. Add To Basket Script 5. Select HTML under Script Source

6. Copy-paste the following script into Inline HTML <script>

var productPrice = document.getElementById("Price").innerHTML;

productPrice = productPrice.replace(/[^0-9.]/g,"");aobmppush("addToBasket",productPrice); </script>

(15)

Create a Checkout Script

For this example the Checkout will be triggered when the url contains "action=checkout" 1. Click the Add New Script button

2. Select Custom Script under Script Type 3. Name the script, e.g. Checkout Script 4. Select HTML under Script Source

5. Copy-paste the following script into Inline HTML

(16)

var aobmp=aobmp||[]; aobmp.push(['checkout','0']); </script>

6. Click Save Script button

Create an Order Script

1. Click the Add New Script button 2. Select Custom Script under Script Type 3. Name the script, e.g. Checkout Script

(17)

4. Select HTML under Script Source

5. Copy-paste the following script into Inline HTML

var orderValue = document.getElementById("Order-Total").innerHTML; orderValue = orderValue.replace(/[^0-9.]/g,"");

var aobmp=aobmp||[];aobmp.push(["order",orderValue]); </script>

(18)

Create Peermap Script

This tag needs to be included in every page. The Api key a6z61bz2n5 is the test key and it needs to be swapped with the live key.

1. Within Qubit, go to your created container 2. Click the Add New Script button

3. Select Custom Script under Script Type 4. Name the script, e.g. Peermap Script 5. Select HTML under Script Source

6. Copy-paste the following script into Inline HTML <script type="text/javascript"> var aobmp=aobmp||[];aobmp.push(['init','a6z61bz2n5']);(function(){ var a=document.createElement("script");a.type="text/javascript";a.async=!0; a.src=("https:"==document.location.protocol?"https://":"http://")+ "peermapcontent.affino.com/AfoCustom/Peermap/Log/aobmp4.js"; var b=document.getElementsByTagName("script")[0];b.parentNode.insertBefore(a,b)})(); </script>

(19)

Publish

1. To publish your container, click the Commit button in the box ‘Changes not committed box. 2. Follow the instructions on the popup, type in COMMIT and click the Commit Container button.

(20)

Appendix C

Using Adobe Dynamic Tag Manager

Getting Started

1. Go to https://dtm.adobe.com/sign_in

2. Log into your account

Set Up Web Property

(21)

(22)

(23)

Within the code you will need to either write raw JS to capture the dynamic values or create a data element that will grab the value:

Once the rule is created you will need to save the rule and publish the rule after testing it. Data Elements

(24)

(25)

Page Load Rule (library and confirmation)

Add in relevant conditions:

(26)