This document will help you set up our Grow (Collection, Revenue tracking) and Reclaim (Add to Cart, Viewed Product) products in BigCommerce.
By following this guide, you'll be ready to:
Collect Grow contacts
Prevent collecting known contacts by suppressing them
Record revenue generated from Grow
Collect abandonment events from Reclaim
For information on suppression, please refer to our suppression documentation here.
Set up Grow
This section is here to help you quickly set up and use Retention's collection and revenue tracking scripts, integral parts of our "Grow" product.
Where to find your Retention.com collection snippet script
Where to find your Retention.com collection snippet script
1. From your Retention Dashboard, click Code Script. Then, click View Your Script.
2. Check the box next to Collection, and then click Copy Code </>. You’ll see a green box in the top right-hand corner telling you the code was copied to your clipboard.
Remember: You can’t check multiple boxes for scripts or you will get an error message. You can only copy one at a time.
3. Once you’ve added the script to your domain, go back to Code Script and click the edit icon next to Authorized Domains.
4. Paste the domain/URL in the text box where you added the script, and click Save Changes.
It will be highlighted in green if the script is properly installed—and in orange if the script is not properly added.
How to add Collection script
1. Log in to your BigCommerce account. From the left navigation, click Storefront.
2. Click Script Manager from the left navigation and then click Create a Script.
3. Name your script, give it a Description (optional), select Header for the placement, select Storefront pages for the location, choose Script under Script type, and paste your Retention.com script in the Script contents box. Click Save.
How to add Revenue Tracking script
You can use your Retention.com's revenue tracking script to capture order information for your Retention.com contacts that land on your BigCommerce page. Tracking codes typically are used on the order status page. Once data is collected, your dashboard will display your week-over-week ROI from your Retention.com contacts.Here's how to add your Retention.com revenue tracking script to your BigCommerce site.
What you'll need
1. You'll need to copy your revenue tracking script from Retention.com. From your Retention Dashboard, click Code Script. Then, click View Your Script.
2. Check the box next to Revenue Tracking, and click Copy Code.
Adding Revenue Tracking to BigCommerce
1. From your BigCommerce dashboard, click Settings > Advanced > Data Solutions. Click the "Connect" button next to Affiliate Conversion Tracking.
2. Paste your Retention.com revenue tracking script into the Conversion Tracking Code box.
3. You will need to replace ORDER_NUMBER, DOLLAR VALUE, and ORDER EMAIL in the code with BigCommerce’s variables.
Replace ##{{ ORDER_NUMBER }} with %%ORDER_ID%%
Replace ##{{ DOLLAR VALUE }} with %%ORDER_AMOUNT%%
Replace ##{{ ORDER EMAIL }} with %%ORDER_EMAIL%%
Click Connect when you’re finished.
Set up Reclaim
This feature can identify viewed products, add to cart, and checkout started events for both unknown, non-logged in users (Grow contacts) and known, non-logged in customers (emails in your Grow suppression list).
What you'll need
Copy the appropriate code block below. This code will be added into your BigCommerce theme and captures key product details to create a payload for Retention Reclaim events.
How does it work?
How does it work?
The code injects key product details into the template through the use of BigCommerce handlebars. The subsequent JavaScript script parses the BigCommerce object and generates a payload for the viewed product and add to cart events.
Upon the DOM being fully loaded, the script initiates the 'Viewed Product Reclaim' event. If an 'Add to Cart' button is present, an event listener is set up to capture the 'addToCart' event when clicked.
Code Block - Viewed Product & Add to Cart
{{inject 'productInfo' product}}
<script defer type="text/javascript">
// grab BigCommerce Data
var jsContext = JSON.parse({{jsContext}});
// create Retention payload object
var vpitem = {
Name: jsContext.productInfo.title,
Price: jsContext.productInfo.price.without_tax.formatted,
ProductID: jsContext.productInfo.id,
Categories: jsContext.productInfo.category[0],
ImageURL: jsContext.productInfo.main_image.data.replace("{:size}", jsContext.productSize),
URL: window.location.href,
Brand: jsContext.productInfo.brand ? (jsContext.productInfo.brand.name ? jsContext.productInfo.brand.name : '') : ''
};
// Output to console in Retention debugger mode only
if (window.location.href.includes('vge=true')) {
console.log("BigCommerce Data", jsContext);
console.log("Payload for Reclaim events", vpitem);
}
// Call Retention Reclaim events once DOM is loaded
document.addEventListener('DOMContentLoaded', function () {
// Call Product Viewed Reclaim event
geq.event('Viewed Product Reclaim', vpitem);
// *NOTE* ---- please use the appropriate selector for the Add to Cart button
// var addToCartButton = document.getElementsByClassName("form-action-addToCart");
var addToCartButton = document.getElementById("form-action-addToCart");
if (addToCartButton) {
addToCartButton.addEventListener('click', function () {
// Output to console in Retention debugger mode only
if (window.location.href.includes('vge=true')) {
console.log("add to cart clicked;");
}
// Call addToCart Reclaim event
geq.addToCart(vpitem);
});
}
});
</script>
Code Block - Checkout Started (Klaviyo)
<script>
document.addEventListener('DOMContentLoaded', function () {
// Fetch cart data from the Storefront Cart API
fetch('/api/storefront/cart', {
method: 'GET',
credentials: 'include', // Include cookies for authentication
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
},
})
.then(response => {
if (!response.ok) {
throw new Error('Failed to fetch cart data');
}
return response.json();
})
.then(data => {
if (data.length === 0) {
console.log('Cart is empty');
return;
}
// Storefront base URL (replace with your store's domain)
const baseUrl = "";
// Access the first cart (in case there are multiple carts)
const cart = data[0];
// Extract necessary variables with PascalCase naming conventions
const CartId = cart.id || ""; // BigCommerce cart ID
const CartAmount = cart.cartAmount || 0; // Total cart amount
const Currency = cart.currency ? cart.currency.code : "USD"; // Currency code
// Fallback checkout URL (static for this BigCommerce store)
const CheckoutUrl = cart.redirectUrls ? cart.redirectUrls.checkoutUrl : `${baseUrl}/cart.php`;
// Transform the cart items into the required PascalCase format
const LineItem = cart.lineItems.physicalItems.map(item => ({
Product: {
Id: item.productId || "",
Url: item.productUrl || `${baseUrl}/products/${item.sku || item.name.replace(/\s+/g, '-').toLowerCase()}`,
Price: {
Amount: item.salePrice || 0,
CurrencyCode: Currency,
},
Title: item.name || "",
Handle: item.sku || "",
Image: {
Src: item.imageUrl || "",
ThumbSrc: item.imageUrl || "", // Assuming the same image is used for thumbnails
},
Vendor: item.brand || "",
Variant: {
Id: item.variantId || "",
Sku: item.sku || "",
Image: {
Src: item.imageUrl || "",
},
Price: {
Amount: item.salePrice || 0,
CurrencyCode: Currency,
},
Title: "",
UntranslatedTitle: "",
}
},
Quantity: item.quantity || 0,
LinePrice: (item.salePrice * item.quantity).toFixed(2),
}));
// Construct the final payload with PascalCase
const payload = {
CartId,
CartAmount,
Currency,
Extra: {
CheckoutUrl,
LineItem,
},
};
// Log the payload to verify
console.log("Payload:", payload);
// Send the payload to Retention if geq is available
if (typeof geq !== 'undefined' && typeof geq.event === 'function') {
geq.event("Checkout Started Reclaim", payload);
} else {
console.log("Retention function not available. Payload:", payload);
}
})
.catch(error => {
console.error('Error fetching cart data:', error);
});
});
</script>
This section pertains specifically to scenarios in which users have the option to add other items to their shopping cart directly from a product page.
If your site does not offer this functionality, you can ignore this section!
Expand to learn more
Expand to learn more
When a user adds another product to their cart directly from a product page, we have two solutions that allow us to capture the Reclaim Add to Cart event.
For the first solution, we implement an event listener to capture this action and subsequently create a temporary cookie in the browser. Upon redirection to the cart, we perform a check to verify the presence of the cookie. If it exists, we utilize the information of the latest item added to the cart to trigger the Reclaim event.
For the second solution, we create a listener for the Big Commerce "cart/add" endpoint and create a payload from that response for the event.
In the picture below, you can see we are on a product page and there are other "related products" that can be added directly to the cart.
Code Snippet 1: Use this if the page redirects after add to cart event
Code Snippet 1: Use this if the page redirects after add to cart event
Where do I add the code?
Insert "Code Block 1" into the product-view.html file, following steps 1 to 3 in the next section outlined below. Subsequently, place "Code Block 2" within Templates -> Pages -> Cart.html.
Code Block 1
{{inject 'productInfo' product}}
<script defer type="text/javascript">
// grab BigCommerce Data
var jsContext = JSON.parse({{jsContext}});
// create Retention payload object
var vpitem = {
Name: jsContext.productInfo.title,
Price: jsContext.productInfo.price.without_tax.formatted,
ProductID: jsContext.productInfo.id,
Categories: jsContext.productInfo.category[0],
ImageURL: jsContext.productInfo.main_image.data.replace("{:size}", jsContext.productSize),
URL: window.location.href,
Brand: jsContext.productInfo.brand ? (jsContext.productInfo.brand.name ? jsContext.productInfo.brand.name : '') : ''
};
// Output to console in Retention debugger mode only
if (window.location.href.includes('vge=true')) {
console.log("BigCommerce Data", jsContext);
console.log("Payload for Reclaim events", vpitem);
}
// Call Retention Reclaim events once DOM is loaded
document.addEventListener('DOMContentLoaded', function () {
// Call Product Viewed Reclaim event
geq.event('Viewed Product Reclaim', vpitem);
// *NOTE* ---- please use the appropriate selector for the Add to Cart button
// var addToCartButton = document.getElementsByClassName("form-action-addToCart");
var addToCartButton = document.getElementById("form-action-addToCart");
if (addToCartButton) {
addToCartButton.addEventListener('click', function () {
// Output to console in Retention debugger mode only
if (window.location.href.includes('vge=true')) {
console.log("add to cart clicked;");
}
// Call addToCart Reclaim event
geq.addToCart(vpitem);
});
}
// This code is for instances where supplementary items are added to the shopping cart directly from a product page.
// *NOTE* --- please use the appropriate selector for the Add to Cart button
var otherProducts = document.getElementsByClassName("button--small card-figcaption-button");
// Convert the HTMLCollection to an array
var otherProductsArray = Array.from(otherProducts);
// Add an click event listener to each product
otherProductsArray.forEach(function (product) {
product.addEventListener('click', function (event) {
// Set a cookie named _geapc that expires in 1 minute
const expirationDate = new Date();
expirationDate.setTime(expirationDate.getTime() + 60 * 1000); // 1 minute
document.cookie = "_geapc=true; expires=" + expirationDate.toUTCString() + "; path=/";
}); // end of click event listener for other products
}); // end of otherProducts check
});
</script><script defer type="text/javascript">
// Check if the "_geapc" cookie exists
if (document.cookie.includes('_geapc=true')) {
// Grab BigCommerce Data
var jsContext = JSON.parse({{jsContext}});
const options = { method: 'GET', headers: { 'Content-Type': 'application/json' } };
fetch(jsContext.secureBaseUrl + '/api/storefront/carts', options)
.then(response => {
if (!response.ok) {
throw new Error("Call to cart failed");
}
return response.json();
})
.then(data => {
if (data.length > 0) {
// Get the last item added to the cart
var lastAdded = data[0].lineItems.physicalItems[data[0].lineItems.physicalItems.length - 1];
// Create new payload for reclaim ATC
var lastItem = {
Name: lastAdded.name,
Price: lastAdded.listPrice,
ProductID: lastAdded.id,
Categories: '',
ImageURL: lastAdded.imageUrl,
URL: lastAdded.url,
Brand: lastAdded.brand ? (lastAdded.brand ? lastAdded.brand : '') : ''
};
console.log(lastItem);
setTimeout(() => {
// Call Reclaim ATC function
geq.addToCart(lastItem);
}, 2000); // 2 second delay before calling the Reclaim ATC function
}
})
.catch(err => console.error(err));
} else {
console.log("Cookie _geapc not found. API call not made.");
}
</script>
Code Snippet 2: Use this if the page doesn't redirect to the cart
Code Snippet 2: Use this if the page doesn't redirect to the cart
Where do I add the code?
Insert "Code Block 3" into the product-view.html file, following steps 1 to 3 in the next section outlined below.
Code Block 3
{{inject 'productInfo' product}}
<script defer type="text/javascript">
// grab BigCommerce Data
var jsContext = JSON.parse({{jsContext}});
// create Retention payload object
var vpitem = {
Name: jsContext.productInfo.title,
Price: jsContext.productInfo.price.without_tax.formatted,
ProductID: jsContext.productInfo.id,
Categories: jsContext.productInfo.category[0],
ImageURL: jsContext.productInfo.main_image.data.replace("{:size}", jsContext.productSize),
URL: window.location.href,
Brand: jsContext.productInfo.brand ? (jsContext.productInfo.brand.name ? jsContext.productInfo.brand.name : '') : ''
};// Output to console in Retention debugger mode only
if (window.location.href.includes('vge=true')) {
console.log("BigCommerce Data", jsContext);
console.log("Payload for Reclaim events", vpitem);
}// Call Retention Reclaim events once DOM is loaded
document.addEventListener('DOMContentLoaded', function () {
// Call Product Viewed Reclaim event
geq.event('Viewed Product Reclaim', vpitem);
// The following code works for ATC when the page is not redirected
(function() {
var originalXHROpen = window.XMLHttpRequest.prototype.open;
window.XMLHttpRequest.prototype.open = function(method, url, async, user, password) {
originalXHROpen.apply(this, arguments);
if (url.includes('/cart/add')) {
this.addEventListener('load', function() {
if (this.readyState === 4 && this.status === 200) {
try {
var item_info = JSON.parse(this.response);
if (item_info && item_info.data && item_info.data.line_items && item_info.data.line_items.length > 0) {
var line_item = item_info.data.line_items[0];
var itemAdded = {
Name: line_item.product_name,
Price: item_info.data.product_value,
ProductID: line_item.product_id,
Categories: line_item.category_names && line_item.category_names.length > 0 ? line_item.category_names[line_item.category_names.length - 1] : '',
ImageURL: item_info.data.cart_item.thumbnail,
URL: item_info.data.cart_item.url,
Brand: line_item.brand_name || ''
};
console.log(itemAdded);
if (typeof geq !== 'undefined' && geq.addToCart) {
geq.addToCart(itemAdded);
}
}
} catch (error) {
if (window.location.search.includes('vge=true')) {
console.error('Error processing XMLHttpRequest response:', error);
}
}
}
});
}
};
})();
});
</script>
Adding Reclaim scripts to BigCommerce
1. In your BigCommerce storefront, go to Themes > Click the "Advanced" dropdown on the current theme > Click "Edit Theme Files"
2. Once you have access to your theme files, proceed to Templates > Components > Products.
🚨 For Checkout Started, please insert the code Templates > Pages > Cart.html
3. In the "products" folder, locate and open the "product-view.html" file. Copy the provided code block from above and paste it into the editor. Save the changes by clicking the button positioned at the bottom right corner of the screen.
4. Verify the functionality of the code by navigating to a product page and activating the Retention debugger. Confirm that the "Viewed Product Reclaim" event is detected and triggered. Additionally, ensure that the "Add to Cart" event is identified, and it should be activated upon adding the product to your cart.
Disclaimer
These scripts attempt to utilize the capabilities offered by BigCommerce and are intended to be lightweight and perform well in the majority of scenarios. We understand that every website is unique and as such, variations may be required by your team.
For support, please contact us at support@retention.com