Context Object Guide

Overview

The context object is a required component of every beacon event payload. It provides contextual information about the shopper and environment for accurate reporting.

{
  "context": { /* contextual information */ },
  "data": { /* event-specific data */ }
}

Context Object Fields

Examples

Minimum Required Fields

{
  "context": {
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/search?q=shirts",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "initiator": "searchspring/custom/1.0"
  }
}

Full Context

Recommended for server side integrations - be sure to provide the shopper's IP and userAgent and not the server's.

{
  "context": {
    "IP": "89.76.6.25",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
    "timestamp": "2024-06-11T17:47:04.075876Z",
    "pageUrl": "https://example.com/products/blue-shirt",
    "userId": "41f87850-65f5-4546-851c-f166109e57b9",
    "sessionId": "1c311c14-c33b-4222-952a-f17db729ea31",
    "pageLoadId": "080d179f-0034-4278-8d3c-dfba71c9b897",
    "shopperId": "[email protected]",
    "initiator": "searchspring/custom/1.0",
    "currency": { "code": "USD" }
  }
}

Best Practices

Identifier Management:

• Use UUIDs (v4) for all identifier generation

Timestamps:

• Use RFC3339 format with UTC timezone: YYYY-MM-DDTHH:mm:ss.sssZ
• Capture when event occurs, not when sent

Authentication:

• Include shopperId whenever user is logged in
• Required for /shopper/login endpoint and personalization

Testing:

• Set dev: true during testing to prevent affecting production reports

Tracking Identifiers

The Searchspring Beacon API uses multiple identifier fields to track shopper behavior at different scopes:

*Required for /shopper/login endpoint, optional but recommended for all other events when user is authenticated.

These identifiers work together to provide complete tracking from the individual shopper level down to specific interactions on a single page, with additional authenticated user tracking for personalization.

User ID (userId)

What is it?

The userId is a persistent identifier that uniquely identifies an individual shopper across all their visits to your site. It remains the same whether the shopper visits today, tomorrow, or months from now.

Duration & Persistence

• Lifetime: Long-term (typically 1-2 years or longer)
• Survives: Browser sessions, site revisits, device restarts
• Storage: Long-lived cookie or localStorage
• Consistency: Must remain identical across all visits for the same shopper

Purpose

The userId enables cross-visit analytics:

• Return Visitor Analysis: Distinguish new vs returning shoppers
• Customer Lifetime Value: Track purchases across multiple sessions
• Long-term Behavior: Identify shopping patterns over time
• Personalization: Deliver consistent personalized experiences
• Attribution: Track conversion paths spanning multiple visits

When to Generate

Generate a new userId only when:

• First-time visitor (no existing user ID found)
• Cookie/storage has been cleared
• Shopper is using a new device/browser

Important Notes

• Different from authenticated user ID (like account login ID)
• Should be anonymous UUID - not personally identifiable
• Required for every tracking event
• Must be consistent to maintain reporting accuracy

Session ID (sessionId)

What is it?

The sessionId identifies a single visit or shopping session. A session represents a continuous period of activity with no gaps longer than 30 minutes between tracked events.

Duration & Expiration

• Active Duration: 30 minutes of continuous activity
• Expiration: After 30 minutes of inactivity
• Auto-Refresh: Every tracking event resets the 30-minute timer

Purpose

The sessionId enables single-visit analytics:

• Conversion Tracking: Track journey from landing to purchase within a visit
• Session Quality: Pages per session, time on site, bounce rate
• Abandonment Analysis: Cart/checkout abandonment within session
• Engagement Metrics: Product views, searches per session
• Behavior Flow: Understand navigation patterns in a single visit

Session Lifecycle

Start: New session begins when:

• Shopper first arrives on site
• Previous session has expired (30+ min inactive)
• Session cookie doesn't exist or is invalid

Continue: Session persists when:

• Shopper browses with less than 30 minutes between events
• Any tracking event is fired (resets timer)
• Shopper remains active on the site

End: Session terminates when:

• 30 minutes pass with no tracked events
• Session cookie expires naturally
• Shopper closes browser (depending on cookie settings)

Example Scenarios

Short Session:

• Visitor lands on homepage at 2:00 PM
• Views 3 products between 2:00-2:10 PM
• Leaves site at 2:10 PM
• Session expires at 2:40 PM (30 min after last event)

Extended Session:

• Visitor lands on site at 10:00 AM
• Browses products continuously until 11:30 AM
• Each page view resets the timer
• Session lasts 1.5 hours despite only 30-minute threshold (because user was active)

Multiple Sessions:

• Visitor shops at 9:00 AM, leaves site
• Returns at 10:00 AM (60 minutes later)
• New session created because previous expired at 9:30 AM

Important Notes

• Session resets with every tracking event (not just page loads)
• Use UTC timestamps to avoid timezone issues
• Required for every tracking event
• Critical for accurate conversion reporting

Page Load ID (pageLoadId)

What is it?

The pageLoadId is a unique identifier for a single page load. It groups all events that occur on the same page together, even if multiple events are fired during that page view.

Duration & Scope

• Lifetime: Single page load only
• Regenerate: Every time page loads/reloads
• Persistence: Does not survive navigation or refresh
• Storage: Can be stored in cookie if needed (for sharing between applications)

Purpose

The pageLoadId enables page-level event correlation:

• Event Grouping: Link all events from same page (render, impression, clickthrough)
• Duplicate Detection: Identify multiple events from same page load
• Analytics Accuracy: Distinguish page refresh from continuing session
• Debugging: Trace all events from a specific page instance
• Performance: Measure time between related events on same page

