> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/standard-events.md).

# Standard events

The predefined event names and properties, and what the platform does automatically when you use them.

## Your goal

Name your events with the predefined names, and fill the predefined properties, so that the platform's built-in processing - analytics, dashboards, funnels, consent handling - works on your data without extra effort.

## Expected outcome

A tracking plan in which every event that has a predefined equivalent uses it, and where custom names are a deliberate choice rather than an accident.

{% hint style="warning" %}
**Always prefer predefined event names and properties** to custom ones when they exist. The platform automates a lot of actions based on them, and using a custom name means silently skipping those steps.

Concretely: `$transaction_confirmed` events are used when calculating conversions and amounts. An `order` event is not.
{% endhint %}

## What an event is

A **UserEvent** is an object composed of an event name and a list of properties, each property being a name and a value. Events are what you send; the platform aggregates and encapsulates them into [UserActivity](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md#the-useractivity-object) objects.

```json
{
    "$ts": 3489009384393,
    "$event_name": "$transaction_confirmed",
    "$properties": {
        "$items": [
            {
                 "$id": "product_ID",
                 "$qty": 20,
                 "$price": 102.8,
                 "$brand": "Apple",
                 "$category1": "Category 1",
                 "$category2": "Category 2"
            },
            {
                 "$id": "product_ID2",
                 "$qty": 12,
                 "$price": 3.4,
                 "$brand": "Microsoft"
            }
        ],
        "$currency": "EUR"
    }
}
```

{% hint style="info" %}
**Base property names all begin with `$`.** If you avoid that character in your own property names, you can always tell platform properties from yours at a glance.
{% endhint %}

## Predefined event names

Using a predefined event name gives you adapted automatic processing on that event.

| Event name               | What it means                                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `$page_view`             | The user viewed a page. See the warning below - these events do not persist.                                                |
| `$home_view`             | The user viewed the home page.                                                                                              |
| `$item_view`             | The user viewed an item.                                                                                                    |
| `$item_list_view`        | The user viewed a list of items.                                                                                            |
| `$basket_view`           | The user viewed the basket.                                                                                                 |
| `$transaction_confirmed` | The user completed a transaction.                                                                                           |
| `$conversion`            | The user completed a conversion. Registered by the integrator, or created automatically by the platform when a goal is met. |
| `$app_install`           | The user installed an app.                                                                                                  |
| `$app_update`            | The user updated an app.                                                                                                    |
| `$app_open`              | The user opened or resumed an app.                                                                                          |
| `$ad_view`               | The user was exposed to a display ad.                                                                                       |
| `$ad_click`              | The user clicked an ad.                                                                                                     |
| `$email_view`            | The user opened an email.                                                                                                   |
| `$email_click`           | The user opened a link in an email.                                                                                         |
| `$set_user_choice`       | The user gave consent to, or objected to, a processing activity.                                                            |

{% hint style="danger" %}
`$page_view` events **serve only in session aggregation**, to produce correct information on the user activity. **They are dropped when the session closes** and are no longer visible on the platform.

If you want a queryable record of the pages a user viewed, name the event differently - or use `$item_view` if your pages show products.
{% endhint %}

## Predefined event properties

| Property                       | What it holds                                                                                                                                                                                                                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$items`                       | An array of products associated with the event, mainly used in e-commerce product tracking. Example: `[{"$id":"ProductID1"},{"$id":"ProductID2"}]`. Each item supports `$id`, `$ean`, `$qty`, `$price`, `$brand`, `$name`, `$category1`, `$category2`, `$category3`, `$category4`. |
| `$campaign_technical_name`     | Technical name of a campaign associated with the event, when tracking ads exposure.                                                                                                                                                                                                |
| `$sub_campaign_technical_name` | Technical name of a sub-campaign associated with the event, when tracking ads exposure.                                                                                                                                                                                            |
| `$creative_technical_name`     | Technical name of a creative associated with the event.                                                                                                                                                                                                                            |
| `$processing_token`            | Token of the processing activity concerned, when the event name is `$set_user_choice`.                                                                                                                                                                                             |
| `$choice_acceptance_value`     | Acceptance value of the user choice, when the event name is `$set_user_choice`.                                                                                                                                                                                                    |

Properties used to declare an activity origin are listed in [Collect data in real time](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md#declaring-an-origin-from-event-properties).

## Which events feed which analytics

Data entering your datamart is stored in a multi-model database optimised for different usages. To display performance analytics - session duration, conversions, funnels - the platform **duplicates some user activities and optimises them**. That duplication only happens for predefined events.

| Event name               | Feeds                                                                                                     | Properties that matter                                                                                                                                                                                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$transaction_confirmed` | Home dashboards (*E-Commerce Engagement*), segment dashboards (*E-Commerce Engagement*), funnel analytics | `$items` - the products in the transaction; `$items.$qty` and `$items.$price` for conversion amounts; `$items.$id` for product IDs in funnel analytics; `$items.$brand` for the brand filter; `$items.$category1` to `$category4` for categorisation in funnel analytics |
| `$item_view`             | Funnel analytics                                                                                          | `$items` - one product only; `$items.$price` for conversion amounts; `$items.$id`, `$items.$brand`, `$items.$category1` to `$category4` as above                                                                                                                         |
| `$basket_view`           | Funnel analytics                                                                                          | `$items` - the products in the basket; `$items.$qty` and `$items.$price` for conversion amounts; `$items.$id`, `$items.$brand`, `$items.$category1` to `$category4` as above                                                                                             |

{% hint style="info" %}
Analytics data built this way is kept for **4 months**, to keep query performance predictable. See [Activities analytics](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/activities-analytics.md).
{% endhint %}

## If you already send custom events

You do not have to redo your tracking to benefit from analytics: events can be transformed on the way in. An [event rule](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/event-rules.md) can rename or reshape an incoming event, so a custom event carrying the right information can become its predefined equivalent before it is stored.

## Verify

* Every event in your tracking plan that has a predefined equivalent uses it.
* Product events carry `$items` with `$id`, `$price`, and `$qty` where amounts are expected.
* You are not relying on `$page_view` for anything queryable.
* Built-in dashboards show non-zero conversions and amounts after collection starts.

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Define your tracking plan</strong></td><td>Turn this catalogue into a plan per property.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/define-your-tracking-plan.md">Define your tracking plan</a></td></tr><tr><td><strong>Activities analytics</strong></td><td>What the platform builds from these events.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/activities-analytics.md">Activities analytics</a></td></tr><tr><td><strong>Event rules</strong></td><td>Reshape incoming events into predefined ones.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/event-rules.md">Event rules</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/standard-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.