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 :
- SITE_VISIT
for activities happening on a channel of type site
- APP_VISIT
for activities happening on a channel of type app
- DISPLAY_AD
for activities involving ad view and ad click events. See Ads exposure tracking for more information.
- EMAIL
when users read a mail or click in a link inside it. For more information, see Email views and clicks.
- TOUCH
for other activities
There are also activity types specific to automations:
- USER_SCENARIO_START
when a scenario starts
- USER_SCENARIO_STOP
when a scenario stops
- USER_SCENARIO_NODE_ENTER
when a new scenario node is entered
- USER_SCENARIO_NODE_EXIT
when a scenario node is exited
$session_status
String enum
The sessions status, automatically updated by mediarithmics. NO_SESSION
, IN_SESSION
, CLOSED_SESSION
$ttl
Integer
The Time To Live in minutes for the storage of this activity. 0
means no expiration
$user_agent_id
String
The identifier of the user device as provided by the user id mapping service. ex: vec:89090939434
⚠️ Legacy, please use $user_identifiers
instead
$user_account_id
(in addition to $compartment_id
)
String
The user account id of the user
⚠️ Legacy, please use $user_identifiers
instead
$compartment_id
(in addition to
$user_account_id
)
Integer
The ID of the compartment associated with this activity
⚠️ Legacy, please use $user_identifiers
instead
$email_hash
Email Hash Object
The email hash object { “$hash”:…, “$email”:…}
⚠️ Legacy, please use $user_identifiers
instead
$user_identifiers
List of User Identifier
A list of all identifiers relative to the activity. You can have many of each type. ⚠️ Use this list rather than the legacy properties ($user_agent_id, $user_account_id & $compartment_id, $email_hash)
$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 : vec:vector_id
; e.g.: vec:89090939434
Activity Location
field
type
description
$source
String (Optional)
The location source (IP
, GPS
, OTHER
)
$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
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 $item_view
event name if your pages show products.
$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 : [{"$id":"ProductID1"},{"$id":"ProductID2"}]
Each item has the $id
, $ean
, $qty
, $price
, $brand
, $name
, $category1
, $category2
, $category3
and $category4
predefined properties.
$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 $set_user_choice
.
$choice_acceptance_value
Acceptance value of the user choice when event name is $set_user_choice
.
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