Shopify Web Pixel

👾What is the Shopify Web Pixel

This extension leverages the Shopify Web Pixels API to provide a high-performance, secure bridge between your storefront and the Athos Commerce Beacon API. By capturing real-time customer signals across the entire shopping journey, it enables deeper analytics and more responsive personalization without compromising site performance or security.

🚀 Key Features

• Automated Event Tracking: Eliminates the need for manual code injection by subscribing directly to Shopify Customer Events.
• Full-Funnel Visibility: Securely tracks interactions across all surfaces, from the initial storefront visit through to the checkout and post-purchase pages.
• Enhanced Performance: A lightweight code library that removes bulky DOM manipulation, preventing performance lags and privacy alerts.
• Strict Security: Runs in a secure, isolated runtime context, ensuring total control over data access and customer privacy.

---

📦 Installation & Integration

The Web Pixel extension is a native component of the Athos: Unified Discovery Shopify app. It is designed for a "zero-touch" deployment experience, eliminating the need for manual script tags or liquid file edits.

🔌Installation Flow

The setup process is streamlined to get tracking live in four simple steps:

• Authentication: Merchants authenticate via the main app's standard Shopify OAuth flow.
• Redirect: Upon successful authentication, the app redirects the user to the Athos Console.
• Installation & Activation: The app must be installed, and then activated directly from the Athos Console.
• Configuration: Upon activation, the pixel automatically uses the siteId of the account that triggered it for all storefront events (unless explicitly overwritten via athos-track).

🧪

Development Mode: To enable detailed console logging, set the athosDev cookie to 1 or run the extension in a development environment. This will output full event payloads, state changes, and API response statuses directly to your browser's developer console.

---

⚙️ Configuration Details

Once the app is live, the extension uses the configured siteId to determine its behavior.

• Field Requirements: The siteId must be a single-line text field with a minimum of 1 character.
• Routing Logic: IDs starting with at route to the Athos Commerce backend. All other IDs route to the Searchspring backend.
• No-Op Mode: If no siteId is provided, the extension remains in a "no-op" state to prevent errors or unauthorized data collection.

❗️

Snap Tracker Compatibility: If using our SNAP library and the Snap tracker is already present and using a different siteId (stored in localStorage as athos-track), the Web Pixel will automatically switch to that ID to ensure consistent tracking.

---

📈Event Tracking

The Web Pixel captures real-time customer signals across the entire shopping journey, from the first product click to the final purchase, enabling deeper analytics. The extension automatically subscribes to Shopify's native customer events to power your discovery engine:

• Product Views: Tracks when customers view product detail pages (PDPs).
• Cart Actions: Monitors additions and removals to keep the Athos state synchronized with the shopper's intent.
• Order Transactions: Captures completed checkout events with order details for ROI reporting.
• Shopper Authentication: Detects login/logout events to link historical behavior with known customer identities across devices.

---

🆔 Identity Management

The Web Pixel extension maintains persistent tracking identifiers stored in both localStorage and cookies for cross-session and cross-subdomain reliability.

🌐

Data Persistence Strategy: The extension implements a hybrid cookie and localStorage fallback strategy. By automatically detecting the root domain, it ensures that tracking remains seamless even as customers move between your primary storefront and the Shopify checkout subdomains.

---

📦 Storage & State Management

To ensure a seamless and personalized shopping experience, the extension maintains a local state that synchronizes your Shopify storefront with the Athos engine.

Key State Components

• Cart State Synchronization: Automatically persists the current Shopify cart state (including SKU, quantity, and price) and syncs with Athos. This ensures that recommendation engines are always aware of what is currently in the basket.
• Viewed Products History: Maintains a local history of recently viewed products up to the last 20 items. This data is used to help power "Recently Viewed" recommendation blocks.
• Marketing Attribution: Captures and persists marketing attribution data via the athos_attribution URL parameter to ensure accurate conversion reporting.
• Root Domain Detection: Automatically determines the appropriate cookie domain for your site. This allows tracking to remain persistent as shoppers move between your primary domain and subdomains (e.g. your store to the Shopify checkout).

⚡

Preflight Requests: To enable real-time personalization, the extension sends debounced "preflight" requests to the recommendation API whenever a significant state change occurs (such as cart updates, viewed products, or login/logout) enabling real-time personalization.

👍

Reliability Strategy: The extension uses a hybrid fallback strategy between localStorage and cookies. By synchronizing state between these two storage methods, the extension ensures maximum cross-browser compatibility and data persistence.

---

🛠️ Technical Specifications

For developers and system integrators, the following technical details outline the underlying architecture and communication protocols used by the extension.

Architecture & Security

• Sandbox Environment: Operates in a strict sandbox runtime context. This ensures that the extension has zero impact on the main thread's performance and adheres to the highest privacy standards.

API Communication

• Beacon V2 API: Events are dispatched to analytics.athoscommerce.net/beacon/v2.
• Preflight API: Real-time personalization hints are sent to {siteId}.a.athoscommerce.net/v1/preflight.
• Reliability: Uses keepalive fetch requests to ensure event delivery is not interrupted by page navigations, tab closures, or rapid browsing.
• Localization: Automatically handles currency detection based on Shopify's payment settings.

📘

Development Support Tip: If you encounter issues with event delivery, ensure the pixel has been activated in the console.

---

📡 Beyond the Pixel: Beacon Tracking

While the Shopify Web Pixel provides a foundation for lifecycle events like "Purchase" or "Add to Cart", it is only one facet of the Athos tracking ecosystem. To capture granular, component-level interactions such as clicks, impressions, and renders on Autocomplete, Search Results, and Personalization modules you must leverage the Athos Commerce Beacon.

🛠️ Implementation Paths

Depending on your storefront architecture, you can track these interactions via two primary methods:

• Beacon.js Library: Our lightweight Beacon tracking library. It automatically handles the heavy lifting of event batching and metadata enrichment for all Beacon 2.0 tracking events.
• Direct API Endpoints: For headless environments or custom implementations, you can post interaction data directly to our beacon endpoints.

🧐What’s Tracked?

Beacon Tracking focuses on the high-frequency "Micro-Moments" occurring within your site’s search and discovery modules. Whether it’s Autocomplete, Search Results, Category Pages, or Personalization Carousels, these interactions provide the granular data necessary to power our tracking reports.

🔍Core Interaction Events

• render: Fires the moment a results grid or recommendation tray finishes loading.
• impression: Fires dynamically as products or merchandising banners scroll into the user's viewport.
• clickThrough: Fires when a user selects a product or recommendation to view its details.
• addToCart: Fires when a user adds a product to their bag directly from a result grid or carousel.
• redirect: Fires when a shopper’s query matches a merchant-defined redirect.

---

📖 Next Steps & Detailed Docs

The Shopify Web Pixel gets you part of the way there. To unlock full-event attribution and advanced reporting options, please refer to our dedicated tracking documentation:

🔗

Ready to go deeper? Familiar with Athos beaconing? Check out our Beacon Migration Guide for technical specs on event payloads. Just getting started? we recommend starting with our Beacon 2.0 overview for a guide on beaconing offers.