Skip to content
Browse the docs

Install Spurn on Shopify

The Spurn app adds the tag to your theme through an app embed and reports purchases through a checkout pixel. There is no code to paste, and the app shows you when each part is working.

Before you start#

  • A Shopify store on an Online Store theme. Headless and Hydrogen storefronts don't run theme app embeds; use /docs/install/nextjs or /docs/install/custom for those.
  • Permission to install apps on the store.
  • A Spurn account, or the email you want to create one with. You can create it during the install.
  • Room for one more site on your Spurn plan. Connecting a store adds a site, unless the workspace already has a site for the store's domain, which Spurn reuses.

Install from the Shopify App Store#

  1. Find Spurn in the Shopify App Store and click Install. Shopify shows the permissions the app needs: write pixels and read customer events. Approve them.
  2. Shopify opens the Spurn app inside your admin. Click Connect to Spurn.
  3. Spurn opens in a new tab. Sign in, or create an account.
  4. Choose the workspace that will protect the store, or choose A new workspace and give it a name. Click Connect store.
  5. Click Back to Shopify. The app now shows your store's setup steps.

The connection link lasts one hour. If it expires, click Connect to Spurn in the app again.

Install from the Spurn dashboard#

  1. In Spurn, open Sites and click Add a Shopify store.
  2. Enter your store's myshopify address, for example yourstore.myshopify.com. You'll find it under Settings, then Domains in your Shopify admin.
  3. Spurn sends you to Shopify. Approve the install.
  4. The Spurn app opens inside Shopify and asks: Connect this store to [your workspace]? It names the workspace and the person who asked. Click Connect store.

The request lasts one hour. Anyone on the store's staff who opens the app in that time sees it. If you don't recognise the workspace or the person, click Not me and nothing is connected.

Switch on the app embed#

Shopify does not let apps switch an embed on by themselves, so this step is yours.

  1. In the Spurn app, find Spurn tag in your theme under Setup and click Turn on in theme editor.
  2. The theme editor opens with Click protection switched on under Spurn, in Theme settings, then App embeds.
  3. Click Save.

Back in the app, the step shows a tick once the embed is on in your live theme. The embed only loads Spurn's tag. The tag does nothing on organic visits; it starts work when a visitor arrives from a paid ad.

The checkout pixel#

The pixel connects itself when the store is linked. You can see it under Settings, then Customer events, on the App pixels tab: Spurn shows as Connected.

It listens for one event, checkout_completed, and only reports orders from shoppers who arrived on a paid click. Each report holds the order id, the order total and its currency, plus the Spurn ids from the shopper's paid landing, so Spurn can match the purchase to that click. A purchase counts as evidence of a real shopper in the click's score.

The pixel declares the analytics purpose. In regions where Shopify's cookie banner asks for consent, it runs only after the shopper accepts analytics.

What the app shows#

  • Protection status: whether the site is in protect mode (blocking) or monitor mode (reporting only), and the workspace it belongs to.
  • Paid clicks checked and fake clicks caught in the last 7 days.
  • Setup, three steps: Spurn tag in your theme, Checkout pixel, Paid clicks arriving.
  • Open Spurn dashboard, for the full click log, block list and rules.

Check it works#

  1. Add your own IP address to the allowlist in Spurn (Blocking, then Allowlist), so your tests are never blocked.
  2. Open your store with a test click id: https://yourstore.com/?gclid=test-123.
  3. Within a minute, the app's Paid clicks arriving step shows a tick, and the click appears under Clicks in the dashboard. The site's Install tab shows Receiving.

A test landing counts as a real paid click and uses one credit.

Troubleshooting#

The embed step shows it is off. Embeds are switched on per theme. After you publish a different theme, or a copy of one, turn Click protection on again in that theme and save. The app reads your published theme only.

The app says it could not read your theme's app embeds. Open the theme editor, go to Theme settings, then App embeds, and check Click protection is on.

The pixel step says Connecting. It usually connects within a few seconds of linking the store. Reload the app. If it stays that way, check Settings, then Customer events.

No clicks arrive. Check the test URL has a click id. Visits without one are ignored by design. Ad blockers can stop the tag in your own browser; try a private window without extensions.

Orders don't show as conversions. The pixel fires when the shopper reaches the thank-you page. If the page doesn't load, Shopify doesn't send the event. Orders from shoppers who didn't arrive on a paid click are never sent.

The store is connected to another workspace. A store belongs to one workspace. Ask an owner of that workspace to invite you.

You changed your store's primary domain. Spurn picks up the change from Shopify and allows the new domain to report. There is nothing to do.

Uninstalling#

Uninstalling the app removes the embed and the pixel from your store, and Spurn deletes its access to the store. The site and its click history stay in your Spurn workspace. Reinstalling reconnects the same site.

What data is sent#

  • From the tag, on paid landings only: the landing URL and referrer, the IP address and user agent, browser signals used to spot automation, and engagement such as time on page and scrolling. See /docs/detection.
  • From the pixel: order id, order total and currency for orders from paid visitors.
  • Spurn reads no customer, order or address records from Shopify. The app's only permissions are writing the pixel and reading customer events.