Skip to main content

​
Installing the pixel

The Storefront Pixel is delivered through the Layers theme app extension. There is no Liquid snippet to paste and 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 Connect on.
3

Save

Click Save. The pixel loads on every storefront page, ingests cart and customer context, and starts capturing events automatically.
The app embed handles tracking API keys, session context (productsInCart, productsPurchased, customer profile), DNS prefetch, and pixel script loading. You do not need to edit theme.liquid or any other theme file.
Contact support if you have questions or need help enabling the Storefront Pixel.

​
Events captured by pixel

The pixel tracks these storefront events:
  • Collection View
  • Search
  • Autocomplete (suggestions shown) and Autocomplete Click (suggestion selected)
  • Product Impression, Product Hover, and Product Touch
  • Product Click
  • Product View
  • Product Add to Cart
  • Content View, Content Impression, and Content Click (blog articles and pages)
  • Block View
  • Banner Impression
  • Banner Click
Purchases are tracked separately. When you install the Layers app, it also adds a Shopify web pixel that sends a Purchase event for each line item when a shopper completes checkout. Like the storefront events, it only runs when the shopper allows analytics. For information on forwarding these events to third-party analytics services like Microsoft Clarity and Blotout.io, see Third-party integrations.

​
What the pixel collects

The Storefront Pixel captures the minimum needed to measure and attribute search and merchandising performance. This section lists exactly what the pixel sends to Layers and what it does 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, a device identifier (persisted in the _layers_did cookie only when analytics consent allows), 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
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. The session ID normally comes from the pixel’s _layers_sid cookie and the device ID from its _layers_did cookie. When a shopper has not consented, the pixel does not read or write either cookie. It falls back to a random session ID in sessionStorage or memory, and refreshes that session on page load and every route change, including pages without tracked events. It expires after 30 minutes without activity. Consent denial does not keep the session alive for the whole tab lifetime, and the pixel does not write an analytics cookie in this state. Search and browse requests still carry a session ID, but it is a random value that identifies nothing beyond the current session.

​
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.
  • 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 in Session identifiers without consent.
  • 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. The redirect is performed by the pixel script, which the Layers Connect app embed loads, so it works whenever the app embed is enabled. The pixel intercepts API responses containing a _meta.redirect object and navigates the customer to the target URL before the search results page renders. For autocomplete, the pixel remembers the redirect for each suggestion and navigates directly when the shopper selects it. When Inline Collection Redirects serves an eligible collection inside the search response, no redirect object is returned and the search results remain on the page. With the pixel installed, you don’t need 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 without leaving the storefront.

​
Activating the debug menu

Add the _layers_debug_menu=true query parameter to any page URL on your storefront:
Once activated, the debug mode persists for the entire browser session (using 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.