Visitor Context SDK (window.ours_experiments.getVisitorContext())

The Visitor Context SDK gives you programmatic access to visitor signals that the Ours Privacy platform collects automatically. Use it for personalization, analytics enrichment, conditional rendering, or pushing context to your dataLayer.

Note: This API currently returns two tiers of signals. Tier 1 comes from browser APIs and URL parsing. Tier 2 is injected server-side from the experiment-init response.

Quick Start

const ctx = window.ours_experiments.getVisitorContext();

// Geo-targeted content
if (ctx.geo.country_region === 'TX') {
  showTexasComplianceBanner();
}

// Campaign-specific messaging
if (ctx.utm.source === 'meta' && ctx.visitor_status === 'new') {
  showFacebookWelcomeOffer();
}

// Device-specific layout
if (ctx.device.type === 'mobile') {
  showMobileOptimizedHero();
}

Tier 1: Browser Signals (instant, no server round-trip)

Available immediately on page load from browser APIs and URL parsing.

UTM Parameters

ctx.utm;
// {
//   source: 'meta',
//   medium: 'paid',
//   campaign: 'spring-2026',
//   content: 'hero-cta',
//   term: 'privacy software'
// }

All values are string | null. Parsed from window.location.search on each page load.

Query Parameters

ctx.query_params;
// { utm_source: 'meta', ref: 'partner-123', promo: 'SAVE20' }

All current URL query parameters as a flat key-value object.

Visitor Status

ctx.visitor_status; // 'new' | 'returning'

Based on whether the visitor ID cookie existed before the current page load.

Referrer

ctx.referrer; // 'https://google.com/search?q=...' | null

Device & Browser

ctx.device;
// {
//   type: 'mobile',        // 'desktop' | 'mobile' | 'tablet'
//   os: 'iOS',
//   browser: 'Safari',
//   screen_width: 390,
//   screen_height: 844,
//   language: 'en-US'
// }

Time

ctx.time;
// {
//   day_of_week: 2,        // 0 (Sunday) – 6 (Saturday)
//   hour: 14,             // 0-23, visitor's local time
//   timezone: 'America/Chicago'
// }

Tier 2: Server-Enriched Signals (injected at script load)

These signals are resolved server-side when the experiment script is served and injected into the runtime config. They come from CloudFront geo headers — no third-party lookup needed.

Geolocation

ctx.geo;
// {
//   country: 'US',
//   country_region: 'TX',
//   city: 'Austin',
//   time_zone: 'America/Chicago'
// }

These are the geo fields currently injected into the SDK on cache-safe headers.

Device Type (server-detected)

ctx.geo.is_mobile_viewer; // 'true' | 'false'
ctx.geo.is_desktop_viewer; // 'true' | 'false'
ctx.geo.is_tablet_viewer; // 'true' | 'false'

These come from CloudFront device detection headers and complement the client-side ctx.device object.

Coming Soon: CDP-Computed Properties

Personalization Properties are planned, but they are not yet injected into getVisitorContext() on production traffic. Until that server-side path ships, rely on the browser and edge-resolved fields documented above.

Event: visitor:ready

Subscribe to the visitor context becoming available during SDK initialization:

window.ours_experiments.on('visitor:ready', (ctx) => {
  // ctx contains the current visitor context
  if (ctx.geo.country_region === 'CA') {
    showCaliforniaDisclosure();
  }
});

If you are attaching listeners after the runtime has already loaded, call window.ours_experiments.getVisitorContext() directly.

Use Cases

Geographic compliance messaging: Show state-specific disclaimers or pricing based on ctx.geo.country_region.

Campaign-matched landing pages: Adjust hero copy to match the ad the visitor clicked, using ctx.utm.source and ctx.utm.campaign.

Returning visitor recognition: Show a loyalty message or skip the intro for returning visitors using ctx.visitor_status.

Analytics enrichment: Push visitor geo, UTM, and device data into your analytics tool or GTM dataLayer.

Conditional rendering: Show or hide page sections based on any combination of visitor signals — device type, location, behavior history.

Next Steps

• Personalization: Always-on audience targeting rules configured in the dashboard
• JavaScript SDK: Experiment assignments, conversion tracking, and event subscriptions
• Installation: Set up the experiment runtime on your site