Home
Start typing to search…

Web SDK Documentation

Essentials for installing and using the Ours Privacy Web SDK, including event tracking and user identification.

Ours Privacy Web SDK Documentation

This guide covers everything you need to know about implementing and using the Ours Privacy Web SDK. Follow the sections below to get started and learn about advanced features.

Getting Started

Installation

To ensure that all page events are captured accurately, include the SDK script in the <head> section of your HTML:

<head>
  <!-- Other head elements -->
  <!-- Insert copy/pasted Ours Privacy Script Here -->
</head>

Note: Installing the SDK in the <head> ensures that events occurring as soon as the page loads are tracked properly.

Initialization

Initialize the SDK with your API key and any desired configuration options:

ours('init', '<ours web api key>', {
  // Optional configuration
  user_id: '<custom user id>',           // Provide your own user ID
  custom_domain: 'example.com',          // Set a custom domain for cookie storage
  track_web_events: true,                // Enable automatic web event tracking
  default_event_properties: {            // Set default event_properties to include on every event
    // Your default event properties
  },
  default_user_custom_properties: {      // Set default user custom_properties for every event
    // Your default user properties
  }
});

Configuration Options:

  • user_id: Your custom user ID to identify the user with
  • custom_domain: Custom domain for cookie storage and cross-domain tracking
  • track_web_events: Enable/disable automatic web event tracking
  • default_event_properties: Default properties to include with all tracked events
  • default_user_custom_properties: Default user properties for GA4 tracking

Core Features

User Identification

To associate tracked events with a specific user, use the ours('identify', ...) method. This method helps in linking the user's actions across sessions and devices.

ours('identify', { 
  first_name: 'test',
  email: '[email protected]',
  external_id: 'user123'
});

Event Tracking

Track events on your website using the ours('track', ...) method:

ours('track', 'event name', { 
  // Event properties
  value: 1 
}, { 
  // User properties
  first_name: 'test' 
});
  • Event Name: The name of your event
  • Event Properties: Metrics or values related to the event
  • User Properties: Additional user context. See allowed user properties

Cross-Domain Tracking

Maintain user identity across different domains by passing the Ours user ID via query parameters:

// Example URL with user ID
https://example.com?ours_user_id=${localStorage.getItem('ours_device_id')}

This is particularly useful when you need to maintain user identity across domains that don't share the same cookie domain.

Advanced Configuration

Custom User IDs (user_id)

Provide your own user ID for tracking when you have your own user identification system. This is useful for linking analytics data to your internal user records.

ours('init', '<ours web api key>', {
  user_id: 'user_12345'
});
  • Best Practice: Use a stable, unique identifier (such as your database user ID or external_id) to ensure consistent tracking across sessions and devices.

Custom Domains (custom_domain)

Set a custom domain for cookie storage to help with cross-domain tracking and to ensure cookies are set as first-party. This is especially important for privacy, compliance, and accurate tracking.

ours('init', '<ours web api key>', {
  custom_domain: 'yourdomain.com'
});
  • Advanced: Requires DNS setup and may need to be enabled by your OursPrivacy account rep. See Custom Domain Setup for details.
  • Best Practice: Use the same custom domain across all your sites for seamless cross-domain tracking.

Track Web Events (track_web_events)

Enable or disable automatic tracking of standard web events (such as page views, clicks, etc.).

ours('init', '<ours web api key>', {
  track_web_events: true
});
  • Advanced: Set to false if you want to manually control all event tracking.

Default Event Properties (default_event_properties)

Set default properties to include with every tracked event. Useful for adding environment, app version, or other context to all events.

ours('init', '<ours web api key>', {
  default_event_properties: {
    environment: 'production',
    app_version: '1.0.0'
  }
});
  • Advanced: These properties are merged with event-specific properties. Event-specific properties take precedence if there is a conflict.

Default User Custom Properties (default_user_custom_properties)

Set default user properties to include with every event, often used for GA4 or other destinations that support user-level properties.

ours('init', '<ours web api key>', {
  default_user_custom_properties: {
    user_type: 'premium',
    subscription_tier: 'enterprise'
  }
});
  • Advanced: These are included as user properties on the first event of each session. Useful for segmenting users in analytics platforms.

Troubleshooting

  • Events not tracking: Ensure the SDK is installed in the <head> section
  • User identification issues: Verify user properties are being passed correctly
  • Cross-domain problems: Check that custom domains are configured properly

For additional details and advanced configurations, please refer to the related guides in the sidebar.

Best Practices

Summary

  • Installation: Place the SDK script in your <head> for complete event capture
  • Initialization: Configure with your API key and desired options
  • User Identification: Use identify to link events with specific users
  • Event Tracking: Use track to capture user actions and behaviors
  • Cross-Domain Tracking: Pass user IDs via query parameters when needed

Common Use Cases

  1. Basic Implementation

    // Initialize
ours('init', '<ours web api key>');

// Identify user
ours('identify', { email: '[email protected]' });

// Track event
ours('track', 'page_view');

  2. Cross-Domain Setup

    // On first domain
ours('init', '<ours web api key>', { custom_domain: 'shared-domain.com' });

// On second domain
window.location.href = `https://second-domain.com?ours_user_id=${localStorage.getItem('ours_device_id')}`;

Troubleshooting

  • Events not tracking: Ensure the SDK is installed in the <head> section
  • User identification issues: Verify user properties are being passed correctly
  • Cross-domain problems: Check that custom domains are configured properly

For additional details and advanced configurations, please refer to the related guides in the sidebar.

Updated 9 days ago