This tutorial will guide you through installing the Boomtrain Commerce tracker code into your shop. Once installed, the tracker will allow Boomtrain to:
- Track your your users' behavior on your shop
- Send your users personalized messages via email and other channels
- Show personalized content to your users in real time, while they navigate the shop
Install all components of the code documented in this page and be sure to let us know if you need any help along the way.
Installing the Base Tracker Code
The base tracker is the core tracking component of Boomtrain Commerce. Please add it to the <HEAD> section of all your shop's pages, populating the site_hash variable with the value received from your account manager.
<script type="text/javascript">
(function() {
var site_hash = "!! GET VALUE FROM BOOMTRAIN SUPPORT !!";
var domain = "commerce.boomtrain.com"
var ldr = document.createElement('script');
ldr.type = 'text/javascript'; ldr.async = true;
ldr.src = document.location.protocol + '//tr-' +
site_hash.substr(2) + '.' + domain + '/tracker/load/' +
site_hash + '/tracker.js?_=' + (+new Date);
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ldr, s);
})();
</script>
Recommendations:
- Install the code on all pages of your site.
- Place the code in the
<HEAD>section of your pages to ensure quick loading of the widgets for optimum user experience. - If you have more versions of the site (such as desktop site and mobile site) please make sure to install the tracker code on all variants
Using the Helper Widget to Verify Tracked Events
When the base tracker code is correctly installed, it can be used to activate a feature named ”helper widget” that lets you visualize the tracked events. Activate the helper widget by loading any page of your shop adding an extra query string parameter, BoomtrainHelperWidget=1, such as in:
http://www.example.com?BoomtrainHelperWidget=1
If the tracker code is installed correctly you'll see the helper widget displayed in the upper left part of the page.
Clicking the View details link will open a pop-up window showing the last five pageviews with their parameters as recorded by the tracker. The following image shows an example with the details of a shopping cart pageview.
Identifying Users
When you know the ID of the current visitor, please add the following script next to the base tracker code to pass the ID to Boomtrain. At the same time specify whether the user is logged in by populating the customer_logged parameter.
<script type="text/javascript">
var _btcommerce = _btcommerce || [];
_btcommerce.push(['customer_id', 'CUSTOMER ID HERE']);
_btcommerce.push(['customer_logged', 'true/false']);
</script>
When you know additional attributes of the current user (like email address, first name, last name, current subscriptions, etc.), execute the following identify call to pass those attributes as well. For example, if a user signs up for an account or subscribes to a newsletter on your site, you may want to set their email address in our system. All attributes set here will be visible in BME under User Properties.
If you choose not to use this call to synch email address with customer_id, you can alternately use a User Feed to accomplish the same task.
<script>
var _btcommerce = _btcommerce || []
_btcommerce.push(["custom_event","identify",{
"customer_id": "same as customer_id call", // subscriber.uid
"email": "[email protected]", // subscriber.contacts[] ... as type email
"first_name": "John", // subscriber.first_name
"last_name": "Smith", // subscriber.last_name
"name": "John Smith", // subscriber.name
"newsletter1subscriber": true, // subscriber.newsletter1subscriber
"other": "attribute", // subscriber.properties.other
//....
}])
</script>
Identifying Page Types
To help the Boomtrain Commerce tracker correctly identify the types of tracked pages, add the following code snippet populating the page_type variable with the the type of page on which the tracker loads.
<script>
// Please add this script to identify known page types
var _btcommerce = _btcommerce || [];
_btcommerce.push(['page_type', '!! CHECK DOCUMENTATION FOR VALID VALUES !!']);
</script>
The possible values of page_type are the following:
| value of page_type | corresponding page |
|---|---|
| homepage | the shop's homepage |
| product | product pages |
| product_listing | category and search pages |
| shopping_cart | shopping cart pages |
| checkout_in_progress | checkout pages |
| checkout_finalized | order confirmation pages |
| pseudo_checkout | checkout substitute pages such as Contact Seller (only for sites that have no real checkout pages such as classifieds sites) |
| other_content | non-product content pages such as articles and blog entries |
After adding the code, you can use the helper widget to verify that Boomtrain receives the page_type data correctly.
Tracking Shopping Cart Events
Please add the following code to any page that can affect the cart. This is necessary for accurate tracking of the visitor’s shopping cart. After adding the code, use the helper widget to verify that Boomtrain receives the cart data correctly.
<script>
// Please add this script to any pages that modify the shopping cart
var _btcommerce = _btcommerce || [];
_btcommerce.push(['cart', [
{
'url': 'http://url_of_the_item', // Product URL
'item_id': 'product ID or SKU', // Product ID or SKU (optional)
'qty': 'product quantity', // Quantity
'price': 'product price' // Price per unit (float)
},
{
'url': 'http://url_of_the_item', // Product URL
'item_id': 'product ID or SKU', // Product ID or SKU (optional)
'qty': 'product quantity', // Quantity
'price': 'product price' // Price per unit (float)
},
// ... other items
]]);
</script>
If the cart is empty please make sure that the code returns empty value:
<script>
var _btcommerce = _btcommerce || [];
// For every time when the cart is empty
_btcommerce.push(['cart', []]);
</script>
Tracking Conversions
To enable tracking of checkout events, please add the following code to your checkout-finalized pages, populating the variables with the transaction data as indicated. After implementation, please use the helper widget to verify that Boomtrain receives the entire transaction data correctly.
<script>
// Please add this script to your checkout-finalized pages
var _btcommerce = _btcommerce || [];
_btcommerce.push(['checkout_finalized',{
'transaction_id': 'unique_transaction_id', // Transaction ID
'total': 'amount', // Total amount of the finalized transaction
'items':
[
// for every item purchased
{
'url': 'http://url_of_the_item', // Product URL
'item_id': 'product ID or SKU', // Product ID or SKU (optional)
'qty': 'product quantity', // Quantity
'price': 'product price' // Price per unit (float)
}
//, { ... next item
]
}]);
</script>
Tracking Product Pageviews
Please add the following script to each product page, populating the product_id variable with the ID of the product being loaded. The value must be the same as the ID received via the products feed.
<script>
// Please add this script to your product pages
var _btcommerce = _btcommerce || [];
_btcommerce.push(['product_id', 'YOUR_PRODUCT_ID']);
</script>
Tracking Category Pageviews
Please add the following script to each category page, populating the cat variable with the name of the category being displayed. The value must be the same as the category names in products feed.
<script>
// Please add this script to your category pages
var _btcommerce = _btcommerce || [];
_btcommerce.push(['cat', 'YOUR_CAT1']); // for level 1 category
_btcommerce.push(['cat', 'YOUR_CAT1', 'YOUR_CAT2']); // for level 2 category
_btcommerce.push(['cat', 'YOUR_CAT1', 'YOUR_CAT2', 'YOUR_CAT3']); // for level 3 category
</script>
Tracking Wishlist Events
If your implementation needs tracking of wishlists, use the code below to push these events to Boomtrain Commerce.
<script>
// Please add this script to your checkout-finalized pages
var _btcommerce = _btcommerce || [];
_btcommerce.push(['wishlist',{
'wishlist_id': 'unique_wishlist_id', // An identifier for the wishlist, ex. "Favorites"
'items':
[
// for every item in the wishlist
{
'url': 'http://url_of_the_item', // Product URL
'item_id': 'product ID or SKU', // Product ID or SKU (optional)
'qty': 'product quantity', // Quantity (optional)
'price': 'product price' // Price per unit (float) (optional)
}
//, { ... next item
]
}]);
</script>
Tracking Product Searches
If your implementation needs tracking of product searches, use the code below in your search pages to push these events to Boomtrain Commerce.
<script>
// Please add this script to your search pages
var _btcommerce = _btcommerce || [];
// Push the searched keyword
_btcommerce.push(['search_kw', 'THE SEARCH KW']);
// Push the filters used
_btcommerce.push(['filters', [
["brand","in",["Brand A", "Brand B"]],
["price","lt",1000],
["price","gt",100],
["color","eq","red"],
["cat", "in", [
["CatA1", "CatA2"],
["CatB1", "CatB2", "CatB3"],
]]
]]);
</script>
Tracking Custom Events
If your implementation needs tracking of custom events, use the code below to push these events to Boomtrain Commerce.
<script>
// Use this script to push custom events to Boomtrain Commerce
var _btcommerce = _btcommerce || [];
_btcommerce.push(["custom_event","EVENT VALUE"])
</script>