What the app embed and SDK handle for you

​

Overview

Most of what makes a Layers integration work end-to-end is not code you write in your theme. The Layers app embed (the theme app extension) and the @commerce-blocks/sdk handle the cross-cutting concerns — authentication, identity, cart and customer context, attribution, tracking, third-party forwarding, semantic redirects, and dynamic linking — so your theme code only has to worry about rendering search, browse, blocks, and banner UI. This page is the reference for what’s handled automatically. If something on this list isn’t behaving in your theme, the fix is almost always a configuration toggle in the Layers dashboard or an embed setting — not theme code.

​

What the app embed handles

The app embed is delivered as a Shopify theme app extension. Once it’s toggled on under Online Store → Themes → Customize → App embeds, the following behavior is automatic.

​

Authentication and identity

• Storefront token loading. The embed reads shop.metafields.layers.embed_settings.value.storefrontApiToken and attaches it to every Layers API request the embed makes on behalf of the storefront. You do not paste a token into theme code.
• Device and session IDs. The embed manages deviceId (persisted) and sessionId (per visit) for every Layers request and event. Cookie fallbacks are configured via sessionCookieFallbacks in embed settings.
• Customer context. If a shopper is logged in, the embed forwards Shopify customer ID, segment, and tag context to every request automatically.
• Cart context. productsInCart is sent on every Layers request without you reading /cart.js. Cart-anchored blocks and cart-aware merchandising work out of the box.
• Market detection. When Shopify Markets is configured, the embed forwards the active market context (currency, country, language) so search, browse, and blocks return market-correct results and pricing.

​

Tracking

The embed includes the Storefront Pixel, which captures and ships events to the Tracking API:

• collection_view when a shopper lands on a collection page.
• product_view when a PDP renders.
• product_click when a shopper clicks a product card surfaced by Layers.
• add_to_cart when a Shopify add-to-cart form submits.
• block_view when a recommendation block enters the viewport.

You do not need to call navigator.sendBeacon yourself for these events. Custom storefronts that don’t load the embed should follow the navigator.sendBeacon guide instead.

​

Attribution

• _layers_attribution line item property. The pixel appends a _layers_attribution property to add-to-cart forms when the shopper clicked the product from a Search or Browse response. The value is the attributionToken of the originating request.
• Order attributes. The pixel reads _em_session_id, _em_device_id, _em_nav_id, and _layers_session_id from order note attributes to tie purchases back to sessions. Edgemesh’s _em_* attributes take priority when present.
• Edgemesh attribute writing. When the Edgemesh integration is enabled, Edgemesh’s session and device IDs are written onto every order automatically — no theme work required.

​

Semantic redirects (auto-redirect)

When Auto Redirect is enabled under Settings → Semantic Redirects, the embed intercepts search and autocomplete responses that carry a _meta.redirect object and navigates the shopper to the configured URL before the search results page renders. See Semantic Redirects. You do not need to handle _meta.redirect in theme code — disabling auto-redirect in the dashboard is the supported way to opt out.

​

Dynamic linking via ?utm_products=

The embed handles inbound ?utm_products= deep links: when a shopper lands on the storefront with a utm_products query param, the embed expands it into the matching products and surfaces them through the appropriate Layers experience. See Dynamic linking.

​

Third-party integration forwarding

When the integrations below are enabled in the Layers dashboard, the embed forwards events and reads/writes IDs without theme changes. See Third-Party Integrations.

​

Search Inspector

Append ?_layers_debug_menu=true to any storefront URL to open the Search Inspector — a built-in QA panel that shows the request being made, the response, attribution, and storefront-pixel events. Mode persists for the session via sessionStorage; ?_layers_debug_menu=false turns it off. No theme code is needed to expose the debug menu. It’s available on every page when the embed is enabled.

​

What the SDK handles

If you adopt @commerce-blocks/sdk, the client adds a second layer of behavior on top of the app embed — none of which requires theme code.

​

Reactive controllers

client.collection(), client.search(), client.blocks(), client.autocomplete(), and friends return controllers with a reactive state signal. Subscribe once, call execute() whenever inputs change, and the subscriber re-runs on every state transition. See Client methods.

​

Caching and request deduplication

Identical in-flight requests are deduplicated into a single network call. Responses are cached in localStorage keyed by request shape so a back-navigation restores instantly. See Cache and storage.

​

Framework-agnostic signals

The reactive state signals work in vanilla JS, React, Vue, Svelte, Solid, and Lit. See Framework integration. You don’t need a framework-specific adapter package — the signal API is what you subscribe to.

​

Product card controller

client.productCard() exposes a reactive product card with variant selection, availability logic, and price formatting. The controller updates as variants are chosen, so your tile component just renders the latest snapshot.

​

Product transforms

createClient({ transforms }) lets you mutate every product, collection result, and search result before it lands in your render code. See Client methods → transforms.

​

Filter aliases

createClient({ filters: { aliases } }) maps URL-friendly filter keys (color, size) onto the underlying attribute codes (options.color, options.size). See Filtering.

​

Prepare / execute split

Controllers expose prepare() and execute() so you can stage the request shape (filters, sort, pagination) before firing the network call. Useful for SSR and for UIs that build the request across multiple user interactions.

​

SSR-safe XHR fallback

In environments where fetch is not available (or keepalive is not honored), the SDK falls back to XHR transparently so requests still complete in SSR contexts and edge cases like unload flushes.

​

What is not handled

Some things still belong to your theme code, even with the embed and the SDK installed:

• Rendering UI — search results pages, collection grids, facet sidebars, sort selectors, block tiles, banner placement. The embed does identity, context, and tracking; the SDK does request management. Markup is yours. See the Liquid guides and the SDK twins.
• Banner placement math. The browse response carries appliedRules[].banners — your theme owns hero placement above the grid and inline position-based slotting. See Rendering banners in Liquid and Rendering banners with the SDK.
• Banner click tracking. Storefront-pixel events cover product engagement; banner clicks are not tracked automatically. Wire a Tracking API call on the banner anchor’s click handler if you need that signal.
• Block picker UI. The embed knows which blocks exist (via metaobjects) but doesn’t render the block-picker dropdown in the theme editor. See Rendering blocks in Liquid.
• Visual Search and Similar Products UX. The embed loads the underlying widget, but you choose where it appears on PDPs and collection pages.

​

See also

• Storefront Pixel — how the pixel ingests events and writes attribution.
• Liquid integration — reading embed settings and metaobjects from Liquid.
• SDK overview — the optional client library.
• Third-Party Integrations — Clarity, Blotout, Rivo, Abra, FoxSell, Edgemesh.
• Theme implementation checklist — step-by-step plan for shipping a theme integration.