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:- Collect relevant contextual information from your application
- Include it in the
contextparameter of your API requests - Manage user identity through the
identityparameter - Pass geographic location explicitly when making server-side API calls (the platform cannot automatically determine location from server IP addresses)
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 whencustomer 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
Thecontext 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.Products in Cart
Current cart contents help surface complementary products and influence relevance scoring.title(string, required): Product titleprice(string, optional): Product price as a stringtype(string, optional): Product typeproductId(string, optional): Shopify product IDvariantId(string, optional): Shopify variant IDoptions(object, optional): Key-value pairs of variant options
Purchase History
Previously purchased products inform recommendations and prevent over-promotion of already-owned items.title(string, required): Product titleprice(string, optional): Product price as a stringtype(string, optional): Product typeproductId(string, optional): Shopify product IDvariantId(string, optional): Shopify variant IDoptions(object, optional): Key-value pairs of variant options
Prior Searches
Recent search queries and their outcomes help understand customer intent and refine relevance models.searchQuery(string, required): The search query texthadClick(boolean, required): Whether the user clicked on any resultshadResults(boolean, required): Whether the search returned any results
Marketing Attribution
UTM parameters and marketing campaign information for attribution tracking.source(string, optional): Marketing source (e.g., “google”, “facebook”)medium(string, optional): Marketing medium (e.g., “cpc”, “email”, “social”)campaign(string, optional): Campaign nameterm(string, optional): Search term or keyword
Customer Profile
Aggregated customer behavior and purchase patterns for personalization.signedIn(boolean, optional): Whether the customer is currently authenticatedreturning(boolean, optional): Whether this is a returning customernumberOfOrders(integer, optional): Total number of orders placedaverageOrderValue(float, optional): Average order value in store currencydaysBetweenOrders(integer, optional): Average days between ordersdaysSinceLastOrder(integer, optional): Days since the most recent orderdaysSinceOldestOrder(integer, optional): Days since the first ordertotalSpent(float, optional): Total amount spent in store currency
Custom Context
Additional custom contextual data specific to your implementation.custom field accepts any arbitrary key-value pairs for implementation-specific context that doesn’t fit into the standard categories.
Complete Context Example
Here’s a comprehensive example showing all available contextual information fields: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. Customer Segmentation: Customer profile data (order history, spending patterns, loyalty status) enables personalized experiences for different customer segments. Marketing Attribution: UTM parameters and campaign information help track the effectiveness of marketing efforts and can influence product recommendations.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