Skip to main content

Context API Object

Overview​

The context API object contains detailed information about server-side context for events sent through API implementations. This object is specifically designed for backend tracking where data must be collected and stored by the data provider before being sent to the API endpoint, enabling comprehensive tracking in server-side environments, CRM systems, and enterprise applications.

Each context API object captures server-side environment data, user agent information, IP addresses, and URL context that must be preserved from the original user interaction and transmitted through the API for accurate attribution and analytics.

Core Structure​

The context API object consists of several logical groups of properties:

  • Environment Configuration - Production vs development environment settings
  • Data Source Identification - Origin system and data collection method
  • Network Information - IP addresses and user agent strings from original interactions
  • URL Context - Page URLs, landing pages, and referrer information that must be preserved

Complete Reference​

context object

environment string required

info

Allowed values: prod, dev

environment: "prod"

data_source string required

info

Recommended values:

  • for website events: website
  • for admin manual added orders events: phone or admin
  • for app events: app
  • for marketplace events : marketplace. (You can replace "marketplace" word with real marketplace name.)
data_source: "website"

user_agent string recommended

info

User-Agent string from a browser when the event occurs

user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"

overide_ip string recommended

info

Ip address. Support ipv4 or ipv6. Recommended ipv6 if exists.

overide_ip: "123.123.123.99"

url string recommended

info

URL of the page where the order was initiated

url:"https://shop.example.com/thankyou-page"

landing_url string recommended

info

URL of the page where the user has start session were event was initiated.

landing_url:"https://shop.example.com/landing-page?query=abc"

referring_url string recommended

info

URL of the external referring site

referring_url:"https://google.com"

Implementation Examples​

{
  // Server-side e-commerce order context
  environment: "prod",
  data_source: "website",
  user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
  overide_ip: "203.0.113.45",
  url: "https://shop.example.com/checkout/confirmation",
  landing_url: "https://shop.example.com/products/laptop?utm_source=google&utm_medium=cpc",
  referring_url: "https://google.com/search"
}

Data Source Types​

The data_source field identifies the origin system and collection method:

Website-based data sources for web traffic:

{
  data_source: "website",      // Primary website traffic
  data_source: "mobile_web",   // Mobile browser traffic
  data_source: "webapp",       // Web application usage
  data_source: "blog",         // Blog and content traffic
  data_source: "landing_page"  // Marketing landing pages
}

User Agent Information​

User agent strings must be preserved from the original user interaction:

Browser User Agents​

// Desktop browsers
{
  user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"
}

// Mobile browsers
{
  user_agent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"
}

Application User Agents​

// Mobile apps
{
  user_agent: "MyApp/2.1.0 (iPhone; iOS 17.0; Scale/3.00)"
}

// API clients
{
  user_agent: "MyCompany-API-Client/1.0"
}

No User Agent Scenarios​

// Phone orders or manual entries
{
  user_agent: null // No browser involved
}

IP Address Handling​

The overide_ip field preserves the original user's IP address:

IPv4 Addresses​

{
  overide_ip: "203.0.113.45"      // Standard IPv4
}
{
  overide_ip: "2001:db8::1"       // IPv6 format
}

IP Privacy Considerations​

// Anonymized IP (last octet removed)
{
  overide_ip: "203.0.113.0"       // Privacy-compliant
}

// Internal/proxy IP handling
{
  overide_ip: "10.0.0.45"         // Internal network IP
}

URL Context Preservation​

API implementations must preserve URL context from the original user interaction:

Complete URL Tracking​

{
  // Current page where action occurred
  url: "https://shop.example.com/checkout/payment?step=billing&session_id=abc123",
  
  // First page of user session
  landing_url: "https://shop.example.com/products/headphones?utm_source=google&utm_medium=cpc&utm_campaign=audio_products",
  
  // External site that brought user
  referring_url: "https://google.com/search?q=wireless+headphones+review"
}

