Installing the pixel
The Storefront Pixel is delivered through the Layers theme app extension — no Liquid snippet to paste, no API key to manage.1
Open your theme customizer
In Shopify admin, go to Online Store → Themes, find your live theme, and click Customize.
2
Enable the Layers app embed
Open the App embeds panel in the left sidebar and toggle Layers on.
3
Save
Click Save. The pixel loads on every storefront page, ingests cart and customer context, and starts capturing events automatically.
productsInCart, productsPurchased, customer profile), DNS prefetch, and pixel script loading. You do not need to edit theme.liquid or any other theme file.
Please contact support if you have any questions or could use some assistance enabling the Storefront Pixel.
Events captured by pixel
- Collection View
- Product Click
- Product View
- Product Add to Cart
- Block View
What the pixel collects
The pixel is designed to capture the minimum needed to measure and attribute search and merchandising performance. This section lists exactly what is sent to Layers and what is not.Fields on every event
Fields specific to an event
Added when the event reaches Layers
Events are received at the edge and enriched before storage with country, region, and city (resolved from the connection), device type, browser name, and operating system name. The raw IP address and user agent string are used for this enrichment and are then discarded. They are not stored with the event.Session context sent with API requests
Separately from events, the Layers app embed passes context along with search and browse requests so results can be personalized. This includes the session ID, customer ID (when signed in), products currently in the cart, recently viewed products, recent purchases, aggregate customer signals such as returning status and order count, the shopper’s market, and any UTM or ad click identifiers from the current visit. This context is used to serve the request and for attribution. It is not sent to model providers. See AI & your data for details.What the pixel does not collect
- Names, email addresses, phone numbers, or postal addresses
- Payment or checkout details
- Free-text input outside the search box
- Keystrokes, mouse movement, scroll depth, or session recordings
- Third-party cookies or cross-site identifiers
- Precise location
Consent and privacy signals
Layers defers to Shopify for all consent and privacy decisions. The pixel does not run its own consent banner or interpret browser privacy signals itself. Instead it reads Shopify’s Customer Privacy API, which reflects the shopper’s cookie banner choice, your store’s regional privacy settings, and browser signals such as Global Privacy Control (GPC) according to how you have configured them in Shopify admin under Settings → Customer privacy.Analytics events
Before queuing any event, the pixel asks Shopify whether analytics processing is allowed for the shopper. If it is not, the event is dropped in the browser and nothing is sent to Layers. Because the check happens per event, a change in consent takes effect immediately: if a shopper declines partway through a visit, events stop from that point and any events still queued in the browser are discarded; if they accept, events start.Session identifiers without consent
The session ID normally comes from Shopify’s_shopify_s cookie. When a shopper has not consented, Shopify does not set that cookie, so the pixel falls back to a random identifier that it generates itself. That identifier is kept in sessionStorage for the current tab only and is not written to a cookie, so it disappears when the tab is closed and cannot be linked to any other visit, device, or Shopify identity. Search and browse requests still carry a session ID in this state, because results need one to be returned correctly, but it is a random value that identifies nothing beyond the current tab.
If the Customer Privacy API is not present
In a headless storefront or custom app where Shopify’s Customer Privacy API is not on the page, the pixel has nothing to defer to and assumes analytics is allowed. Headless implementations are responsible for gating tracking against their own consent mechanism.What consent does and does not affect
- Analytics events (everything in “Events captured by pixel”) are only sent when Shopify reports analytics is allowed.
- Search and browse requests are always made, because they are required to render results. Without consent they carry the random per-tab session ID described above.
- Auto redirects and the Search Inspector are unaffected by consent state.
Line item properties
The pixel appends a line item property with the key_layers_attribution to some add-to-cart forms. The value corresponds to the identifier of the request made using the Search or Browse API where the customer last saw the product before adding it to their cart. This property is only added if the customer clicked on products from the Search or Browse APIs.
Order attributes
Layers reads the following order-level note attributes to associate purchase events with browsing sessions:
When both
_em_session_id and _layers_session_id are present on an order, _em_session_id takes priority.
If you have the Edgemesh integration enabled, the Edgemesh attributes are automatically appended to orders. No additional configuration is required.
Auto redirect support
The storefront pixel automatically redirects customers when a search or autocomplete request matches a semantic redirect. Whenever the pixel is installed, it intercepts API responses containing a_meta.redirect object and navigates the customer to the target URL before the search results page renders.
This eliminates the need for custom frontend logic to handle redirect responses. For details, see Semantic Redirects — Auto redirect.
Search Inspector (debug menu)
The Storefront Pixel includes a built-in debug panel called the Search Inspector. It helps developers and QA teams verify tracking behavior, inspect API requests, and submit search quality feedback — all without leaving the storefront.Activating the debug menu
Add the_layers_debug_menu=true query parameter to any page URL on your storefront:
sessionStorage). To deactivate it, use _layers_debug_menu=false.
Panel tabs
The Search Inspector has four tabs:- Searches — Displays all API requests intercepted by the pixel (search, browse, similar, blocks). Each request shows the URL, request type, and timestamp. You can expand a request to reveal the full request/response bodies, workflow steps (like spelling corrections, query expansions, and applied rules), metadata, and search IDs.
- Activity — Shows all tracking events captured by the pixel (product clicks, views, add-to-carts, and more) with delivery status and full event payloads.
- Feedback — A form for submitting search quality feedback directly to Layers. The search reference ID is automatically populated from the most recent search. Includes a rating (good/poor results) and optional text feedback.
- Rules — Displays the current session state including experiment info, active search query, collection context, result counts, and attribution tokens. Also shows any merchandising rules that were applied to recent requests.
Panel features
- Draggable and resizable — The panel can be moved anywhere on screen and resized. Position is persisted across page navigations within the session.
- Dockable — Collapses to a small handle on the left or right edge of the viewport. Click the handle to expand.
- Shadow DOM isolation — The panel renders inside a closed Shadow DOM, so it does not interfere with the storefront’s styles or layout.
The Search Inspector is dynamically loaded only when debug mode is active. It adds no overhead to the storefront when not in use.
Browser compatibility
Supported specs
- Back/Forward Cache.
- Speculation Rules.
- SPA Navigation.