Pixel Installation Guide

The Attribution.ai tracking pixel is the foundation of your attribution data. It captures visitor sessions, UTM parameters, referral sources, and ad platform click IDs across every page of your store so that each order can be tied back to the marketing touchpoints that drove it. This guide covers the current recommended installation path, verification steps, and common issues.

Important: Legacy public pixel script URLs (app.attribution.ai/pixel.js and cdn.attribution.ai/pixel.js) are deprecated and should not be used for new installations.

What the Pixel Tracks

Before installation, here is what the pixel captures on every page load:

Page views with full URL, page title, and referrer
UTM parameters: utm_source, utm_medium, utm_campaign, utm_term, utm_content
Ad platform click IDs: Facebook (fbclid), Google (gclid), TikTok (ttclid), Snapchat (ScCid)
Session data: session duration, page navigation paths, entry and exit pages
Device and browser metadata: device type (mobile, desktop, tablet), browser, operating system
Referral source: the referring domain for organic and referral traffic

The pixel does not collect personally identifiable information (PII) such as names, email addresses, or payment details. It assigns anonymous session identifiers that are later matched to Shopify orders.

Performance Impact

The pixel is under 5KB gzipped and loads asynchronously, meaning it does not block page rendering or affect your store's visible load time. It is served from a global CDN for minimal latency. The pixel has been tested across thousands of Shopify themes with no measurable impact on Core Web Vitals (LCP, FID, CLS).

Method 1: Automatic Installation (Recommended)

This is the fastest and most reliable method. It works with all standard Shopify themes.

In your Attribution.ai dashboard, navigate to Settings > Pixel Setup.
Click Install Pixel Automatically.
The app configures tracking using the current Shopify-compatible installation flow (Theme App Embed + backend wiring).
No code editing is required. The pixel is managed entirely through the Attribution.ai dashboard.

Advantages: No theme code changes, automatically updates when we release pixel improvements, works with theme switches.

Limitations: Headless storefronts (Hydrogen/custom React/Next.js) may require additional setup support.

Method 2: Manual Installation via Theme Editor (Legacy / Deprecated)

Direct manual snippet installation is deprecated for new setups. Use Method 1 unless support explicitly instructs otherwise.

In your Attribution.ai dashboard, go to Settings > Pixel Setup.
Click Copy Pixel Code to copy the snippet to your clipboard.
In your Shopify admin, navigate to Online Store > Themes.
Click Actions > Edit Code on your active theme.
Open the theme.liquid file (or layout/theme.liquid depending on your theme).
Paste the pixel snippet just before the closing </head> tag.
Click Save.

Legacy snippets and hardcoded script hosts should not be copied from old docs or historical implementations.

Important notes for manual installation:

The snippet must appear on every page. Placing it in theme.liquid ensures this because that layout file wraps all pages.
If your theme uses multiple layout files (e.g., theme.liquid and checkout.liquid), add the pixel to each one.
If you use a headless storefront, add the snippet to your application's root HTML template or use the JavaScript SDK directly.
The pixel automatically handles single-page app (SPA) navigation if your theme uses AJAX page loads or the History API.

Method 3: Google Tag Manager (GTM) (Legacy / Deprecated)

GTM-based standalone snippet injection is deprecated for new installations. Use dashboard-managed installation and contact support for advanced GTM workflows.

In your Attribution.ai dashboard, go to Settings > Pixel Setup and copy your Store ID (not the full snippet).
In Google Tag Manager, create a new Custom HTML Tag.
Do not inject legacy pixel.js URLs directly through GTM for new setups.
If you require GTM orchestration, coordinate with support for the current supported pattern.

GTM-specific considerations:

The pixel must fire on all pages, not just specific ones. Use the "All Pages" trigger, not a URL-based trigger.
If you have consent management configured in GTM, ensure the Attribution.ai pixel tag is categorized appropriately (typically "Analytics" or "Performance").
GTM's built-in tag sequencing is not required -- the Attribution.ai pixel is self-contained and does not depend on other tags.
If you use GTM's Server-Side Tagging, the pixel should still be deployed client-side. The pixel needs to run in the visitor's browser to capture session-level data.

Verification Steps

After installing the pixel using any method, follow these steps to confirm it is working:

Quick Verification

Open your Shopify store in an incognito or private browser window (this ensures no ad blockers or cached scripts interfere).
Browse through 2-3 pages on your store.
In your Attribution.ai dashboard, go to the Events tab.
Within 60 seconds, you should see page view events appearing with your store's URLs.

