User activities and events
User activity management is at the core of audience management services.
A user activity is a collection of events done by a single user in a given period of time. For instance, mediarithmics considers that a website activity is a session of no more than 30mn on a given website. An user activity is also linked to its referrer (like Google, Yahoo!, ...), if an user switch of referrer an go back to the same website, it will be considered like a new activity. Events can be given any name and any properties, but some predefined names and properties can be used to trigger specific treatment on the data.
You send user events to mediarithmics, that are aggregated and encapsulated into user activities. Some user activities only have one user event, but some can have multiple events.
To visualize user activities for a specific user, go to the navigator > Audience > Monitoring and select a user id.
You can then view the complete JSON for each activity.
User activities and events can be indexed and queried using APIs and/or the query engine, if their properties fit the object tree schema.
When an activity is ingested via the real time tracking pipeline, it will trigger some dedicated processes like event rules, activity analyzers, ...
User Activity object
A minimal user activity is an object with the following properties.
field | type | description |
$ts | Long | The timestamp of the activity. For a session, it should correspond to the start date (Unix Epoch Time in milliseconds) |
$type | String enum | The activity type :
- There are also activity types specific to automations: - - - - |
$session_status | String enum | The sessions status, automatically updated by mediarithmics. |
$ttl | Integer | The Time To Live in minutes for the storage of this activity. |
$user_agent_id | String | The identifier of the user device as provided by the user id mapping service. ex: |
$user_account_id (in addition to | String | The user account id of the user |
$compartment_id (in addition to
| Integer | The ID of the compartment associated with this activity |
$email_hash | Email Hash Object | The email hash object { “$hash”:…, “$email”:…} |
$user_identifiers | List of User Identifier | A list of all identifiers relative to the activity. You can have many of each type. You can either use this list, or use $user_agent_id, $user_account_id, $compartment_id, and $email_hash |
$origin | The activity origin | |
$location | The activity location | |
$events | List of User Event | A list of user events attached to this activity |
$unique_key | String | The unique_key of the activity formatted as an uuid-v1. If empty, the platform generates one automatically |
[any custom property] | Any | The value of a custom property |
User activities could be enriched with any custom property, and specific activity types can have additional base properties.
Base properties names all begin with '$'. That's a good way to differentiate base properties and your custom properties if you don't start your property names with that same character.
Always prefer predefined properties to custom properties when they exist, as the platform automates a lot of actions based on those properties. You could miss some critical steps in having well organized data.
Activities are limited to 8000 characters.
For user identification you can : - either use $user_identifiers; - or use $user_agent_id, $user_account_id, $compartment_id, and $email_hash
Site visits user activities
Their type is SITE_VISIT. They have those additional base properties :
field | type | description |
$site_id | String | The site ID (channel) |
$session_duration | Integer | The session duration in seconds. |
App visits user activities
Their type is APP_VISIT. They have those additional base properties :
field | type | description |
$app_id | String | The mobile app ID (channel) |
$session_duration | Integer (Optional) | The session duration in seconds. |
Channels
If you have multiple sites and/or apps, you can create a channel for each one of them. Each channel will have an ID, representing either a site ID or an app ID.
When you attach site IDs or app IDs to your user activities, you link them to the corresponding channel.
This is useful for attaching data privacy rules to a site or an app, or when you'll want to create queries and segments, allowing you to select only users having activities on a specific site or app.
User Identifier
A user identifier is either a user account, a user email, or a user agent.
User Account
field | type | description |
$type | Constant String | USER_ACCOUNT |
$compartment_id | Integer | The ID of the compartment associated with this activity |
$user_account_id | String | The user account id of the user |
User Email
field | type | description |
$type | Constant String | USER_EMAIL |
$hash | String | The email hash |
String (Optional) | The "raw" email |
User Agent
field | type | description |
$type | Constant String | USER_AGENT |
$user_agent_id | String | The user agent id
Currently support agent type :
- vector id : |
Activity Location
field | type | description |
$source | String (Optional) | The location source ( |
$country | String (Optional) | The country’s name |
$region | String (Optional) | The region’s name |
$iso_region | String (Optional) | The region iso (ISO 3166-2) |
$city | String (Optional) | The city’s name |
$iso_city | String (Optional) | The city iso (UN/LOCODE) |
$zip_code | String (Optional) | The zip code |
$latlon | Array[Double, Double] | The latitude and longitude where the first element is the latitude and the second the longitude |
Activity Origin
In the mediarithmics vocabulary, the activity origin refers to the last digital channel leading to user interaction. It is key information to be used to analyze the results and the performance of marketing activities.
This interaction can be a Touch (the user views a banner or an email) or a Visit (the user visits a web site or an app). In both cases, the $origin object of the user activity is used to capture the information related to the originating channel.
The $origin object is a customizable object with predefined properties as follows:
origin field | description |
$ts | |
$channel | the communication channel. ex: cpc, newsletter, banner, video, ... |
$source | the source of the traffic. ex: google.com, news-foo.com, ... |
$campaign_name | the campaign name |
$campaign_technical_name | the campaign technical name |
$campaign_id | the campaign id |
$sub_campaign_technical_name | the sub campaign (Ad Group) technical name |
$sub_campaign_id | the sub campaign (Ad Group) id |
$message_id | |
$message_technical_name | |
$keywords | the keywords used in the search ex:sport+shoes |
$creative_name | the creative name |
$creative_technical_name | the creative technical name |
$creative_id | the creative id |
$engagement_content_id | |
$social_network | the social network |
$referral_path | the URL of the referral |
$log_id | the custom unique identifier for the activity origin |
$gclid | the unique identifier for a Google AdWords click |
Origin calculation
The origin of user activity is calculated in different ways depending on the activity type (Touch/Visit) and source (Tag/API):
for a visit on a site or an app: from the analysis of the referrer and/or the query parameters provided in the destination URL (like the UTM parameters used by Google Analytics)
for touch events generated by campaigns delivered by the mediarithmics platform, the origin is automatically calculated from campaign information
for touch events (pixel events in emails or banners) the origin is calculated from the properties provided in the event (predefined properties)
for an activity inserted through the API, the origin fields can be directly filled with the relevant data.
A user activity can only have one origin. If a user comes back from a different origin in a live session. The current session is closed and a new session is opened with the second origin.
Origin detection based on Google Analytics parameters (UTM)
Here is the table of correspondence between mediarithmics origin fields and Google Analytics parameters:
origin field | url parameters | example / description |
$channel | utm_medium | utm_medium = email or $channel = email |
$source | utm_source | utm_source = base loyalty program |
$campaign_name | utm_campaign | utm_campaign = back to school |
$creative_name | utm_content | utm_content = template 1 |
$keywords | utm_term | utm_term = sport+shoes or $keywords = sport+shoes |
$gclid | gclid | Google Click Identifier |
Origin detection based on AT Internet parameter (xtor)
Here is the table of correspondence between mediarithmics origin fields and AT Internet parameter:The structure of the xtor parameter is as follows:
The xtor parameter is automatically analyzed to fill the following origin fields:
origin field | xtor field | example / description |
$source | A | EPR when xtor=EPR-14234 |
$campaign_name | B | 7880 when xtor=AD-7880 |
$creative_name | C | ad_version7 when xtor=AD-3030-ad_version7 |
Marketing Channel inference
According to AT Internet documentation about xtor parameter, source may be related to marketing channel.Here is the table of correspondance between AT Internet source and mediarithmics channel origin field
source | channel |
EPR | |
EREC | |
ES | |
AD | $rtb_display |
AL | $affiliation |
Origin declaration with predefined event properties
When the user event is declared through a tag it is possible to add predefined event properties to declare an activity origin.
Here is the list of the predefined properties :
origin field | predefined event properties | example / description |
$source | $source | $source=crm_database |
$campaign_name | $campaign_name | $campaign_name=back to school |
$campaign_technical_name | $ctn | $ctn=DISPLAY-BACK-TO-SCHOOL |
$campaign_id | $caid | $caid=8989 |
$sub_campaign_technical_name | $scatn | $scatn=STRATEGY-1, the sub campaign technical name is equivalent to the ad group technical name |
$sub_campaign_id | $scaid | $scaid=8782, sub campaign id is equivalent to the ad group id |
$creative_name | $creative_name | |
$creative_technical_name | $crtn | $crtn=special-banner |
$keywords | $keywords | $keywords = sport+shoes |
$social network | $social_network | |
$referral path | $referral_path | |
$log_id | $log_id | unique custom identifier |
$gclid | $gclid | Google Click Identifier |
Activity unique key
In mediarithmics, each unique activity is stored with 4 different accesses in this order:
Datamart_id, user_point_id, ts and unique_key.
It means that when those 4 parameters are identical between 2 activities, the new one cancels and replaces the old one. If one of the parameter differs then a new activity is created.
Unique key calculation
This unique key is an uuid format. It can be calculated by the platform or the user itself.
The best practice is to used uuid-v1 when generated by the user as it’s not a random value but calculated on the timestamp and a unique String.
mediarithmics tag through user-event-front: the unique_key is generated by the platform.
mediarithmics apis through datamart-front: the unique_key can be calculated by the user. If empty, it’s generated by the platform.
mediartihmics document import: the unique_key can be calculated by the user. If empty, it’s generated by the platform.
When generated manually, the user has to select a key property (such as an order_id, a unique id generated on client size) or properties concatenation in order for the String to be unique.
The uuid-v1 also need a timestamp to be generated and it's highly recommended to select the activity's one.
See additional documentation https://www.npmjs.com/package/uuid#uuidv1options-buffer-offset
User Events object
A User Event is an object composed of an event name and a list of properties. Each property is composed of a name and a value.
Predefined event names
Using some predefined event names will allow you to have useful adapted automatic processing on some of your events.
event name | description |
$page_view | The user has viewed a page.
Events with this event name only serve in session aggregation to have correct information on the user activity. They will be dropped when the session closes, and you won't see them on the platform anymore. If you wish to keep a record of the pages a user viewed in your site and create queries based on that data, you should name your event differently. You can also use the |
$home_view | The user has viewed the home page |
$item_view | The user has viewed an item |
$item_list_view | The user has viewed a list of items |
$basket_view | The user has viewed the basket |
$transaction_confirmed | The user has completed a transaction |
$conversion | The user has completed a conversion. This event is either registered by the integrator or automatically craeted by the platform when a goal is met. |
$app_install | The user has installed a mobile app |
$app_update | The user has updated a mobile app |
$app_open | The user has opened an app or resumed it |
$ad_view | The user has been exposed to a display add |
$ad_click | The user has clicked on an app |
$email_view | The user has opened an email |
$email_click | The user has opened a link in an email |
$set_user_choice | The user has given consent or objected to a processing activity |
Always prefer predefined event names to custom events when they exist, as the platform automates a lot of actions based on those names. You could miss some critical steps in having well organized data.
Predefined event properties
Using some predefined event properties will allow you to have useful adapted automatic processing on some of your events.
property name | description |
$items | An array of products associated with the event. Mainly used in products tracking for e-commerce sites.
Example value : Each item has the |
$campaign_technical_name | Technical name of a campaign associated to the event when tracking ads exposure. |
$sub_campaign_technical_name | Technical name of a sub campaign associated to the event when tracking ads exposure. |
$creative_technical_name | Technical name of a creative associated to the event |
$processing_token | Token of the associated processing activity when event name is |
$choice_acceptance_value | Acceptance value of the user choice when event name is |
Always prefer predefined event properties to custom event properties when they exist, as the platform automates a lot of actions based on those names. You could miss some critical steps in having well organized data.
User Activity JSON schema and TypeScript interfaces
Below is the JSON schema for a single activity, according to the rules enacted in this documentation.
Last updated