E-commerce Journey Context​

{
  // Order confirmation page
  url: "https://shop.example.com/thank-you?order=12345",
  
  // Product page where journey started
  landing_url: "https://shop.example.com/products/laptop?color=silver&storage=512gb",
  
  // Social media referrer
  referring_url: "https://facebook.com/YourBrand/posts/123456789"
}

Lead Generation Context​

{
  // Contact form submission page
  url: "https://example.com/contact-us?form=enterprise_inquiry",
  
  // Marketing landing page entry point
  landing_url: "https://example.com/solutions/enterprise?utm_source=linkedin&utm_campaign=b2b_solutions",
  
  // LinkedIn company page referrer
  referring_url: "https://linkedin.com/company/example-company"
}

Environment Configuration​

The environment field distinguishes between production and development contexts:

Production environment for live business data:

{
  environment: "prod",
  data_source: "website",
  overide_ip: "203.0.113.45"
}

Characteristics:

  • Real customer transactions
  • Live business operations
  • Production analytics tracking
  • Customer behavior data

Data Collection Requirements​

API context requires careful preservation of original interaction data:

Required Data Preservation​

User Agent Strings

  • Must be captured during original browser interaction
  • Store in session or transaction records
  • Transmit exactly as received from browser

IP Addresses

  • Capture real user IP, not server IP
  • Handle proxy and CDN scenarios correctly
  • Consider privacy regulations for IP storage

URL Information

  • Preserve complete URLs with parameters
  • Track landing page from session start
  • Maintain referrer information through journey

Data Storage Considerations​

// Example of preserving context in session data
const sessionData = {
  user_agent: request.headers['user-agent'],
  ip_address: request.connection.remoteAddress,
  landing_url: session.landing_page,
  current_url: request.url,
  referrer: request.headers.referer
};

// Later use in API call
const contextData = {
  environment: "prod",
  data_source: "website",
  user_agent: sessionData.user_agent,
  overide_ip: sessionData.ip_address,
  url: sessionData.current_url,
  landing_url: sessionData.landing_url,
  referring_url: sessionData.referrer
};

Usage in API Implementations​

The context API object is used across all server-side implementations:

Best Practices​

Data Accuracy​

  • Original Context Preservation - Always use original user context, never server context
  • Complete Information - Include all available context fields for accurate attribution
  • Consistent Data Sources - Use standardized data source naming conventions
  • IP Address Accuracy - Ensure real user IP, not proxy or server IP

Privacy Compliance​

  • IP Anonymization - Consider anonymizing IP addresses for privacy compliance
  • User Agent Privacy - Be aware that user agents can contain identifying information
  • URL Parameter Filtering - Remove sensitive parameters from URLs before transmission
  • Data Retention - Follow privacy regulations for context data storage

Performance Optimization​

  • Efficient Storage - Store context data efficiently in sessions or databases
  • Data Validation - Validate context data before API transmission
  • Error Handling - Handle missing or invalid context data gracefully

Integration Patterns​

  • Session Tracking - Maintain context data throughout user sessions
  • Delayed Transmission - Store context for later API submission (e.g., async order processing)
  • Multi-touchpoint - Preserve context across multiple system interactions
  • Cross-platform - Maintain context consistency across different platforms and systems

Security Considerations​

Sensitive Information​

// Avoid including sensitive data in URLs
{
  url: "https://example.com/account?user_id=HASHED_VALUE", // Use hashed IDs
  landing_url: "https://example.com/secure-area", // Remove sensitive parameters
  referring_url: "https://external-site.com" // Safe external referrer
}

IP Address Security​

// Consider IP privacy
{
  overide_ip: "203.0.113.0" // Last octet removed for privacy
}

Data Transmission Security​

  • Always use HTTPS for API transmission
  • Validate and sanitize all context data
  • Implement proper authentication and authorization
  • Monitor for suspicious or malformed context data