Advanced Verification Using Browser DevTools

Open your store in any browser.
Open Developer Tools (right-click > Inspect, or press F12).
Go to the Network tab.
Filter by "attribution" or "pixel-track".
Browse to a new page on your store.
You should see outgoing network requests to the pixel tracking endpoint. A successful request returns a 200 or 204 status code.

Debug Mode

For detailed diagnostic output, add ?att_debug=true to any page URL on your store (e.g., https://yourstore.com?att_debug=true). This activates debug mode, which outputs detailed logging to the browser console showing:

Every event the pixel captures
UTM parameters and click IDs detected
Session ID assignment
Any errors encountered during tracking

Debug mode is only visible in the browser console and does not affect the customer experience.

Verification Checklist

After installation, confirm all of the following:

Page view events appear in the Events tab within 60 seconds
UTM parameters are captured (test by visiting your store with ?utm_source=test&utm_medium=test)
Click IDs are captured (test by visiting with ?gclid=test or ?fbclid=test)
Events are firing on all page types: homepage, collection pages, product pages, cart page
The pixel loads on mobile devices (test using your phone or browser DevTools device emulation)

Common Issues

Pixel Not Tracking Any Events

Pixel not installed: The most common cause. Verify the script tag is present in your page source (View Page Source in your browser and search for "attribution.ai" or "pixel.js").
Wrong store ID: If the pixel loads but events do not appear in your dashboard, confirm the data-store-id value matches your Attribution.ai account. Find your correct Store ID in Settings > Pixel Setup.
Script error on page: Other JavaScript on your page may be throwing errors that prevent the pixel from loading. Check the browser console for errors.

CORS Errors in Browser Console

Cross-Origin Resource Sharing (CORS) errors appear when the pixel's tracking requests are blocked by the browser. This is rare but can happen if:

A proxy or CDN in front of your store is modifying response headers. Contact your hosting provider to ensure the Attribution.ai tracking domain is not blocked.
A Content Security Policy (CSP) header on your site is too restrictive. See the CSP section below.

Content Security Policy (CSP) Blocking

If your Shopify theme or a third-party app sets a strict Content Security Policy, the pixel may be blocked. You will see CSP errors in the browser console. To fix this, add the following to your CSP header:

connect-src: https://attribution.ai https://*.supabase.co

If you are unsure where your CSP is configured, search your theme code for Content-Security-Policy or contact the developer who set it up.

Ad Blockers Preventing Tracking

Ad blockers and privacy extensions (uBlock Origin, AdGuard, Privacy Badger, etc.) can block the Attribution.ai pixel. This is expected behavior and affects a portion of your traffic (typically 15-30% depending on your audience).

Attribution.ai accounts for this in two ways:

Post-purchase surveys capture attribution data directly from the customer, bypassing ad blockers entirely.
Attribution triangulation adjusts decision confidence when ad blockers reduce pixel coverage.

You do not need to take any action to work around ad blockers. The system is designed to produce accurate attribution even with partial pixel coverage.

Pixel Installed Multiple Times

If the pixel is installed more than once (e.g., both automatic and manual methods), events may be duplicated. Check for duplicate installations by:

Viewing your page source and searching for "attribution.ai" or "pixel.js".
If you find multiple instances, remove the extras and keep only one.
If you used the automatic method and also installed manually, remove the manual snippet and rely on the automatic installation.

Headless Storefront Setup

If you use a headless Shopify storefront (Hydrogen, Next.js, Gatsby, or a custom frontend), the automatic installation method will not work. Instead:

Install the pixel using the manual snippet method in your application's root HTML template.
Ensure the snippet loads on every route, not just the initial page load.
For single-page applications, the pixel automatically listens for History API changes (pushState and replaceState) to track page navigations.
If your SPA uses a custom routing mechanism that does not use the History API, contact support for guidance on manual page tracking.

Privacy and Compliance

The pixel respects Do Not Track (DNT) browser signals when configured (enable this in Settings > Privacy).
No personally identifiable information is collected by the pixel.
Session data is stored for the duration of your configured lookback window (default: 30 days) and then automatically deleted.
The pixel is compatible with GDPR consent management platforms. If a visitor has not consented to analytics tracking, the pixel will not fire when properly integrated with your consent management tool.