Shopify Headless tracking pixel instructions

11 min

If brand is a Shopify merchant using a headless storefront, you will need to include Roster's link tracking pixel on your storefront web pages to capture link clicks from ambassadors' referral links and, if applicable, apply leakproof codes or shareable codes to customers' sessions.

You will not need to install Roster's order tracking pixel, as that is handled by Shopify's Web Pixel on the order confirmation page.

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 saves ambassadors' referral link IDs in the browser to track subsequent purchases.

Add the following Javascript tags just before the closing </head> tag in your e-commerce platform or website's global template.

<script type="text/javascript">
  window.roster = {
    config: {
      token: 'YOUR_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 YOUR_PUBLIC_ACCESS_TOKEN in the window.roster.config object with the Public Access Token from Step 1 above.

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.

Be sure you install the link tracking pixel in a way that will allow it to run on each page load. This will ensure that regardless of which URL ambassadors share as their referral link, Roster will capture incoming link clicks and store the referral link IDs for purchases made by referred customers.

See Verify installation with Roster's Chrome Extension to speed up the verification process using Roster's Chrome browser extension.

Step 3: 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].