The following guide will provide instructions to install the following integration components.
Click here for instructions regarding Subscription Points.
Click here for instructions to test your integration.
Each section will outline the significant user events that should trigger various scripts. Function and variable definitions are also outlined in each section.
Data Keys
To support your automated campaigns, we pull data from both the website integration and the file/API data feed. Please ensure that the keys used in the website integration match the keys in the data feed.
Table | Key |
SKU | |
Order Number | |
Order Number | |
Email Address |
For example, the order numbers used in the Conversion Tracking component need to match the order number sent in the data feed.
Framework & ltkAsyncListener
All Listrak JavaScript code is dependent on our framework. Use the following script and your unique Merchant ID to load our framework.
To promote faster page loading, we recommend placing this script at the bottom of your HTML body or loading it last if you are using a tag manager.
Framework
<!-- Listrak Analytics - Javascript Framework -->
<script type="text/javascript">
(function (d, tid, vid) {
if (typeof _ltk != 'undefined') return; var js = d.createElement('script'); js.id = 'ltkSDK';
js.src = "https://cdn.listrakbi.com/scripts/script.js?m=" + tid + "&v=" + vid;
d.querySelector('head').appendChild(js);
})(document, 'merchantID', '1');
</script>
Ensure that you replace 'MERCHANTID' with your unique Merchant ID.
Executing component scripts before loading the Listrak framework will result in an error. To prevent this, wrapping your scripts or tags with the following script wrapper will ensure that our framework has finished loading before the code executes and still allows you to place the framework towards the bottom of your page or load it last/later in a tag manager.
ltkAsyncListener
(function(d){if(typeof _ltk=="undefined"){if(document.addEventListener)document.addEventListener("ltkAsyncListener",function(){_ltk_util.ready(d)});else{e=document.documentElement;e.ltkAsyncProperty=0;e.attachEvent("onpropertychange",function(e){if(e.propertyName=="ltkAsyncProperty"){_ltk_util.ready(d)}})}}else{_ltk_util.ready(d)}})(function(){
/********** Begin Custom Code **********/
/********** End Custom Code ************/
});
For example, executing Cart Abandonment may look like this.
(function(d){if(typeof _ltk=="undefined"){if(document.addEventListener)document.addEventListener("ltkAsyncListener",function(){_ltk_util.ready(d)});else{e=document.documentElement;e.ltkAsyncProperty=0;e.attachEvent("onpropertychange",function(e){if(e.propertyName=="ltkAsyncProperty"){_ltk_util.ready(d)}})}}else{_ltk_util.ready(d)}})(function(){
/********** Begin Custom Code **********/
_ltk.SCA.AddItemWithLinks('abc-xs', 1, '5.99', 'Crew Neck Tee', '/media/crewnecktee.jpg', '/crew-neck-tee');
_ltk.SCA.AddItemWithLinks('abc-m', 1, '5.99', 'Crew Neck Tee', '/media/crewnecktee.jpg', '/crew-neck-tee');
_ltk.SCA.Submit();
/********** End Custom Code ************/
});
Conversion Tracking
Conversion Tracking is used to track orders and attach revenue to email campaigns to measure performance. It also signals our system to close a user's activity tracking session for campaigns such as Browse and Cart Abandonment.
Significant Events
📍 Placing an Order
When an order is placed, execute the following script.
_ltk.Order.SetCustomer(emailAddress, firstName, lastName);
_ltk.Order.OrderNumber = orderNumber;
_ltk.Order.ItemTotal = itemTotal;
_ltk.Order.ShippingTotal = shippingTotal;
_ltk.Order.TaxTotal = taxTotal;
_ltk.Order.HandlingTotal = handlingTotal;
_ltk.Order.OrderTotal = orderTotal;
// REPEAT THIS FUNCTION FOR EVERY ITEM PURCHASED
_ltk.Order.AddItem(sku, quantity, price);
_ltk.Order.Submit();
Function and Variable Definitions
SetCustomer()
The SetCustomer() function provides Listrak contact details for the order. Other contact details can be sent to Listrak in the file/API data feed.
_ltk.Order.SetCustomer(emailAddress, firstName, lastName);
Parameter | Type | Description |
emailAddress | String | Purchaser's email address |
firstName | String | Purchaser's first name |
lastName | String | Purchaser's last name |
AddItem()
The AddItem() function attaches each order item to the purchaser's order.
_ltk.Order.AddItem(sku, quantity, price);
Parameter | Type | Description |
sku | String | Product SKU |
quantity | Number | Product quantity |
price | String | Product Price |
Submit()
The Submit() function will submit the order to Listrak
_ltk.Order.Submit();
Variables
Name | Type | Description |
Order.OrderNumber | String | Order |
Order.ItemTotal | String | Item total |
Order.ShippingTotal | String | Shipping total |
Order.TaxTotal | String | Tax total |
Order.HandlingTotal | String | Handling total |
Order.OrderTotal | String | Total amount paid |
Order.Source | String | Order source - Example: 'web' |
Order.Meta1 | String | Custom order-level meta field |
Order.Meta2 | String | Custom order-level meta field |
Order.Meta3 | String | Custom order-level meta field |
Order.Meta4 | String | Custom order-level meta field |
Order.Meta5 | String | Custom order-level meta field |
Tracking Pixel
The following pixel will ensure that we still close a user's activity tracking session when they complete a purchase if the Conversion Tracking component cannot. Place this on your Order Confirmation page.
Replace MERCHANTID with your unique Merchant ID.
<img src="https://fp.listrakbi.com/fp/MERCHANTID.jpg" height="1" width="1" />
Email Capture
Email Capture is used to attach an email address to the onsite activity being tracked by the other components.
It is important to understand the difference between Email Capture and Subscription Points.
Email Capture | Subscription Points |
Used to attach an email address to website activity such as product browsing and cart activity for abandonment emails. | Used to subscribe users who opt into receiving general marketing emails to your primary marketing list. |
Integrated with the ltk.SCA object. | Integrated with either the _ltk.Signup object or our Email REST API. |
Significant Events
📍 Entering an Email Address
Any time a user enters their email address (logging in, signing up for marketing emails, filling out a support form), capture it for use in automated solutions.
In cases where the user may be inputting someone else's email address such as a "refer-a-friend" form, do not capture the email.
The following function accepts an element ID or Name and will attach an event listener to the element.
_ltk.SCA.CaptureEmail(elementIdOrName);
If you want to use your own event listener or already have one in place, you can use the following function to set the data manually.
_ltk.SCA.Update("email", emailAddress);
Function and Variable Definitions
CaptureEmail()
The CaptureEmail() function attaches an event listener to the specified input element.
_ltk.SCA.CaptureEmail(elementIdOrName);
Parameter | Type | Description |
elementIdOrName | String | The email input element's ID or Name attribute. |
Update()
This function is used to manually set the value of the user's email address for Email Capture.
_ltk.SCA.Update("email", emailAddress);Parameter | Type | Description |
emailAddress | String | The user's inputted email address. |
Browse Abandonment
Browse Abandonment tracks what pages and products the user browses so you can send emails encouraging them to return to the website or add the products to their cart.
Significant Events
📍 Browsing a non-product Page
Each page the user browses is tracked automatically when the framework loads. However, when integrating a single-page application, you will not be loading the framework on each virtual page. In those cases, the following function will track the user's page.
This function is only necessary when integrating single-page applications in which the framework is not loaded on each new page.
_ltk.Activity.AddPageBrowse(url); //Passing the URL is not necessary as our function will pull the URL from the page but it may be included if needed.
📍 Browsing a Product Page
When a user browses a product page, use the following function to send Listrak which product they are browsing.
_ltk.Activity.AddProductBrowse(sku);
Function and Variable Definitions
AddPageBrowse()
The AddPageBrowse() function provides Listrak the pages the user browses.
Parameter | Type | Description |
url | String | The currently viewed page URL. This parameter is optional. If excluded, the function will pull the current URL. You can manually pass the URL, however. |
AddProductBrowse()
The AddProductBrowse() function provides Listrak the user's browsed products.
Parameter | Type | Description |
sku | String | Product SKU |
Cart Abandonment
Cart Abandonment tracks the user's cart activity so you can send emails encouraging them to complete their purchase.
Each time the cart is modified, the entire cart contents should be sent to Listrak.
Significant Events
📍 Adding to Cart
When a user adds an item to their cart, execute the following script including all of the items that may already be present in their cart.
// REPEAT THIS FUNCTION FOR EVERY CART ITEM
_ltk.SCA.AddItemWithLinks(sku, quantity, price, title, imageURL, productURL);
// INCLUDE THESE FUNCTIONS ONCE FOR THE CART
_ltk.SCA.Total = total;
_ltk.SCA.Submit();
📍 Removing From Cart
When a user removes an item from their cart, send the remaining cart items to Listrak using the same script above.
📍 Updating Quantity
When a user updates the quantity of one or more items in their cart, send the full cart contents to Listrak using the same script above.
📍 Clearing Cart
When a user clears/empties their cart, use the following script to send the clear cart flag to Listrak.
_ltk.SCA.ClearCart();
Function and Variable Definitions
AddItemWithLinks()
The AddItemWithLinks() function provides Listrak each carted item.
_ltk.SCA.AddItemWithLinks(sku, quantity, price, title, imageURL, productURL);
Parameter | Type | Description | Required |
sku | String | Product SKU | Yes |
quantity | Number | Quantity of product in the cart | Yes |
price | String | Product price | Yes |
title | String | Product title | No - If this data is not available on the front-end, data may be pulled from the product table in Listrak supplied by the file/API data feed |
imageURL | String | Image URL for the product | No - If this data is not available on the front-end, data may be pulled from the product table in Listrak supplied by the file/API data feed |
productURL | String | Link URL for the product | No - If this data is not available on the front-end, data may be pulled from the product table in Listrak supplied by the file/API data feed |
Submit()
The Submit() function will send the cart data to Listrak.
_ltk.SCA.Submit();
ClearCart()
The ClearCart() function will clear the user from the Cart Abandonment queue.
_ltk.SCA.ClearCart();
Variables
Name | Type | Description |
SCA.CartLink | String | The cart link the user should be sent to from the Abandonment email. This can include query parameters that may be necessary for recreating the user's cart if that feature is available on your website. |
SCA.Total | String | Total value of the items in an abandoner's cart. |
SCA.Meta1 | String | Custom cart-level meta field |
SCA.Meta2 | String | Custom cart-level meta field |
SCA.Meta3 | String | Custom cart-level meta field |
SCA.Meta4 | String | Custom cart-level meta field |
SCA.Meta5 | String | Custom cart-level meta field |
Alerts
The Alerts suite allows you to notify customers when products they are interested in are back in stock, drop in price, or are low in inventory.
Significant Events
📍 Browsing a Product
Users can be added to an Alerts queue by browsing a product. If you have already integrated the Browse Abandonment component, no further integration is required.
📍 Adding to Cart
Users can be added to an Alerts queue by adding a product to their cart. When a user adds a product to their cart, use the following function to add them to the Alerts queue.
_ltk.Activity.AddProductAddedToCart(sku);
📍 Signing up for Alerts
Typically used for Back In Stock or Coming Soon campaigns, users can sign up to be added to the queue for a specific product. When the user submits a form requesting to be signed up, use the following function to add them to the queue.
_ltk.Alerts.AddAlertwithIdentifiers({Identifiers:{Email:'EmailAddress',PhoneNumber:'PhoneNumber'}, Sku:'productSKU', AlertCode:'alertCode'});
_ltk.Alerts.Submit();
Function and Variable Definitions
AddProductAddedToCart()
The AddProductAddedToCart() function will add users to Alert queues configured to use the Carted Item action.
Parameter | Type | Description |
sku | String | Product SKU |
AddAlert()
The AddAlert() function will subscribe users to the alert queue assigned to the specified Alert Definition Code.
Parameter | Type | Description |
emailAddress | String | User's email address |
sku | String | Product SKU |
alertCode | String | The Alert Definition Code assigned to the alert settings when configuring the alert. |
Custom Events
Listrak's Custom Events allow you to enter a contact into a journey based on criteria you determine.
The JavaScript call will trigger a journey if at least one valid contact identifier (email address or SMS phone number) is included.
The JavaScript call will trigger a journey if at least one of the data properties specified in the custom event is included.
An error will appear if no data properties match the configured custom event.
_ltk.CustomEvents.submit({
"eventUID":"customeventUID",
"identifiers":[
{
"identifierType":"EmailAddress",
"identifierValue":"emailaddress"
},
{
"identifierType":"PhoneNumber",
"identifierValue":phonenumber
}
],
"dataFields":{
"property1name":"property1textvalue",
"property2name":property2doublevalue
}
});
Testing
Click here for instructions to test your integration.