🎯 Overview
This document only describes how to install Pixel to work with Shopify Headless storefront; cross domain tracking is yet to be investigated. The store front and checkout needs to be in the same domain for this to work.
Examples:
✅ Store front: qingxinshopifyheadless.tanamonproductions.com/, checkout: qingxinshopifyheadless.tanamonproductions.com/checkout/…
🚫 Store front: YOURDOMAIN.com, checkout: checkout.YOURDOMAIN.com ← checkout page is on a different subdomain
Prerequisite
The customer needs to have Affiliate integration installed in GRIN. See Step 1-4 in this help doc: https://help.grin.co/v1/docs/setting-up-affiliate-tracking-with-shopify
🔧 Technical Background
TLDR; Shopify does not support the infrastructure of using app web pixel (our old way of installing pixel app on the store). We can bypass this by instructing merchant to install Custom Web Pixel.
From Shopify Support agent:
For headless stores, the Shopify native pixel tracking (via Trekkie) currently only loads and tracks events on the checkout and order status pages, not on the headless storefront itself. As a workaround, users are advised to use third-party tools like Google Tag Manager to track events on their headless storefronts. And if the pixel remains disconnected, it might be due to set up issues or permissions.
Currently, Web Pixels, including those integrated via the Pixel App Web Extension API, do not fully integrate with headless or custom storefronts. User using headless/custom storefronts should be aware that pixel support and integration are limited currently, and Shopify intends to explore this area future. However, Web Pixels would probably load by default on any Shopify hosted surfaces (i.e. Checkout).
In contrast, the pixel works properly with traditional Shopify stores (non-headless), where it is integrated via sales channels or apps using Trekkie or the Pixel App Web Extension API. Traditional stores benefit from Shopify's built-in pixel placement and tracking mechanisms.
There are two types of pixel Shopify has: app web pixel and custom web pixel. Our app is the app web pixel, where it gets installed to the merchant’s store when customer connect their Shopify store with GRIN. The advantage of app web pixel is that is does not require merchant to create pixel app manually. However, given the limitation with Shopify’s headless infrastructure, the app web pixel does not work properly.
As a result, we can instruct merchant to install Custom Web Pixel in their store as part of the onboarding steps.
📖 Installation Steps
1. Log in Shopify store as admin, go to Settings > Customer Events
2. Install the Custom Pixel app
a. Click on Add custom pixel, then name it to something like “GRIN Custom Pixel”. Save the name
b. Copy and Paste the below snippet to Code section
const gd='https://affiliate.grin.co/collect',cl='_gLink',ck='_gToken',cc='_gContact',cw='_gAttributionWindow',lp='link_id',kp='token',cp='contact_id',wp='attribution_window',ec='conversion',ep='view',getStorage=async n=>{let v;try{v=await browser.localStorage.getItem(n)}catch{return false}return v},setStorage=async(n,v)=>browser.localStorage.setItem(n,v),getCookie=async n=>{let c;try{c=await browser.cookie.get(n)}catch{return false}return c},setCookie=async(n,v)=>await browser.cookie.set(n,v),send=p=>{let e=btoa(JSON.stringify(p));browser.sendBeacon(gd+'?payload='+e)},bootstrap=async l=>{let p=l.search!==''?new URLSearchParams(l.search):new URLSearchParams(l.hash);for(const[k,v]of p.entries());p.has(lp)&&await setStorage(cl,p.get(lp));p.has(kp)&&await setStorage(ck,p.get(kp));p.has(cp)&&await setStorage(cc,p.get(cp));await setStorage(cw,p.get(wp)||30)},buildEventPayload=async(e,y)=>{e.context.document.location&&await bootstrap(e.context.document.location);let l=await getStorage(cl)||await getCookie(cl),k=await getStorage(ck)||await getCookie(ck),c=await getStorage(cc)||await getCookie(cc),p={};if(k&&c&&l){p={token:k,link_id:l,contact_id:c,event:y,url:e.context.document.location.origin+e.context.document.location.pathname,referrer:e.context.document.referrer,user_agent:e.context.navigator.userAgent};y===ec&&(p.currency=e.data.checkout.subtotalPrice.currencyCode,p.customer_id=e.data.checkout.contact_id,p.order_id=e.data.checkout.order.id,p.checkout_token=e.data.checkout.token,p.total=e.data.checkout.subtotalPrice.amount)}return p};analytics.subscribe('checkout_completed',e=>{buildEventPayload(e,ec).then(p=>{send(p)}).catch(r=>{})});analytics.subscribe('page_viewed',e=>{buildEventPayload(e,ep).then(p=>{send(p)}).catch(r=>{})});
c. Make sure to Save, then Connect. It should look like the following screenshot.
3. Now going back to the Customer events Settings page, you should see the new Pixel, with “Connected” status.
That’s it! Now the affiliate tracking should be working with your Shopify headless store.