BigCommerce tracking pixel instructions
When following these steps, some brands' developers have found it helpful to first review the Generic tracking pixel instructions and then comparing with the BigCommerce-specific instructions in this guide.
This guide will walk you through the steps to install Roster's two tracking pixels, both of which are required to enable roster's sales attribution features, such as link tracking and referral commissions.
Google Tag Manager
We strongly discourage installing Roster's tracking pixels through Google Tag Manager (GTM). More and more browsers and extensions block GTM from loading, thereby blocking Roster's tracking pixels from working.
We recommend installing Roster's tracking pixels directly in your e-commerce platform or website's global theme/template.
Step 1: Get a public access API token
Each of the two tracking pixels require a public access token in order to securely send tracking data from a customer's browser to your Roster account. You can use the same public access token for both tracking pixels.
Log into your Roster account.
Go to the API integration page by clicking on your brand's name in the left-hand navigation, then Integrations > API integration

Copy the newest Public Access Token if one exists, or click New Access Token to create a new one.

Never use Private Access Tokens with Roster's tracking pixels. Public Access Tokens are safe to use in a browser environment, but Private Access Tokens are only intended for server-side usage as they allow full access to all Roster API endpoints.
Step 2: Install the link tracking pixel
Roster's link tracking pixel tracks link clicks from ambassadors' referral links and stores ambassadors' referral link IDs in the browser to track subsequent purchases.
Ensure the person performing the following steps has admin access to your BigCommerce account.
Log into your BigCommerce account.
Navigate to Storefront > Script Manager
Click Create a Script and enter the following values:
- Script name: Roster Link Tracking Script
- Location: Header
- Pages: All pages
- Script category: Analytics
- Script type: Script
Review this article learn more about the BigCommerce Script Manager.
Paste the Javascript tag into the textarea of the new script.
<script type="text/javascript">
window.roster = {
config: {
token: 'PUBLIC_ACCESS_TOKEN',
forceShareableCodeFetch: true
},
onClickTracked: function() {
// Optional callback. See table below for details.
console.log('Click tracked');
},
onCodeRetrieved: function(discountCode) {
// Optional callback. See table below for details.
console.log('Discount code:', discountCode);
},
onError: function(error) {
// Optional callback. See table below for details.
console.error('Roster pixel error:', error);
}
};
</script>
<script async type="application/javascript"
src="https://cdn.rostercdn.com/sa.js"></script>Replace PUBLIC_ACCESS_TOKEN in the Javascript tag with the Public Access Token from Step 1 above.
Save the changes you made to the script.
Verify the link trakcing pixel.
After your have published the changes to your storefront or website, verify that link tracking is working by using an ambassador's referral link from your Roster account.
See Verify installation with Roster's Chrome Extension to speed up the verification process using Roster's Chrome browser extension.
Step 3: Install the order tracking pixel
Roster's order tracking pixel is an order-aware Javascript pixel that needs to be installed on the order confirmation page (the page that loads immediately after a customer completes a purchase.)
Create a new script in Script Manager like you did in Step 2 above.
- Script name: Roster Order Tracking Script
- Location: Header
- Pages: Order confirmation
- Script category: Analytics
- Script type: Script
Copy the following Javascript tag to your clipboard:
See storefront orders in the BigCommerce API reference for information on the order data points referenced in the script below.
<script async type="text/javascript">
// Get the order data from the BC API
async function getOrderData() {
const orderURL = "/api/storefront/orders/" + {{checkout.order.id}};
const response = await fetch(orderURL);
const data = await response.json();
return data;
}
function submitOrder() {
if (sAttribution) {
getOrderData().then((orderData) => {
let orderCoupons = [];
if (orderData.coupons && orderData.coupons.length > 0) {
orderCoupons = orderData.coupons.map((coupon) => coupon.code);
}
// Roster uses subtotalPrice when calculating referral rewards. Most brands subtract discounts from this amount so that they pay commissions on the discounted amount.
let subtotalPrice = orderData.baseAmount;
if (orderData.discountAmount > 0) {
subtotalPrice = subtotalPrice - orderData.discountAmount;
}
// Push orderData to API
sAttribution.set({
orderId: orderData.orderId.toString(),
orderNumber: orderData.orderId.toString(),
discountCodes: orderCoupons,
currency: orderData.currency.code,
subtotalPrice: subtotalPrice,
totalPrice: orderData.orderAmount,
firstName: orderData.billingAddress.firstName,
lastName: orderData.billingAddress.lastName,
email: orderData.billingAddress.email,
});
sAttribution.emitOrder();
});
}
}
var saScript = document.createElement("script");
saScript.addEventListener("load", submitOrder);
saScript.src = "https://sa.getroster.com/sa.js?token=PUBLIC_ACCESS_TOKEN";
var observer = new MutationObserver(function() {
if (document.body) {
document.body.appendChild(saScript);
observer.disconnect();
}
});
observer.observe(document.documentElement, {childList: true});
</script>Paste the Javascript tag into the textarea of the new script.
Replace PUBLIC_ACCESS_TOKEN in the Javascript tag with the Public Access Token from Step 1 above.
Save the changes you made to the script.
Step 4: Verify the installation process
It's imperative that you test the link tracking and order tracking upon completing the above steps.
See Verify tracking pixel installationVerify tracking pixel installation for a video walkthrough and detailed steps and Verify installation with Roster's Chrome Extension.
Event reference for link tracking pixel
Callback | Signature | Description |
|---|---|---|
onCodeRetrieved | function(discountCode) | Called when a discount code is successfully returned from Roster's shareable endpoint. discountCode is a string containing the code to apply. |
onClickTracked | function(click) | Called when a referral click is tracked by the pixel. click is an object containing click details such as referralLinkId, landingPageUrl, referrerUrl, queryParams, utmParams, userAgent, linkSource, linkVariant, characterSet, title, location, externalId, and clickTimestamp. |
onError | function(error) | Called when an error occurs during the shareable endpoint request or a callback error is caught. error is a string or Error object describing what went wrong. |
Config reference for link tracking pixel
Property | Type | Default | Description |
|---|---|---|---|
token | string | "" | Your public access API token. Required. |
forceShareableCodeFetch | boolean | false | Set to true to enable discount code retrieval on non-Shopify storefronts. Required for this integration. |
Need help?
If you have any questions about adding hidden products to product rewards, contact us at [email protected].
