Starting July 1st 2023, this application will no longer be maintained by VTEX. The VTEX repository shall remain archived private and unchanged with the original version. Please don't share this repository with anyone external to VTEX. Internal questions only for VTEXers in this Slack channel.
---
📢 Use this project, contribute to it or open issues to help evolve it using Store Discussion.
Listrak
This app provides pixel integration for Listrak metrics and cart abandonment functionality, and provides related routes and blocks for use in an account's store-theme.
Additionally, if you would like the app to send Order, Product, and Customer data to Listrak, you can create a Listrak Data Integration.
Configuration
- Install the
listrak-pixelapp in the desired account; - In the account's admin, access Apps > My Apps and then select the Listrak box;
- Once in the app's page, define the app’s configurations in the Setup section:
-
Merchant ID: Input your Listrak Merchant ID here.
-
Subscription Point ID: Input your
Subscribe IDof the email Subscription Point from your Listrak account. -
Subscription Form IDs: To capture a shoppers opt-in to an email subscription, enter the field IDs associated with the subscription form email input and submit button. Enter both IDs separated with commas and no spaces like
emailInputId,submitButtonId. If the Newsletter block from thevtex.store-componentis used, no entry is necessary. -
Email Input Field IDs: Listrak's cart abandonment feature works in part by capturing email addresses when shoppers type them into certain fields. These field IDs can be specified here, separated with commas and no spaces like
emailField1,emailField2. -
Preference Center Name: This app creates a new store route with the path
/preference-centerwhich displays the Listrak Preference Center. Referencing your Listrak Preference Center integration instructions, input the value for thedata-ltk-prefcenterattribute of the Preference Center div here.
The settings below are only needed if you have created a Listrak Data Integration.
-
Client ID: Your Listrak Data Integration Client ID.
-
Client Secret: Your Listrak Data Integration Client Secret.
-
Full Catalog Import: Send your entire product catalog to Listrak. This will happen on the first SKU update after enabling the option.
-
Use SKU Reference ID: Send Listrak SKU reference IDs instead of VTEX SKU IDs.
-
Image Size (in pixels): Set dimensions for images imported to Listrak. If left blank, the default size for your store's thumbnail images wil be used, usually 100x100 pixels.
Listrak Fields and Values (Optional)
The following optional settings allow you to map VTEX product specifications to specific Listrak fields. If left blank, they will be filled according to the default behavior explained below:
-
Category: Input the name of the product specification field containing the product's main category. If left blank, this will be automatically set as the first category that the product belongs to.
-
Sub Category: Input the name of the product specification field containing the product's secondary category. If left blank, this will be automatically set as "Type/Silhouette".
-
Meta 1: Input the name of the product specification field containing any additional data you wish to send. If left blank, this will be automatically set as a pipe-separated list of the item's unique SKU specifications.
-
Meta 2: Input the name of the product specification field containing any additional data you wish to send. If left blank, this will be automatically set with a placeholder value of "meta_2".
-
Meta 3: Input the name of the product specification field containing any additional data you wish to send. If left blank, this will be automatically set with a placeholder value of "meta_3".
(Optional) On-Site Recommendation Integration Block
To use this optional block in your store-theme, you must add the Listrak app to your store-theme's peer dependencies in manifest.json:
_10"peerDependencies": {_10 "vtex.listrak-pixel": "1.x"_10 }
Then you may use this block in your layouts:
"listrak-recommendations": The Listrak app provides this block which is designed to be added to the product page (store.product). It renders Listrak's On-Site Recommendations product shelf. The block takes two props:
| Prop name | Type | Description |
|---|---|---|
merchandiseBlockId | String | The Merchandise Block ID from Listrak's admin. Default: '' |
templateHTML | String | The HTML template for the recommender from Listrak's admin. Default: '' |
:warning: Both props must be filled for the component to render.
Example - Listrak provides sample template code that looks like this:
_12<div_12 data-ltk-merchandiseblock="sample-merchandise-block-id"_12 style="width:100%; padding:40px 0;"_12>_12 <script type="text/html">_12 <div style="box-sizing:border-box; vertical-align:top; display:inline-block; width:25%; padding:20px;">_12 <a href="@Recommendation.LinkUrl"><img src="@Recommendation.ImageUrl" title="@Recommendation.Title" style="display:block; width:auto; height: 100%; max-height:200px; margin:auto;"/></a>_12 <a href="@Recommendation.LinkUrl" title="@Recommendation.Title" style="display:block; width:100%; font-family:Segoe UI,Roboto,Helvetica Neue,sans-serif; font-size: 15px; font-weight: 500; color:#333;text-decoration:none; text-align:center; padding-top:8px;">@Recommendation.Title</a>_12 <a href="@Recommendation.LinkUrl" title="@Recommendation.Title" style="display:block; width:100%; font-family:Segoe UI,Roboto,Helvetica Neue,sans-serif; font-size: 13px; font-weight: 700; color:#d43e3e; text-decoration:none; text-align:center; padding-top:8px;">$@Recommendation.Price</a>_12 </div>_12 </script>_12</div>
In this case, your block's props would look like this:
_10"listrak-recommendations#example": {_10 "props": {_10 "merchandiseBlockId": "sample-merchandise-block-id",_10 "templateHTML": "<div style='box-sizing:border-box; vertical-align:top; display:inline-block; width:25%; padding:20px;'><a href='@(window.location.origin + Recommendation.LinkUrl)'><img src='@Recommendation.ImageUrl' title='@Recommendation.Title' style='display:block; width:auto; height: 100%; max-height:200px; margin:auto;'/></a><a href='@(window.location.origin + Recommendation.LinkUrl)' title='@Recommendation.Title' style='display:block; width:100%; font-family:Segoe UI,Roboto,Helvetica Neue,sans-serif; font-size: 15px; font-weight: 500; color:#333;text-decoration:none; text-align:center; padding-top:8px;'>@Recommendation.Title</a><a href='@(window.location.origin + Recommendation.LinkUrl)' title='@Recommendation.Title' style='display:block; width:100%; font-family:Segoe UI,Roboto,Helvetica Neue,sans-serif; font-size: 13px; font-weight: 700; color:#d43e3e; text-decoration:none; text-align:center; padding-top:8px;'>$@Recommendation.Price</a></div>"_10 }_10},
:warning: Note that the HTML has all been combined into a single line, and double quotes " replaced with single quotes '.
:warning: Also note that each @Recommendation.LinkUrl has been replaced with @(window.location.origin + Recommendation.LinkUrl). This is because the LinkUrl stored for each product in Listrak is a relative URL. ImageUrl does NOT need this same treatment because each ImageUrl is already an absolute URL.
Checkout Integration
To finalize a Listrak integration, custom JS code must be added to checkout in the checkout6-custom.js file:
_62// Listrak_62$(document).ready(function() {_62 var prevItems = []_62 $(window).on('orderFormUpdated.vtex', function(evt, orderForm) {_62 ;(function() {_62 if (typeof _ltk == 'object') {_62 ltkCode()_62 } else {_62 ;(function(d) {_62 if (document.addEventListener)_62 document.addEventListener('ltkAsyncListener', d)_62 else {_62 e = document.documentElement_62 e.ltkAsyncProperty = 0_62 e.attachEvent('onpropertychange', function(e) {_62 if (e.propertyName == 'ltkAsyncProperty') {_62 d()_62 }_62 })_62 }_62 })(function() {_62 ltkCode()_62 })_62 }_62 function ltkCode() {_62 _ltk_util.ready(function() {_62 _ltk.SCA.CaptureEmail('client-pre-email')_62 if (JSON.stringify(orderForm.items) != JSON.stringify(prevItems)) {_62 if (orderForm.items.length > 0) {_62 orderForm.items.forEach(item => {_62 _ltk.SCA.AddItemWithLinks(_62 item.id,_62 item.quantity,_62 (item.price / 100).toString(),_62 item.name,_62 item.imageUrl,_62 item.detailUrl_62 )_62 })_62 _ltk.SCA.Submit()_62 } else {_62 _ltk.SCA.ClearCart()_62 }_62 prevItems = orderForm.items_62 }_62 })_62 }_62 })()_62 })_62})_62var biJsHost = 'https:' == document.location.protocol ? 'https://' : 'http://'_62;(function(d, s, id, tid, vid) {_62 var js,_62 ljs = d.getElementsByTagName(s)[0]_62 if (d.getElementById(id)) return_62 js = d.createElement(s)_62 js.id = id_62 js.src =_62 biJsHost + 'cdn.listrakbi.com/scripts/script.js?m=' + tid + '&v=' + vid_62 ljs.parentNode.insertBefore(js, ljs)_62})(document, 'script', 'ltkSDK', 'LISTRAK-MERCHANT-ID', '1')_62// end Listrak
:warning: Make sure to replace 'LISTRAK-MERCHANT-ID' in the second-to-last line with your Listrak Merchant ID. No other customizations are needed.
Listrak Data Integration
Enabling this feature will send additional Order, Customer, and Product data to listrak.
- Orders data is sent when an order has been invoiced and/or updated if canceled.
- Customer data is sent when the order is invoiced.
- Product data is sent when a SKU has been created or updated.
To provide additional data to Listrak, you will need to create a new integration from the Listrak application and allow access to the Listrak API. Listrak provides some instructions here.
Access Levels
The app supports sending Order, Customer, and Product data and will need these access levels selected.
IP Address Whitelist
There are three possible IPs the app may use to send data to the Listrak API, these will need to be added to the integration's whitelist.
- 34.199.112.14
- 107.23.210.212
- 52.73.206.45
Customization
In order to apply CSS customizations to this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.
| CSS Handles |
|---|
recommendations |