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 withcustom_domain
: Custom domain for cookie storage and cross-domain trackingtrack_web_events
: Enable/disable automatic web event trackingdefault_event_properties
: Default properties to include with all tracked eventsdefault_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
)
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
)
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
)
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
)
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
)
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
-
Basic Implementation
// Initialize ours('init', '<ours web api key>'); // Identify user ours('identify', { email: '[email protected]' }); // Track event ours('track', 'page_view');
-
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