Skip to main content
Layers uses lightweight session context to deliver personalized search experiences. By understanding what customers have viewed, purchased, searched for, and where they’re located, the platform can surface more relevant products and optimize merchandising decisions in real-time.

​
How Contextual Information Works

Contextual information is automatically collected and managed by the Storefront Pixel for standard Shopify integrations. For headless or custom implementations, you must manually include contextual data in your API requests to enable personalization features.

​
Standard Shopify Integration

When you install the Layers Storefront Pixel on your Shopify theme, contextual information is automatically:
  • Collected from the customer’s browsing session and Shopify customer data
  • Transmitted with every search, browse, and tracking event
  • Used to personalize results without any additional implementation

​
Headless Integration

For headless storefronts or custom implementations, you must:
  1. Collect relevant contextual information from your application
  2. Include it in the context parameter of your API requests
  3. Manage user identity through the identity parameter
  4. Pass geographic location explicitly when making server-side API calls (the platform cannot automatically determine location from server IP addresses)
See the Search API, Browse API, and Prepare Search API documentation for details on passing contextual information.

​
User Identity

Layers uses three identifiers to track and personalize user experiences:

​
Device ID (Browser ID)

A persistent identifier stored in the browser’s local storage that remains constant across sessions. This allows Layers to recognize returning visitors even when they’re not signed in, enabling long-term personalization and behavior tracking. Source: Generated by the Storefront Pixel on first visit and persisted in browser storage.

​
Session ID

A temporary identifier that represents a single browsing session. Sessions typically expire after a period of inactivity or when the user closes their browser (depending on Shopify’s session management). Source: Shopify session ID, available via Liquid template variables.

​
Customer ID

The Shopify customer ID for authenticated users. This identifier is only present when a customer is signed in to their account. Source: Shopify customer ID, available when customer exists in Liquid templates. These identifiers are included in the identity parameter when making API requests. The Storefront Pixel handles this automatically for standard integrations.

​
Contextual Data Structure

The context parameter accepts the following structured data:

​
Geographic Information

Location data used for regional merchandising and localized search results. For client-side requests, the platform automatically determines the user’s location based on their IP address. For headless integrations making server-side API calls, you should pass geo information explicitly. 
{
  "geo": {
    "country": "US",
    "province": "California",
    "city": "Los Angeles"
  }
}

​
Products in Cart

Current cart contents help surface complementary products and influence relevance scoring. 
{
  "productsInCart": [
    {
      "title": "Nike Air Force 1",
      "price": 110.00,
      "type": "Shoes",
      "productId": "1234567890",
      "variantId": "9876543210",
      "options": {
        "Size": "11"
      }
    }
  ]
}

​
Purchase History

Previously purchased products inform recommendations and prevent over-promotion of already-owned items. 
{
  "productsPurchased": [
    {
      "title": "Nike Air Force 1",
      "price": 100.00,
      "type": "Shoes",
      "productId": "1234567890",
      "variantId": "1111111111",
      "options": {
        "Size": "13"
      }
    }
  ]
}

​
Prior Searches

Recent search queries and their outcomes help understand customer intent and refine relevance models. 
{
  "priorSearches": [
    {
      "searchQuery": "running shoes",
      "hadClick": true,
      "hasResults": true,
      "fromPage": "/collections/all"
    }
  ]
}

​
What Context Influences

Contextual information affects multiple aspects of the search experience: Relevance Scoring: Products related to cart items or purchase history receive adjusted relevance scores, surfacing complementary or similar items more prominently. Facet Selection: The platform intelligently selects which facets to display based on the customer’s browsing context and previous interactions. Sort Order Optimization: Default sorting can be influenced by customer behavior patterns, showing more relevant products first. Geographic Personalization: Location-aware merchandising rules and product availability can be applied based on the customer’s region. Intent Understanding: Prior searches and click behavior inform how new queries are interpreted, improving semantic understanding over time.

​
Implementation Notes

  • Contextual information is processed in real-time and only persists for the duration of the session
  • No personally identifiable information (PII) is required; all data is behavioral and anonymous
  • Sort Orders and Merchandising Rules always take precedence over contextual adjustments
  • Missing or incomplete contextual data won’t break functionality; the platform gracefully degrades to non-personalized results
  • For headless implementations, validate your contextual data structure matches the expected format to ensure proper personalization

​
Privacy Considerations

The Layers platform is designed with privacy in mind:
  • Device IDs are anonymous browser identifiers, not tied to personal information
  • Contextual data is used only for search personalization and is not shared with third parties
  • Customer IDs are encrypted and handled according to Shopify’s privacy standards
  • Geographic data is limited to city-level granularity, never precise coordinates
See also: Storefront Pixel, User Intent Processing, Search API
⌘I