When to Generate

Generate a new pageLoadId:

• On initial page load
• On page refresh/reload
• On single-page app route changes (if treating as new page)
• Every time the page context changes

Use Cases

Search Results Page:

• Page loads → Generate pageLoadId: xyz-123
• Fire render event → Include pageLoadId: xyz-123
• Fire impression event → Include pageLoadId: xyz-123
• User clicks result → Fire clickthrough event → Include pageLoadId: xyz-123

All events share the same pageLoadId because they occurred during the same page load.

Page Refresh:

• User on product page → pageLoadId: abc-111
• User refreshes page → Generate new pageLoadId: abc-222
• New events use abc-222

This distinguishes the second page view from the first.

Important Notes

• Must be unique for each page load
• All events on same page should share the same pageLoadId
• Different from session ID (multiple page loads can occur in one session)
• Generate once per page load and reuse for all events on that page
• Required for every tracking event

Shopper ID (shopperId)

What is it?

The shopperId is an authenticated user identifier that links tracking events to a specific logged-in customer account. Unlike userId (which is anonymous), shopperId represents a known, authenticated shopper.

Duration & Persistence

• Lifetime: Active while user is logged in
• Survives: Session, but tied to authentication state
• Cleared: When user logs out
• Storage: Application session or secure cookie
• Consistency: Should match authenticated account identifier

Purpose

The shopperId enables authenticated user features:

• Personalization: Deliver user-specific product recommendations
• Cross-Device Tracking: Link same user across devices when authenticated
• Account Analytics: Track behavior tied to specific customer accounts
• Purchase History: Connect browsing to known customer purchase patterns
• Customer Insights: Analyze behavior of identified customers

When to Include

Required:

• /shopper/login endpoint - Must be present in context

Recommended (when user is authenticated):

• All search, category, autocomplete events
• All recommendations events
• Product pageviews
• Cart modifications
• Order transactions

Omit when:

• User is not logged in (guest browsing)
• User is in anonymous/incognito mode
• Before successful authentication

What Value to Use

Typical values:

• Customer account ID (e.g., "cust_123456")
• Customer email address (e.g., "[email protected]")
• Internal user identifier from your system

Important: Use a consistent identifier that:

• Uniquely identifies the customer
• Matches across all authenticated sessions
• Aligns with your customer database
• Remains stable (doesn't change when user updates profile)

Relationship to userId

Both identifiers can coexist:

• userId = Anonymous browser-based tracking (always present)
• shopperId = Known customer tracking (when authenticated)

Example flow:

Guest browsing:
- userId: anon-uuid-123
- shopperId: (not included)

User logs in:
- userId: anon-uuid-123 (same)
- shopperId: [email protected] (now included)

User logs out:
- userId: anon-uuid-123 (same)
- shopperId: (removed)

This allows you to:

• Track anonymous behavior before login
• Connect that behavior to authenticated user after login
• Continue tracking if user logs out

Privacy & Security

Considerations:

• shopperId contains personally identifiable information
• Ensure compliance with privacy regulations (GDPR, CCPA)
• Include in privacy policy disclosures
• Implement proper data retention policies
• Consider hashing or tokenizing if transmitting sensitive identifiers
• Use HTTPS for all tracking requests

Best practices:

• Clear shopperId when user logs out
• Don't include shopperId for guest checkout
• Respect user privacy preferences
• Document what identifier you're using as shopperId

Authentication Events

The /shopper/login endpoint specifically tracks successful authentication. This is the only endpoint where shopperId is required rather than optional.

When to fire /shopper/login:

• User successfully logs in via login form
• User authenticates via social login (Google, Facebook, etc.)
• User authenticates via SSO

When NOT to fire:

• Failed login attempts
• User creates new account (fire after they log in post-registration)
• Automatic session restoration (already logged in from previous session)

Important Notes

• Different from userId (which is anonymous)
• Only include when user is authenticated
• Must be included in /shopper/login endpoint
• Critical for personalized recommendations
• Should match your customer database identifier
• Clear when user logs out

Best Practices

Generation

userId:

• Generate once and store persistently
• Use UUID v4 format
• Store in long-lived cookie (1-2 years)
• Never regenerate unless cookie cleared

sessionId:

• Generate on first visit or after expiration
• Use UUID v4 format
• Store with timestamp in cookie
• Regenerate after 30 minutes of inactivity

pageLoadId:

• Generate fresh on every page load
• Use UUID v4 format
• Keep in memory, don't persist
• Share across all events on same page

shopperId:

• Only include when user is authenticated
• Use customer account identifier or email
• Required for /shopper/login endpoint
• Clear when user logs out

Consistency

• Same values: All events from same context should use identical IDs
• Timing: Generate IDs at appropriate scope (don't mix page load IDs across pages)
• Validation: Verify IDs are valid UUIDs before sending
• Testing: Use dev: true flag to test without affecting production data

Common Mistakes

❌ Don't:

• Regenerate userId on every visit
• Use sessionId across different sessions
• Share pageLoadId across page navigations
• Include shopperId when user is not logged in
• Use sequential numbers instead of UUIDs
• Mix up which ID goes where

✅ Do:

• Keep userId consistent for returning visitors
• Refresh sessionId timestamp with each event
• Create new pageLoadId for each page load
• Include shopperId when user is authenticated
• Use proper UUID format for anonymous identifiers
• Include all required IDs in every event