# Understanding Events

> A comprehensive guide to tracking events, managing event properties, and ensuring secure and effective data collection in Ours Privacy.

Source: https://docs.oursprivacy.com/docs/understanding-events

Events in Ours Privacy 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.

***

## Tracking Events

### Tracking Events via Ours Privacy Tag Manager (Recommended)

The [Ours Privacy Tag Manager](https://docs.oursprivacy.com/docs/tag-manager) lets you create and manage tracking tags visually, with no code required. It's purpose-built for HIPAA-regulated analytics and provides the tightest integration with Ours Privacy.

[Get started with Tag Manager](https://docs.oursprivacy.com/docs/tag-manager/installation)

### 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:

1. **Event name**
   * The event name is what you will see in your Ours Privacy recent event view. You will need to "Allow" this event name on all destinations it should dispatch.
2. **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 used for de-duplicating your events. Pass a stable, deterministic value you can reproduce on retry, such as an order ID or a payment provider's transaction ID. If omitted, we generate one for you, but supplying your own gives stronger idempotency guarantees, since it lets you safely retry the same call without creating a duplicate event. See [Deduplication](https://docs.oursprivacy.com/docs/deduplication) for how to keep a client-side and server-side event for the same conversion from being counted twice.
3. **Visitor properties**
   * [Visitor properties](https://docs.oursprivacy.com/docs/visitor-properties-overview) only accept specific visitor properties specified by Ours Privacy. You can see the complete [list here](https://docs.oursprivacy.com/docs/visitor-properties-overview). These properties can be mapped to your various destinations
4. **Default properties**
   * Default properties are things specific to where the event happened. Ours Privacy 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 the [Ours Privacy Tag Manager](https://docs.oursprivacy.com/docs/tag-manager) or the Web SDK.

### Data Types Available During Dispatch

When configuring destination mappings, you have access to three distinct data types:

* **Event Data (event.\*)**: Captures specific data at the time an event occurs, including event properties and contextual information.
* **Visitor Data (visitor.\*)**: Contains the most up-to-date information about the current visitor session.
* **User Data (user.\*)**: A unified profile created by merging multiple visitors with the same external ID, providing a complete view across all devices and sessions.

See [Data Mapping](https://docs.oursprivacy.com/docs/data-mapping), and [Visitor Properties](https://docs.oursprivacy.com/docs/visitor-properties-overview) for more details.

Both the Javascript library and the [Ours Privacy Tag Manager](https://docs.oursprivacy.com/docs/tag-manager) support sending all of the four properties above.

***

## Event Dispatch Flow

Once an event is tracked, it follows a specific flow through the Ours Privacy platform before being sent to destinations:

**Event → Allow List → Global Data Governance → Destination Mapping → Dispatch**

### 1. Allow List Check

Events are first checked against your [Event Allow List](https://docs.oursprivacy.com/docs/allow-listing-events). Only events that are explicitly allowed will proceed to the next step.

### 2. Global Data Governance

If you have [Global Data Governance](https://docs.oursprivacy.com/docs/global-data-governance) enabled, events are evaluated against your consent rules. Events that match category logic (evaluating to TRUE) will have dispatch stopped for destinations assigned to those categories.

### 3. Destination Mapping

Events that pass the consent check proceed to the [data mapping](https://docs.oursprivacy.com/docs/data-mapping) layer, where event and visitor properties are transformed according to each destination's configuration.

### 4. Dispatch

Finally, events are dispatched to their configured destinations with the transformed data.

***

## Event Names and Naming

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

For example, the mapping shown below renames `Appointment Requested` to `Appointment Booked` before it reaches the destination.

![A custom event mapping that renames an appointment request and hashes the visitor email before dispatch](https://docs.oursprivacy.com/img/data-mapping/data-mapping-img-1.jpg)

***

## Default Parameters Collected

Ours Privacy 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:

![The variable dictionary showing available event and visitor properties for a destination mapping](https://docs.oursprivacy.com/img/understanding-events/understanding-events-img-3.jpg)

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 Privacy 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 Privacy 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 Privacy 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

1. **Add Events**:
   * Add custom events to your [Allow List](https://docs.oursprivacy.com/docs/allow-listing-events) before sending them to destinations.
2. **Use Semantic Event Names**:
   * Name the events in Ours Privacy with a pattern like: "Name Action". For example, "Summer CTA Click" or "Homepage Video View".
3. **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.
4. **Leverage Default Properties**:
   * Take advantage of automatically captured properties to enrich your events without extra effort.
5. **Configure Consent Management**:
   * Use [Global Data Governance](https://docs.oursprivacy.com/docs/global-data-governance) to centrally manage consent rules across multiple destinations.
   * Pass consent properties as event or visitor properties to control dispatch based on user consent.
6. **Test Events with a Test Token**:
   * Use test tokens to safely debug events without impacting production data. See [Tracking and Debugging Events](https://docs.oursprivacy.com/docs/tracking-and-debugging-events).

***

## Event and Payload Limitations

Ours Privacy enforces size and structure limits on events to ensure optimal performance and data integrity. These limits apply to event properties, visitor custom properties, and the overall event payload.

| **Limit Type**                   | **Maximum Value**                               | **Applies To**                                                                |
| -------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- |
| Event name length                | 1,000 characters                                | Event names                                                                   |
| String property value            | 2,000 characters                                | Event properties, visitor properties, custom properties                       |
| `data:` URI in an event property | Media type only, such as `data:application/pdf` | Event properties sent by the web SDK, so an inline file never leaves the page |
| Array length                     | 250 items                                       | Arrays within event properties or custom properties                           |
| Object depth                     | 5 levels                                        | Nested objects in event properties or custom properties                       |
| Custom properties count          | 200 properties                                  | `custom_properties` object                                                    |
| Event object size                | 1MB                                             | Complete event payload                                                        |
| Processed event size             | About 500 KB                                    | The event after processing, including the context Ours Privacy adds           |

These limits help ensure events are processed efficiently and prevent issues with downstream destinations. If your data exceeds these limits, it will be automatically truncated or rejected with an appropriate error message.

***

## Event Deduplication and Idempotency

Ours Privacy ensures data integrity through idempotent event processing using the combination of `visitor_id` and `distinct_id`. This prevents duplicate events, even when copies arrive at the same moment.

### How Idempotency Works

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

* **First Event Wins**: 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

### Events That Arrive Together

When multiple events with the same `visitor_id` and `distinct_id` arrive at nearly the same moment (for example, from network retries), exactly one is stored, and the outcome is the same every time.

This ingestion-level dedup is one of three places deduplication matters: see [Deduplication](https://docs.oursprivacy.com/docs/deduplication) for how Ours Privacy also avoids double-counted conversions at ad platforms and during a parallel-run migration.

***

## Backfilling Historical Events

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

### Event Age Limits

* **Maximum Age**: You can send events up to one year old
* **Time Format**: The `time` field must be in milliseconds since UTC epoch
* **Validation**: Future times are set to the time the event is received

For more details on implementation, see [Server-to-Server Integration](https://docs.oursprivacy.com/docs/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](https://docs.oursprivacy.com/docs/destination-facebook) for a detailed overview of optional and required properties.
