Understanding Events

Events in Ours represent key interactions or actions taken by visitors on your website or app. You can track events, enrich them with event and visitor properties, and securely forward them to your configured destinations. This guide explains how events work, default behaviors, and best practices for ensuring secure and effective tracking.

Tracking Events

Tracking Events via GTM (Google Tag Manager)

Ours has a custom GTM template that makes it easy to trigger your events. While you can use our Javascript API, we recommend using our GTM template for added organization and triggering simplicity.

Tracking Events via Javascript

Track events by calling the ours function:

ours('track', 'Event Name');

If you'd like to capture additional attributes:

ours('track', 'Event Name', { value: 1, color: 'red' }, { first_name: "First name" });

Event Structure and Properties

The Four Parts of an Event

There are four parts to every event:

Event name
- The event name is what you will see in your Ours recent event view. You will need to "Allow" this event name on all destinations it should dispatch.
Event properties
- The event properties are optional. You can pass whatever you would like here. Example: {value: 100} to specify the event had a value of $100.
- $distinct_id is a special event property - It can be used for de-duplicating your events. Please use a sufficiently random value here, and avoid passing this property if you are not sure how to use it.
Visitor properties
- Visitor properties only accept specific visitor properties specified by Ours. You can see the complete list here. These properties can be mapped to your various destinations
Default properties
- Default properties are things specific to where the event happened. Ours automatically captures many things like utm_campaign, fbclid, browser type, IP address, and 100+ more properties. These can be mapped back to various destinations. You can optionally override any of these using our GTM template.

See Data Mapping, and Visitor Properties for more details.

Both the Javascript library and GTM template support sending all of the four properties above.

Event Names and Naming

We recommend sending semantically named events to Ours, and then using the built in renaming feature to rename the events before sending them to a destination.

For example, we recommend sending Ours:

"Summer Therapy Special Button Click" and then using our one-click renaming feature to rename the event to "MagicalElf" before sending it to a destination like Facebook

Default Parameters Collected

Ours automatically collects a variety of default parameters with each event to provide a comprehensive view of visitor behavior.

You can review all parameters collected by navigating to the Mappers inside of any destination. From here, open the variable dictionary to explore:

At a highlevel, we collect things like:

Ad Tracking Parameters:

gclid, gad_source, gc_id, gbraid, wbraid, utm_source, utm_medium, utm_campaign, utm_content, utm_term, fbclid, ad_id, msclkid, ttclid, rdt_cid

Session and Visitor Information:

sessionCount: Tracks the user's session count.
user_agent: Captures device and browser details.

Device and Browser Details:

browser, browser_version, device_type

Page and Referrer Details:

current_url, referrer, pathname, host

Screen Resolution:

screen_height, screen_width

Other:

title: The current page's title.
fbp and fbc: Facebook tracking identifiers.
browser_language: The default browser language.

Attribution Parameters

Ours tracks both initial and current values for key attribution parameters, enabling you to perform both first-touch and last-touch attribution analysis. This gives you flexibility in understanding how visitors discovered your site versus what brought them to their final conversion.

First Touch vs Last Touch Attribution

First Touch Attribution uses the initial values when a visitor first arrived at your site:

initial_referrer: The first referrer that brought the visitor to your site
initial_utm_source: The first UTM source parameter
initial_utm_medium: The first UTM medium parameter
initial_utm_campaign: The first UTM campaign parameter
initial_utm_term: The first UTM term parameter
initial_utm_content: The first UTM content parameter

Last Touch Attribution uses the current values from the most recent session:

referrer: The current referrer (same as the standard referrer parameter)
utm_source: The current UTM source parameter
utm_medium: The current UTM medium parameter
utm_campaign: The current UTM campaign parameter
utm_term: The current UTM term parameter
utm_content: The current UTM content parameter

Implementation

You can access both sets of parameters in your destination mappings. For example:

Map initial_utm_source to understand first-touch attribution
Map utm_source to understand last-touch attribution
Use both in your analytics platforms to compare attribution models

This dual tracking approach allows you to maintain comprehensive attribution data without losing historical context, even as visitors return to your site through different channels.

Ad-Specific Event Tracking

For advertising campaigns, Ours automatically captures and dispatches key query parameters from clicks, such as gclid (Google) or fbclid (Facebook). These parameters are included in tracked events and forwarded to relevant ad platforms.

Automatic Ad Conversion Tracking:

Ours detects sufficient properties to trigger conversions (e.g., for Google Ads).
Automatically handles dispatching conversions without manual intervention, improving tracking reliability.

Best Practices for Event Tracking

Add Events:
- Add custom events to your Allow List before sending them to destinations.
Use Semantic Event Names:
- Name the events in Ours with a pattern like: "Name Action". For example, "Summer CTA Click" or "Homepage Video View".
Use Event Renaming:
- Protect sensitive data by avoiding event names that reveal personal or identifiable information.
- Click "rename" event from your destinations allowed event list. And, automatically generate a unique name.
Leverage Default Properties:
- Take advantage of automatically captured properties to enrich your events without extra effort.
Test Events with a Test Token:
- Use test tokens to safely debug events without impacting production data. See Tracking and Debugging Events.

Event Deduplication and Idempotency

Ours ensures data integrity through idempotent event processing using the combination of visitor_id and distinct_id. This system prevents duplicate events and handles race conditions gracefully.

How Idempotency Works

When multiple events with identical visitor_id and distinct_id combinations are received:

First-Wins Semantics: The first event received for a given visitor_id + distinct_id combination will be stored
Subsequent Events Ignored: Any subsequent events with the same identifiers are silently ignored
No Data Loss: This prevents duplicate events from overwriting the original event

Race Condition Handling

When multiple events with the same visitor_id and distinct_id arrive within a short time window (e.g., from parallel processing or network retries):

Atomic Operations: Only one event will be stored through atomic database operations
Eliminates Race Conditions: This prevents the scenario where multiple events could be processed concurrently
Deterministic Results: The winner is determined consistently by the database, ensuring predictable behavior

Backfilling Historical Events

You can backfill historical events that occurred in the past using the Server API. This is useful for importing data from existing systems or correcting missing events.

Event Age Limits

Maximum Age: Events can be backfilled up to 7 days in the past
Time Format: The time field must be in milliseconds since UTC epoch
Validation: The time must be in the past and within the last 7 days

For more details on implementation, see Server-to-Server Integration.

Platform-Specific Recommendations

When sending events to platforms like Facebook and Google, ensure that your event names and properties align with their guidelines. These platforms often have unique requirements, such as specific event names or mandatory properties for accurate tracking.

Refer to each destination's documentation in Destinations for a detailed overview of optional and required properties.

Summary

Events are at the core of the Ours platform, allowing you to track key visitor actions and forward them securely to destinations. By following best practices for event naming, leveraging default properties, and managing visitor privacy, you can optimize your tracking workflows while maintaining compliance with privacy standards.