Track visitors, campaigns, and purchases on a Shopify store with the Linkrunner Web SDK
Shopify stores need the Web SDK installed in two places, because Shopify does not
allow scripts on the checkout and thank-you pages. Your storefront gets a script tag;
your checkout gets a custom pixel.Once both are in, every purchase is linked back to the ad, campaign, or link that
brought the shopper in.
This takes about 30 minutes and needs no developer access to your servers. Everything
is done from your Shopify admin.
Go to Settings → Domains in your Shopify admin. Your checkout must run on your
own domain (for example checkout pages under yourstore.com) for the purchase to
be linked to the shopper’s browsing session.Most Shopify stores are already set up this way. If your checkout runs on
yourstore.myshopify.com while your storefront is on yourstore.com, Step 3 below
is required rather than optional.
Get your Web SDK token
Web attribution is in beta, so tokens are issued by us. Email
support@linkrunner.io with your project name and
store domain, and we’ll send you a Web SDK token.
Back up your theme
Step 2 edits your theme’s code. In Online Store → Themes, use Actions →
Duplicate on your live theme first, so you can roll back instantly.
Click Save. This tracks page views, traffic sources, campaigns, and ad clicks
across your storefront.
2
Pass the visitor ID into the cart
In the same layout/theme.liquid file, paste this directly below the script you
just added:
<script> document.addEventListener("DOMContentLoaded", function () { var vid = localStorage.getItem("lr_vid"); if (!vid) return; fetch("/cart/update.js", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ attributes: { lr_vid: vid } }), }).catch(function () {}); });</script>
This attaches the visitor’s ID to their cart so the purchase can still be matched
if checkout happens on a different domain, which is what Shop Pay does. Click
Save.
Strictly optional if your checkout is on your own domain and you don’t use Shop
Pay. We recommend adding it anyway: it costs nothing and removes a whole class
of missing-attribution problems.
3
Add the checkout pixel
Go to Settings → Customer events → Add custom pixel. Name it Linkrunner.
This is a new, separate pixel. Do not paste this code into a pixel you already
have. Each custom pixel runs in its own sandbox, so any existing pixels (Google
Analytics, Meta, and so on) keep working and should be left untouched.
Settings → Customer events (1), then Add custom pixel (2)
The code box arrives pre-filled with Shopify’s commented placeholder starting
// Step 1. Initialize the JavaScript pixel SDK. Select all of it and delete it, then
paste the code below and replace YOUR_WEB_SDK_TOKEN with the token from Step 1.
Replace the placeholder in the Code box (1). Connect (2) is the button you press after saving.
The empty catch at the end is deliberate. A custom pixel must never throw, because
an error there can interrupt the checkout. Failures are swallowed silently, which is
why you verify with the steps below rather than by watching for errors.
This sends your shoppers’ email and phone to Linkrunner. They are what link a
purchase to an identifiable person, so audience exports and person-level reporting
depend on them.Make sure your privacy notice covers sharing customer contact details with
Linkrunner and your data processing agreement with us is in place. If you would
rather not send them, comment out the email and phone lines in event_data.
Attribution, campaign reporting, and revenue all work without them; you lose
person-level audiences.
Above the code box, check the two Customer privacy settings. The defaults are
already right for Linkrunner, so in most cases you are confirming rather than changing:
Permission: leave Required selected, with Marketing and Analytics
ticked. Analytics covers page views and sessions; Marketing covers the ad click IDs
and campaign data that attribution depends on. Preferences is unused, leave it
unticked.
Data sale: leave Data collected qualifies as data sale selected. The pixel
then stops collecting for shoppers who opt out of having their data sold.
Leave Required selected (1) with Marketing and Analytics ticked (2), and leave the default Data sale option (3)
Choosing Not required makes the pixel collect regardless of consent. That is a
legal decision about the markets you sell in, not a technical one. Check with whoever
handles privacy at your company before changing it.
Click Save, then click Connect.
Save and Connect are two separate actions. A saved but unconnected pixel looks
installed and never runs. This is the single most common reason purchases don’t
appear.
4
Verify it works
Visit your store with test campaign parameters, for example
https://yourstore.com/?utm_source=meta&utm_medium=cpc&utm_campaign=test
Browse a product, add it to the cart, and complete a real order
You should see page views for the visit and a purchase event carrying the order
value, all attributed to utm_campaign=test.
Refund the test order afterwards. Refunding does not remove the tracked event, which
is what you want, because you are confirming tracking, not revenue.
Please read these before going live. Most are Shopify platform behaviour, not Linkrunner
settings, and cannot be worked around.
Shop Pay checkouts run on a different domain
When a shopper checks out with Shop Pay, the checkout is served by shop.app, not
your store. Browser security prevents the pixel from reading anything your storefront
saved.The cart-attribute snippet in Step 2 is what keeps these purchases attributed. If
you use Shop Pay, Step 2 is required.
The pixel only runs on your published theme
Custom pixels do not run in theme preview links. Test on the published theme, or your
purchase events will never fire.
Customer privacy settings can block the pixel
If your store uses Shopify’s customer privacy controls, a custom pixel will not run
until the visitor grants the consent category the pixel is assigned to.If you see page views but no purchases, check the pixel’s Permission setting under
Settings → Customer events first.
Password-protected stores
Development stores and stores behind a password page keep the storefront gated. Enter
the password first, then navigate to your campaign URL. Otherwise Shopify strips the
campaign parameters during the redirect and the visit records with no campaign.
Safari clears stored data after 7 days
Safari deletes browser storage written by scripts after 7 days of inactivity. A Safari
visitor who first arrives from an ad and returns more than a week later will be counted
as a new visitor.This affects all web analytics tools equally and is not specific to Linkrunner.
Ad-blockers and tracking prevention
Some browser extensions block analytics requests. Expect a small gap between Shopify’s
own order count and the purchases recorded here. Shopify’s admin remains the source of
truth for revenue.
Use Web SDK v0.1.13 or later
The cdn.linkrunner.io URL in Step 1 always serves the current version, so there is
nothing to install or keep updated. If you load the SDK from somewhere else, use
v0.1.13 or later for full campaign attribution at checkout.
Open your storefront, press F12, and check the Network tab for requests
to api.linkrunner.io.
No requests: the script tag is missing or the theme wasn’t saved
401 responses: wrong token. Confirm you used the Web SDK token
Page views appear but purchases don't
In order of likelihood:
The pixel was saved but never Connected
Customer privacy settings are blocking it (see Limitations)
You tested on a theme preview instead of the published theme
The token in the pixel doesn’t match the one in the theme
Purchases appear but show no campaign
Usually Shop Pay. Confirm the Step 2 cart snippet is installed and saved, then place
a fresh test order, because existing carts won’t have the attribute attached.
Revenue is missing or zero
Check that your products have prices set. The pixel reads the order total directly from
Shopify’s checkout data, so a zero total means a zero-priced order.