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 Using Adobe Dynamic Tag Manager... 20 1 peermap.com IMRG Peermap Documentation
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, userinteractive 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. 2 peermap.com IMRG Peermap Documentation
The JavaScript Snippet <script type="text/javascript"> var aobmp=aobmp [];aobmp.push(['init','api-key-goes-here']);(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)})(); 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 <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)})(); 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). 3 peermap.com IMRG Peermap Documentation
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']); 2. Using a method: <script type="text/javascript"> aobmppush('addtobasket','12.25'); 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']); 2. Using a method <script type="text/javascript"> aobmppush('checkout','0'); 4 peermap.com IMRG Peermap Documentation
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']); 2. Using a method <script type="text/javascript"> aobmppush('order','22.50'); 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 <a href="#" onclick="aobmppush('addtobasket','12.25');">add</a> Checkout <a href="#" onclick="aobmppush('checkout','0');">add</a> Order <a href="#" onclick="aobmppush('order','22.50');">add</a> 5 peermap.com IMRG Peermap Documentation
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: <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_debug.js"; var b=document.getelementsbytagname("script")[0];b.parentnode.insertbefore(a,b)})(); 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. Test API tool: http://www.peermap.com/test-install 6 peermap.com IMRG Peermap Documentation
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 Email: support@imrg.org 7 peermap.com IMRG Peermap Documentation
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 8. Click Save Trigger button 8 peermap.com IMRG Peermap Documentation
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 3. Fire on Page URL contains action=order (Page URL is a pre-defined option) 9 peermap.com IMRG Peermap Documentation
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)})(); 7. Under Fire On, select All Pages and click Create Tag button 10 peermap.com IMRG Peermap Documentation
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 <script type="text/javascript">var productprice = document.getelementbyid("price").innerhtml; productprice =productprice.replace(/[^0-9.]/g,"");aobmppush("addtobasket",productprice); 4. Under Fire On, select More button 5. Choose the AddToBasket Trigger you create and click Save 6. Click Create Tag 11 peermap.com IMRG Peermap Documentation
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 <script type="text/javascript">var aobmp=aobmp [];aobmp.push(["checkout",0]); 4. Under Fire On, select More 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]); 10. Under Fire On, select More button 11. Choose the Order Trigger you create and click Save 12. Click Create Tag 12 peermap.com IMRG Peermap Documentation
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 13 peermap.com IMRG Peermap Documentation
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); 7. Click Save Script button 14 peermap.com IMRG Peermap Documentation
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 <script> 15 peermap.com IMRG Peermap Documentation
var aobmp=aobmp []; aobmp.push(['checkout','0']); 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 16 peermap.com IMRG Peermap Documentation
4. Select HTML under Script Source 5. Copy-paste the following script into Inline HTML <script> var ordervalue = document.getelementbyid("order-total").innerhtml; ordervalue = ordervalue.replace(/[^0-9.]/g,""); var aobmp=aobmp [];aobmp.push(["order",ordervalue]); 6. Click Save Script button 17 peermap.com IMRG Peermap Documentation
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)})(); 7. Click Save Script button 18 peermap.com IMRG Peermap Documentation
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. 19 peermap.com IMRG Peermap Documentation
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 Create Event Rule (add to basket) 20 peermap.com IMRG Peermap Documentation
Add in your conditions and selectors 21 peermap.com IMRG Peermap Documentation
Then add JavaScript to the rule: 22 peermap.com IMRG Peermap Documentation
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 23 peermap.com IMRG Peermap Documentation
Then add custom code: 24 peermap.com IMRG Peermap Documentation
Page Load Rule (library and confirmation) Add in relevant conditions: Add custom code: 25 peermap.com IMRG Peermap Documentation
26 peermap.com IMRG Peermap Documentation