1 of 100

Developer

UserPoint

A UserPoint is a 360° vision of a unique user on the platform.

It is composed of different sets of data to cover all the user aspects providing a 360° view (online and offline):

UserActivity represent an interaction with the user
UserProfile represent a summary of timeless information about the user, like first name, last name, birth date...
UserSegment are here to capture that the user belongs to a particular group of users
UserChoice capture that the user has given his consent for a specific type of data processing
UserTrait represent a calculated attribute used to describe the user.

UserPoint merges

Imagine you are going to a site with firefox, and you go back to that site later on safari. At the moment, there is no way for the platform to know that all those actions are from the same user. You'll have two UserPoints: one with the UserDeviceTechnicalId from firefox and the other with the UserDeviceTechnicalId from safari. If later you log into the site with your UserAccount on both navigators, the two UserPoint will be associated with a common UserAccount ID identifier. The platform will automatically merge the two UserPoint and their activities to represent the reality that we now know those two users were the same.

UserPoint merges can only be triggered by :

UserActivity updates
User identifiers association declarations

The merge will result in a UserPoint survivor, to which we migrate all the data related to the previous two UserPoint.

User identifiers

It is important to distinguish the nodes representing a user identifier and the nodes describing content on the user.

Every activity or import that'll have one of those properties set will automatically be related to the correct UserPoint.

Any activity using an identifier that doesn't already exist in the datamart will trigger the creation of a new UserPoint.

You can bulk associate, dissociate or delete user identifiers using the bulk import feature.

There are three different types of user identifiers:

User accounts
User emails
User device points and device technical ids

Device-based Network IDs

Managing device registries in the mediarithmics platform

Device-based Network IDs refer to Device Registries because each device is assigned a "registry" where its identifiers are stored.

How to active a Device Registry on a datamart

Here are common steps to activate a Device registry on a specific datamart:

If you have a single datamart, the Device Registry is automatically activated, and you can go to the next step.
If you have multiple datamarts, you must manually activate the Device Registry:
1. Go to Navigator > Settings > Organisation > Device Registries.
2. Select your Device Registry.
3. Click More button to open the menu.
4. Choose Edit linked datamarts.
5. Select all datamarts where you want to activate the Device Registry.

Custom Device ID integration

A UserPoint can be associated with multiple UserDevicePoint. Each user device point can include:

Multiple device technical identifiers
One device information record

Create a new registry

Go to Navigator > Settings > Organisation > Device Registries.
In the First-party device registries section, click on New Registry.
Specify the following details:

Parameters

Description

Name

Name of the Device Registry

Token

A technical identifier used to link the Device Registry with the JS Tag

Type

Must be one of the following enums:

MOBILE_VENDOR_ID ,CUSTOM_DEVICE_ID

Go to Navigator > Settings > Organisation > Device Registries.
In the Shared device registries section, click on Manage subscriptions.
Select Subscribe to the desired registry.

If you have multiple datamarts, don't forget to activate your Device Registry on all datamarts.

ID5

For ID5, you need to :

Subscribe to ID5
Activate ID5 data ingestion from websites

Go to Navigator > Settings > Organisation > Device Registries.
In the Shared device registries section, click on Manage subscriptions
Subscribe to ID5.

If you have multiple datamarts, activate the ID5 subscription on all datamarts.

Activate ID5 ingestion for your websites

ID5 requires a specific technical configuration to be properly ingested from your website.

Please contact your Account Manager to complete the ID5 configuration for your channel (an activity analyzer will be added to your channel to handle ID5 IDs).

First ID

For First ID, you need to :

Subscribe to First ID
Activate First ID data ingestion from Websites

Go to Navigator > Settings > Organisation > Device Registries.
In the Shared device registries section, click Manage subscriptions.
Subscribe to First ID.

If you have multiple datamarts, don't forget to activate First ID on all datamarts.

Activate First ID ingestion from websites

First ID requires a modification of the user-event-tag to ingest the identifier. Follow these steps:

Head to Navigator > Settings > Datamart > Channels.
Select the site where you want to activate automated First ID capture.
Go to JS Tag Configuration > Device Identification.
Enable First ID.
Repeat these steps for all site where First ID data collection is expected.

IP address

IP address automatic capture is only available for CTV channels. If you wish to discuss activating it for Site or Mobile channels please get in touch with your account manager.

For IP address, you have 2 options :

Option 1 : Activate auto IP address capture for a CTV channel

Option 2 : Create dedicated registries then activate auto capture

Option #1

If you wish to have 2 dedicated registries for each CTV channel

Go to Navigator > Settings >Channels
Select an existing CTV Channel or create a new one
In the IP addresses capture section, toggle "Active"
Save

This will automatically create dedicated registries to store IPv4 and IPv6 addresses. All captured IP addresses will then be stored in one of these two registries.

If you have multiple CTV channels don't forget to do this for each one.

Option #2

If you wish to use the same 2 registries for all your CTV channels

Create 2 devices registries Navigator>Settings>Organisation>Device Registries
1. One of type IP_V4_ADDRESS_ID
2. One of type IP_V6_ADDRESS_ID
Activate automatic IP capture on your CTV channel(s) : Navigator > Settings >Channels
Select an existing CTV Channel or create a new one
In the IP addresses capture section, toggle "Active"
Check the "Use exisiting device registries" and select the 2 registries you created
Save

User-based Network IDs

Managing compartments in the mediarithmics platform

User-based Network IDs refer to Compartments because each user network ID is assigned a compartment where its identifiers are stored.

How to activate a compartment on a datamart

Here are general steps to follow in order to activate a Compartment on a specific datamart:

If you have a single datamart, the Compartment is automatically activated.
If you have multiple datamarts, you must activate it on every datamart
1. Head to Navigator > Settings > Datamart > Compartments.
2. Select your Compartment.
3. Click to the More button to open the menu.
4. Choose Edit linked datamarts.
5. Select the datamart where you want to activate the Compartment.

Activate IDs across your organisations:

For community-created user IDs, activate them across organizations by selecting Enable Compartment in the Shared User Account Compartments Enabled section.

Custom User ID integration

Custom User IDs are used to identify your users with your systems such as CRMs, loyalty programs, or authentication systems.

Create a Custom User ID

Go to Navigator > Settings > Organisation > Compartments.
In the First-party user account compartments section, click on New Compartment.
Specify the following details:

Parameters

Description

Name

Name of the Compartment

Token

A technical identifier used to link the Compartment with the JS Tag

If you have multiple datamarts, don't forget to activate the new Compartment on all other datamarts.

UTIQ martechpass

Understand UTIQ identifiers

UTIQ proposes two types of identifiers:

UTIQ martechpass (mobile): refers to identifiers coming from mobile network connections
UTIQ martechpass (fixed): refers to identifiers coming from internet box connections

To subscribe:

Go to Navigator > Settings > Organisation > Compartments.
In the Shared user account compartments section, click on Manage subscriptions.
Subscribe to:
- UTIQ martechpass (mobile)
- UTIQ martechpass (fixed)

If you manage multiple datamarts, ensure UTIQ is activated on each one.

You must subscribe to each type individually, depending on the identifiers you want to capture. The configuration steps are the same for both mobile and fixed identifiers.

Activate UTIQ ingestion from your websites

UTIQ IDs can be ingested natively via the user-event-tag when users browse your websites.

To enable automatic ingestion:

Go to Navigator > Settings > Datamart > Channels.
Select the site where you want to activate UTIQ capture.
Under JS Tag Configuration > Device Identification, enable:
- UTIQ martechpass (mobile)
- UTIQ martechpass (fixed)
Repeat this process for each website where UTIQ ID capture is
required.

Storage and impact on user point merges

The storage method for UTIQ identifiers depends on their type, which directly impacts how UserPoint are merged:

UTIQ martechpass (mobile): stored as UserAccount identifiers in compartment 20. The identifier value is provided in the user_account_id property. These act as reconciliation keys, triggering a User Point merge when the same identifier is seen across different sessions.

{
    "type": "USER_ACCOUNT",
    "user_account_id": "mt1-k4LwxGWEn-...........",
    "creation_ts": 1770466916312,
    "compartment_id": 20,
    "expiration_ts": 1778241090397
}

UTIQ martechpass (fixed): stored as UserProfile in compartment 21. The identifier value is provided in the $utiq_martechpass_fixed property. These are anonymous profiles (no user_account_id and therefore not linked to any userAccount) and do not trigger any UserPoint merge.

    {
        "$compartment_id": "21",
        "$last_modified_ts": 1774049259779,
        "$expiration_ts": 1779898252683,
        "$creation_ts": 1774049244368,
        "$utiq_martechpass_fixed": "mt2-k4LwxGWEn-..........."
    }

UserAccount

Definition

UserAccount identify a user registered on your different systems, like your CRM, a loyalty program or any authentication system. They have the following properties:

Property

Type

Description

user_account_id

String

Usually the same as the ID as the source, like your CRM.

compartment_id

String

Compartment associated with the user account

creation_ts

Timestamp

Account's creation timestamp

Always use the user_account_id in correlation with a compartment_id to identify a user by its account. If you don't specify a compartment_id, then the default compartment will be used.

A Compartment is a group that organizes specific user account identifiers. Each compartment has a unique ID that is used to identify the corresponding user account identifier. For instance, “UTIQ Martechpass” might have the compartment id 20.

There are two categories of Compartments:

The First-party user account compartments which compartments contain user account identifiers created within your organization, such as CRM identifiers.
Shared user account compartments which include user account identifiers shared from another organisation.

For instance, if you wish to add UTIQ to your datamart, first subscribe to it within your community organisation. It will then be automatically shared with your other organisations, but you’ll still need to activate it within your datamart.

UserEmail

Users can have multiple UserEmail registered on the platform. They have the following properties:

Property

Type

description

hash

Hashed user email. Always use the same hashing function (ex: SHA-256) in your datamart and all its integrations to allow proper matching between data flows.

String

Optional. User's email, not hashed.

creation_ts

Timestamp

When the email was registered on the platform

expiration_ts

Timestamp (optional)

Email's eventual expiration timestamp

The hash property is mandatory and is the property used to identify a user (provided in $hash property in User activities request).

UserDeviceTechnicalId

In each datamart, all device information is stored within a device graph:

Devices are represented by UserDevicePoint
Device identifiers are represented by UserDeviceTechnicalId

A UserPoint can have multiple user device points. A user device point can have multiple user device technical identifiers, and one device info.

UserPoint
|
|---------UserDevicePoint--------------------------DeviceInfo: PC - CHROME BROWSER
|                |---------UserDeviceTechnicalId: 1P cookie
|                |---------UserDeviceTechnicalId: Network ID
|                |---------UserDeviceTechnicalId: 3P cookie
|
|---------UserDevicePoint--------------------------DeviceInfo: ANDROID TABLET
|                |---------UserDeviceTechnicalId: Mobile advertising id
|                |---------UserDeviceTechnicalId: Mobile vendor id

Organizing device technical identifiers within registries

Device technical identifiers are related to a registry. There are 6 types of registries:

Type

Description

INSTALLATION_ID

For each site on which the installation ID feature is activated, a registry of type INSTALLATION_ID is created.

MOBILE_ADVERTISING_ID

Registries representing mobile advertising ids that can be shared across editors are related to this type. It includes for instance Android Advertising IDs (AAID) and Apple Identifier for Advertisers (IDFA).

MOBILE_VENDOR_ID

Registries representing mobile ids that can be only be shared among apps of the same developer account are related to this type. This includes for instance Apple Identifier for Vendors (IDFV).

Registries are related to organisations. You can manage them by going to Navigator > Settings > Organisation > Device registries.

You can create your own registries under the types MOBILE_VENDOR_ID and CUSTOM_DEVICE_ID, IP_V4_ADDRESS_ID, IP_V6_ADDRESS_ID or subscribe to existing registries under other types. For more information of IP addresses refer to this page. Once created, you can activate them on the organisation datamarts.

You can set up a expiration duration for identifiers stored in registries you created manually. This will only apply to identifiers captured after setting up the expiration duration.

Registries of type INSTALLATION_ID are automatically created and removed by the platform.

Do not forget to create or subscribe to the required registries before using them to identify user data. If user data is received under unknown registries, identifiers will be removed and data may not be ingested properly.

Two web browsers on the same desktop PC are considered as two distinct agents. For example, your Chrome browser on your Windows laptop is a different device than your Firefox browser on the same laptop. On smartphones, the web browser and the phone itself are considered as two distinct agents.

Some device registry identifiers require Channel configuration updates to trigger tracking using them on your websites properly.

Merge of device points

When two device technical ids are associated, the related device points are merged. This can happen:

When capturing user activities with multiple identifiers
When using the identifier association feature

If the related device points are linked to different UserPoint, a merge of device points will induce the merge of UserPoint as well.

For some ids that are considered as probabilistic (e.g. that can create false positive matchings of users), the merge of UserDevicePoint/UserPoint will not be allowed to avoid inconsistencies in your ID graph.

You contact your Account manager for additional information

Description of device graph documents

Hereafter is the description of the documents and their properties, as they can be fetched on the APIs.

User device point

Property

Type

Description

String

The document identifier. Formatted as udp:-1234

type

Enum UserIdentifierType

In the case of device points, this property takes the value "USER_DEVICE_POINT"

`device` property of user device point

Property

Type

Description

brand

String

The brand of the device (ex.: "Apple")

model

String

The model of the device (ex.: "Iphone 14")

User device technical identifier

Property

Type

Description

user_agent_id

String

The value of the identifier. See format

registry_id

String

The registry to which the technical identifier

The properties available in the documents might differ slightly from the ones of the runtime schema.

`user_agent_id`

user_agent_id property allows to use device identifiers in a single property by concatenating several informations such as registry type, registry id and the id value.

The Installation ID can appear in different formats depending on where it is used:

Location

Value format

Example

Cookie stored in the user' browser

<version_prefix><base64(value)> w

aMGQ0YTU4Y2EtMTRlNS0xMWVlLWJlNTYtMDI0MmFjMTIwMDAy

Used in authenticated endpoints

ins:<registry_id>:<value>

ins:1001:0d4a58ca-14e5-11ee-be56-0242ac120002

Note that version_prefix is currently defined as a.

mediarithmics offers to use its third-party cookie, the vector ID. More information can be found on the cookie documentation.

mediarithmics third-party cookie can be used as a user identifier with two different formats:

vec:<value>
mum:<value>

Both formats are equivalent: the first one is the exact format stored in the cookie, the second one is the one stored as a technical identifier in the the datamart.

Example: vec:89998434 / mum:89998434

For a given device point, the vector ID can be retrieved:

In the technical_identifiers list as a device technical id of type MUM_ID ; in which case the identifier format will be mum:89998434
In the mappings list related to the device point

Partners' third party cookies

The formatting of advertising cookie values from Google and Xandr is a bit specific due to the historical activity of mediarithmics as a DSP provider:

tech:goo:<value> for Google advertising cookies
tech:apx:<value> for Xandr advertising cookies

For other partners, their third-party cookie value is attached to a web domain that is defined by mediarithmics. The identifier format is as follows:

web:<web_domain_id>:<value>

The web domain designates the partner-domain.com and value the identifier value inside the cookie on partner-domain.com.

user_agent_id formatting - Mobile application identifiers

Mobile advertising identifiers

The generic format for mobile advertising ids is:

mob:<os>:<encoding>:<value>.

The os field designates the OS of device: and for Android, ios for iOS.

The encoding field describes how the value is encoded. Available values are: raw for no encoding, sha1 for SHA1, md5 for MD5.

The value field contains the mobile advertising id value, encoded according to the previous field. The non-encoded ID should be in lower case for Android and in uppercase for iOS.

Example:

mob:ios:raw:12345654-ABCD-1234-A1B2-123456789876
mob:and:raw:12345678-abcd-1234-a1b2-123456789876

Mobile vendor identifiers

The compressed format for mobile vendor ids is:

mov:<os>:<registry_id>:<value>

The os field designates the OS of device: and for Android, ios for iOS.

The registry_id field designates the registry to which this device id should be linked.

value refers to the identifier value as generated within the mobile application.

user_agent_id formatting - CTV identifiers

CTV advertising identifiers

The generic format for CTV advertising ids is:

tv:<registry_id>:<value>

IP addresses captured on CTV channel

ipv4:<registry_id>:<value> for registries of type IPV4_ADDRESS_ID
ipv6:<registry_id>:<value> for registries of type IPV6_ADDRESS_ID

value will contain the raw IP address (no hashing or normalization)

While there is no registry dedicated to store CTV vendor identifiers, you can still use either custom registries or Mobile vendor ones (if you want to store the value of the os in the identifier)

user_agent_id formatting - Other device identifiers

net:<registry_id>:<value> for device technical ids of type NETWORK_ID
dev:<registry_id>:<value> for type CUSTOM_DEVICE_ID
udp:<value> if you want to use directly the device point identifier instead of a custom device identifier.

User agents (legacy)

User agent is a legacy format that is being replaced replaced by user device points and user device technical identifiers.

User agents are the legacy format to store device identifiers. Several user agents can be attached to a UserPoint, and each user agent has a device info object.

UserPoint
|
|---------UserAgent: vec:1111--------------------------DeviceInfo: PC - CHROME BROWSER              
|
|---------UserAgent: vec:2222--------------------------DeviceInfo: ANDROID TABLET

All user agents are identified by a vector ID.

User agents have the following properties:

Property

Type

Description

vector_id

String

Unique ID generated by mediarithmics and associated with each agent

device

Object

Device pieces of information such as operating system and browser

Agent-based operations like visiting a website or seeing an ad will generally automatically leverage the user agent to identify the user. You can use an agent to identify a user, usually with a user_agent_id field in the requests.

// Browser based agent
{
    "vector_id": "vec:12345654321",
    "device": {
        "form_factor": "SMARTPHONE",
        "os_family": "IOS",
        "browser_family": "SAFARI",
        "browser_version": null,
        "brand": null,
        "model": null,
        "os_version": null,
        "carrier": null,
        "raw_value": null,
        "agent_type": "WEB_BROWSER"
    },
    "creation_ts": 1591712194234,
    "mappings": [
        {
            "user_agent_id": "tech:goo:Cazrazrkazeeza-azeree9-azezrze",
            "realm_name": "GOOGLE_OPERATOR"
        },
        {
            "user_agent_id": "tech:apx:12345654321654321",
            "realm_name": "APP_NEXUS_OPERATOR"
        }
    ]
}

The value field contains the string value in lower case, after the optional encoding.

// Mobile application agent
{
    "vector_id": "vec:12345654321",
    "device": {
        "form_factor": "OTHER",
        "os_family": "OTHER",
        "browser_family": null,
        "browser_version": null,
        "brand": null,
        "model": null,
        "os_version": null,
        "carrier": null,
        "raw_value": null,
        "agent_type": null
    },
    "creation_ts": 1573405364473,
    "mappings": [
        {

            // IDFA user agent id with raw encoding: mob:ios:raw:6d92078a-8246-4ba4-ae5b-76104861e7dc
            // IDFA user agent id with SHA1 encoding: mob:ios:sha1:d520a80c026be39edeb9c6e3f37c01f2da5f5e97
            // AAID user agent id with raw encoding: mob:and:raw:97987bca-ae59-4c7d-94ba-ee4f19ab8c21
            // AAID user agent id with MD5 encoding: mob:and:md5:ba06c008973b8a1bff6e087c6149227f
            "user_agent_id": "mob:ios:raw:12345654-8246-1234-ae5b-123456454654",
        }
    ]
},

UserActivity & UserEvent

User activity management is at the core of audience management services.

A UserActivity is a collection of events (UserEvent) 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 UserActivity 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 UserEvent to mediarithmics, that are aggregated and encapsulated into UserActivity. Some UserActivity only have one UserEvent, but some can have multiple UserEvent.

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

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.

A few things to keep in mind :

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.

CTV visits user activities

Their type is Ct_VISIT. They have those additional base properties :

field

type

description

$ctv_id

String

The CTV ID (channel)

$session_duration

Integer (Optional)

The session duration in seconds.

Channels

If you have multiple sites/apps (Mobile or CTV) 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

User Email

field

type

description

$type

Constant String

USER_EMAIL

$hash

String

User Agent

field

type

description

$type

Constant String

USER_AGENT

$user_agent_id

String

User Agent info

Property

Type

Description

$initial_ts

Timestamp

Timestamp at which device has been seen

$form_factor

Enum

Indicates the format of the device. Possible values: PERSONAL_COMPUTER, SMART_TV, GAME_CONSOLE, SMARTPHONE, TABLET, WEARABLE_COMPUTER, OTHER.

Activity Location

field

type

description

$source

String (Optional)

The location source (IP, GPS, OTHER)

$country

String (Optional)

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, ...

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

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:

xtor=A-B-C-D-E-F-G-H

The xtor parameter is automatically analyzed to fill the following origin fields:

origin field

xtor field

example / description

$source

EPR when xtor=EPR-14234

$campaign_name

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

$email

EREC

$email

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=crm_database

$campaign_name

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.

{
    "$ts": 3489009384393,
    "$event_name": "$transaction_confirmed", // Conversion detected
    "$properties": {
        "$items": [
            {
                 "$id": "product_ID", // Used to filter in funnel analytics
                 "$qty": 20, // Used for conversion amounts
                 "$price": 102.8, // Used or conversion amounts
                 "$brand": "Apple" // Used to filter in funnel analytics
                 "$category1": "Category 1", // Used to filter in funnel analytics
                 "$category2": "Category 2", // Used to filter in funnel analytics
                 "$category3": "Category 3", // Used to filter in funnel analytics
                 "$category4": "Category 4" // Used to filter in funnel analytics
             },
             {
                 "$id": "product_ID2",
                 "$qty": 12,
                 "$price": 3.4,
                 "$brand": "Microsoft"
             }
        ],
        "$currency": "EUR"
    }
}

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

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 . Example value : [{"$id":"ProductID1"},{"$id":"ProductID2"}]

Each item has the $id, $ean, $qty , $price, $brand, $name, $category1,

$campaign_technical_name

Technical name of a campaign associated to the event when .

$sub_campaign_technical_name

Technical name of a sub campaign associated to the event when .

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.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$ref": "#/definitions/UserActivity",
    "definitions": {
        "UserActivity": {
            "oneOf": [
                {
                    "$ref": "#/definitions/GenericUserActivity"
                },
                {
                    "$ref": "#/definitions/SiteVisitUserActivity"
                },
                {
                    "$ref": "#/definitions/AppVisitUserActivity"
                },
                {
                    "$ref": "#/definitions/CTVVisitUserActivity"
                }
            ]
        },
        "GenericUserActivity": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$session_status": {
                    "$ref": "#/definitions/UserActivitySessionStatus"
                },
                "$ttl": {
                    "type": "number"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$email_hash": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70767-70920-1071211137-0-212510%3Cdef-interface-792792747-896-1013-792792747-0-7494%2C%22%24type%22%3E%3E"
                },
                "$user_identifiers": {
                    "$ref": "#/definitions/Nullable%3Cdef-alias-792792747-1226-1323-792792747-0-7494%5B%5D%3E"
                },
                "$origin": {
                    "$ref": "#/definitions/Nullable%3CUserActivityOrigin%3E"
                },
                "$location": {
                    "$ref": "#/definitions/Nullable%3CUserActivityLocation%3E"
                },
                "$unique_key": {
                    "$ref": "#/definitions/UUID"
                },
                "$type": {
                    "type": "string",
                    "enum": [
                        "DISPLAY_AD",
                        "EMAIL",
                        "TOUCH",
                        "USER_SCENARIO_START",
                        "USER_SCENARIO_STOP",
                        "USER_SCENARIO_NODE_ENTER",
                        "USER_SCENARIO_NODE_EXIT"
                    ]
                },
                "$events": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/UserActivityEvent"
                    }
                }
            },
            "required": [
                "$email_hash",
                "$events",
                "$location",
                "$origin",
                "$session_status",
                "$ts",
                "$ttl",
                "$type"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "Timestamp": {
            "type": "number"
        },
        "UserActivitySessionStatus": {
            "type": "string",
            "enum": [
                "NO_SESSION",
                "IN_SESSION",
                "CLOSED_SESSION"
            ]
        },
        "Nullable<ID>": {
            "anyOf": [
                {
                    "$ref": "#/definitions/ID"
                },
                {
                    "type": "null"
                }
            ]
        },
        "ID": {
            "type": "string"
        },
        "Nullable<alias-1071211137-70767-70920-1071211137-0-212510<def-interface-792792747-896-1013-792792747-0-7494,\"$type\">>": {
            "anyOf": [
                {
                    "type": "object",
                    "properties": {
                        "$hash": {
                            "type": "string"
                        },
                        "$email": {
                            "$ref": "#/definitions/Nullable%3Cstring%3E"
                        }
                    },
                    "required": [
                        "$hash"
                    ],
                    "additionalProperties": false
                },
                {
                    "type": "null"
                }
            ]
        },
        "Nullable<string>": {
            "type": [
                "string",
                "null"
            ]
        },
        "Nullable<def-alias-792792747-1226-1323-792792747-0-7494[]>": {
            "anyOf": [
                {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/UserIdentifier"
                    }
                },
                {
                    "type": "null"
                }
            ]
        },
        "UserIdentifier": {
            "anyOf": [
                {
                    "$ref": "#/definitions/UserEmailIdentifier"
                },
                {
                    "$ref": "#/definitions/UserAccountIdentifier"
                },
                {
                    "$ref": "#/definitions/UserAgentIdentifier"
                }
            ]
        },
        "UserEmailIdentifier": {
            "type": "object",
            "properties": {
                "$type": {
                    "type": "string",
                    "const": "USER_EMAIL"
                },
                "$hash": {
                    "type": "string"
                },
                "$email": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                }
            },
            "required": [
                "$type",
                "$hash"
            ],
            "additionalProperties": false
        },
        "UserAccountIdentifier": {
            "type": "object",
            "properties": {
                "$type": {
                    "type": "string",
                    "const": "USER_ACCOUNT"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/ID"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$type",
                "$user_account_id",
                "$compartment_id"
            ],
            "additionalProperties": false
        },
        "UserAgentIdentifier": {
            "type": "object",
            "properties": {
                "$type": {
                    "type": "string",
                    "const": "USER_AGENT"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$type",
                "$user_agent_id"
            ],
            "additionalProperties": false
        },
        "Nullable<UserActivityOrigin>": {
            "anyOf": [
                {
                    "$ref": "#/definitions/UserActivityOrigin"
                },
                {
                    "type": "null"
                }
            ]
        },
        "UserActivityOrigin": {
            "type": "object",
            "properties": {
                "$campaign_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$campaign_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$channel": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$creative_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$creative_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$engagement_content_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$gclid": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$keywords": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$log_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$message_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$message_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$referral_path": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$social_network": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$source": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$sub_campaign_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$sub_campaign_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$ts": {
                    "type": "number"
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "Nullable<number>": {
            "type": [
                "number",
                "null"
            ]
        },
        "JsonType": {
            "anyOf": [
                {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                {
                    "type": "boolean"
                },
                {
                    "type": "object"
                },
                {
                    "type": "array",
                    "items": {}
                },
                {
                    "not": {}
                }
            ]
        },
        "Nullable<UserActivityLocation>": {
            "anyOf": [
                {
                    "$ref": "#/definitions/UserActivityLocation"
                },
                {
                    "type": "null"
                }
            ]
        },
        "UserActivityLocation": {
            "type": "object",
            "properties": {
                "$source": {
                    "$ref": "#/definitions/LocationSource"
                },
                "$country": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$region": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$iso_region": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$city": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$iso_city": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$zip_code": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$latlon": {
                    "$ref": "#/definitions/Nullable%3Cnumber%5B%5D%3E"
                }
            },
            "required": [
                "$latlon"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "LocationSource": {
            "type": "string",
            "enum": [
                "GPS",
                "IP",
                "OTHER"
            ]
        },
        "Nullable<number[]>": {
            "anyOf": [
                {
                    "type": "array",
                    "items": {
                        "type": "number"
                    }
                },
                {
                    "type": "null"
                }
            ]
        },
        "UUID": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
        },
        "UserActivityEvent": {
            "anyOf": [
                {
                    "$ref": "#/definitions/GenericUserActivityEvent"
                },
                {
                    "$ref": "#/definitions/AdTrackingEvent"
                },
                {
                    "$ref": "#/definitions/SetUserChoiceEvent"
                },
                {
                    "$ref": "#/definitions/SetUserProfilePropertiesEvent"
                },
                {
                    "$ref": "#/definitions/RetailEvent"
                },
                {
                    "$ref": "#/definitions/ConversionEvent"
                }
            ]
        },
        "GenericUserActivityEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "anyOf": [
                        {
                            "$ref": "#/definitions/EventName"
                        },
                        {
                            "type": "string"
                        }
                    ]
                },
                "$properties": {
                    "$ref": "#/definitions/Customizable"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "Nullable<Timestamp>": {
            "anyOf": [
                {
                    "$ref": "#/definitions/Timestamp"
                },
                {
                    "type": "null"
                }
            ]
        },
        "EventName": {
            "anyOf": [
                {
                    "$ref": "#/definitions/DefaultEventName"
                },
                {
                    "type": "string"
                }
            ]
        },
        "DefaultEventName": {
            "type": "string",
            "enum": [
                "$page_view",
                "$home_view",
                "$category_view",
                "$email_view",
                "$email_click",
                "$email_sent",
                "$email_delivered",
                "$email_soft_bounce",
                "$email_hard_bounce",
                "$email_unsubscribe",
                "$email_complaint",
                "$content_corrections"
            ]
        },
        "Customizable": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "AdTrackingEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "type": "string",
                    "enum": [
                        "$ad_view",
                        "$ad_click"
                    ]
                },
                "$properties": {
                    "$ref": "#/definitions/AdTrackingEventProperties"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "AdTrackingEventProperties": {
            "type": "object",
            "properties": {
                "$url": {
                    "type": "string"
                },
                "$referrer": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$campaign_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$sub_campaign_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$creative_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$message_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$campaign_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$sub_campaign_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$message_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$creative_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            },
            "required": [
                "$url"
            ]
        },
        "SetUserChoiceEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "type": "string",
                    "const": "$set_user_choice"
                },
                "$properties": {
                    "$ref": "#/definitions/SetUserChoiceEventProperties"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "SetUserChoiceEventProperties": {
            "type": "object",
            "properties": {
                "$url": {
                    "type": "string"
                },
                "$referrer": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$processing_token": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$processing_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$choice_acceptance_value": {
                    "type": "boolean"
                },
                "$choice_source_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                }
            },
            "required": [
                "$choice_acceptance_value",
                "$url"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "SetUserProfilePropertiesEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "type": "string",
                    "const": "$set_user_profile_properties"
                },
                "$properties": {
                    "$ref": "#/definitions/Customizable"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "RetailEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "$ref": "#/definitions/RetailEventName"
                },
                "$properties": {
                    "$ref": "#/definitions/RetailEventProperties"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "RetailEventName": {
            "type": "string",
            "enum": [
                "$item_view",
                "$item_list_view",
                "$product_view",
                "$product_list_view",
                "$basket_view",
                "$transaction_confirmed"
            ]
        },
        "RetailEventProperties": {
            "type": "object",
            "properties": {
                "$url": {
                    "type": "string"
                },
                "$referrer": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$items": {
                    "$ref": "#/definitions/Nullable%3Cdef-interface-792792747-3521-3897-792792747-0-7494%5B%5D%3E"
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            },
            "required": [
                "$url"
            ]
        },
        "Nullable<def-interface-792792747-3521-3897-792792747-0-7494[]>": {
            "anyOf": [
                {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/RetailEventPropertiesItem"
                    }
                },
                {
                    "type": "null"
                }
            ]
        },
        "RetailEventPropertiesItem": {
            "type": "object",
            "properties": {
                "$id": {
                    "type": "string"
                },
                "$ean": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$qty": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$price": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$brand": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$category1": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$category2": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$category3": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$category4": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                }
            },
            "required": [
                "$id"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "ConversionEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "type": "string",
                    "const": "$conversion"
                },
                "$properties": {
                    "$ref": "#/definitions/ConversionEventProperties"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "ConversionEventProperties": {
            "type": "object",
            "properties": {
                "$conversion_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$goal_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$conversion_technical_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$goal_technical_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$conversion_value": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$log_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$conversion_external_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$goal_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "SiteVisitUserActivity": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$session_status": {
                    "$ref": "#/definitions/UserActivitySessionStatus"
                },
                "$ttl": {
                    "type": "number"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$email_hash": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70767-70920-1071211137-0-212510%3Cdef-interface-792792747-896-1013-792792747-0-7494%2C%22%24type%22%3E%3E"
                },
                "$user_identifiers": {
                    "$ref": "#/definitions/Nullable%3Cdef-alias-792792747-1226-1323-792792747-0-7494%5B%5D%3E"
                },
                "$origin": {
                    "$ref": "#/definitions/Nullable%3CUserActivityOrigin%3E"
                },
                "$location": {
                    "$ref": "#/definitions/Nullable%3CUserActivityLocation%3E"
                },
                "$unique_key": {
                    "$ref": "#/definitions/UUID"
                },
                "$session_duration": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$error_analyzer_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$analyzer_errors": {
                    "type": "array",
                    "items": {
                        "type": "object"
                    }
                },
                "$topics": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Cnumber%3E%3E%3E"
                },
                "$type": {
                    "type": "string",
                    "const": "SITE_VISIT"
                },
                "$events": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/UserActivityEvent"
                    }
                },
                "$site_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$email_hash",
                "$events",
                "$location",
                "$origin",
                "$session_status",
                "$site_id",
                "$ts",
                "$ttl",
                "$type"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "Nullable<alias-1071211137-70404-70537-1071211137-0-212510<string,alias-1071211137-70404-70537-1071211137-0-212510<string,number>>>": {
            "anyOf": [
                {
                    "type": "object",
                    "additionalProperties": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "number"
                        }
                    }
                },
                {
                    "type": "null"
                }
            ]
        },
        "AppVisitUserActivity": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$session_status": {
                    "$ref": "#/definitions/UserActivitySessionStatus"
                },
                "$ttl": {
                    "type": "number"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$email_hash": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70767-70920-1071211137-0-212510%3Cdef-interface-792792747-896-1013-792792747-0-7494%2C%22%24type%22%3E%3E"
                },
                "$user_identifiers": {
                    "$ref": "#/definitions/Nullable%3Cdef-alias-792792747-1226-1323-792792747-0-7494%5B%5D%3E"
                },
                "$origin": {
                    "$ref": "#/definitions/Nullable%3CUserActivityOrigin%3E"
                },
                "$location": {
                    "$ref": "#/definitions/Nullable%3CUserActivityLocation%3E"
                },
                "$unique_key": {
                    "$ref": "#/definitions/UUID"
                },
                "$session_duration": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$error_analyzer_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$analyzer_errors": {
                    "type": "array",
                    "items": {
                        "type": "object"
                    }
                },
                "$topics": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Cnumber%3E%3E%3E"
                },
                "$type": {
                    "type": "string",
                    "const": "APP_VISIT"
                },
                "$events": {
                    "type": "array",
                    "items": {
                        "anyOf": [
                            {
                                "$ref": "#/definitions/UserActivityEvent"
                            },
                            {
                                "$ref": "#/definitions/AppActivityEvent"
                            }
                        ]
                    }
                },
                "$app_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$app_id",
                "$email_hash",
                "$events",
                "$location",
                "$origin",
                "$session_status",
                "$ts",
                "$ttl",
                "$type"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
		"CTVVisitUserActivity": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$session_status": {
                    "$ref": "#/definitions/UserActivitySessionStatus"
                },
                "$ttl": {
                    "type": "number"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$email_hash": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70767-70920-1071211137-0-212510%3Cdef-interface-792792747-896-1013-792792747-0-7494%2C%22%24type%22%3E%3E"
                },
                "$user_identifiers": {
                    "$ref": "#/definitions/Nullable%3Cdef-alias-792792747-1226-1323-792792747-0-7494%5B%5D%3E"
                },
                "$origin": {
                    "$ref": "#/definitions/Nullable%3CUserActivityOrigin%3E"
                },
                "$location": {
                    "$ref": "#/definitions/Nullable%3CUserActivityLocation%3E"
                },
                "$unique_key": {
                    "$ref": "#/definitions/UUID"
                },
                "$session_duration": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$error_analyzer_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$analyzer_errors": {
                    "type": "array",
                    "items": {
                        "type": "object"
                    }
                },
                "$topics": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Cnumber%3E%3E%3E"
                },
                "$type": {
                    "type": "string",
                    "const": "CTV_VISIT"
                },
                "$events": {
                    "type": "array",
                    "items": {
                        "anyOf": [
                            {
                                "$ref": "#/definitions/UserActivityEvent"
                            },
                            {
                                "$ref": "#/definitions/AppActivityEvent"
                            }
                        ]
                    }
                },
                "$ctv_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$ctv_id",
                "$email_hash",
                "$events",
                "$location",
                "$origin",
                "$session_status",
                "$ts",
                "$ttl",
                "$type"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "AppActivityEvent": {
            "type": "object",
            "properties": {
                "$event_name": {
                    "type": "string",
                    "enum": [
                        "$app_open",
                        "$app_update",
                        "$app_install"
                    ]
                },
                "$properties": {
                    "$ref": "#/definitions/Customizable"
                }
            },
            "required": [
                "$event_name",
                "$properties"
            ],
            "additionalProperties": false
        }
    }
}

Compartments

A UserPoint could have multiple user accounts and user profiles on the same datamart. For example, having a profile on one of your sites and another profile on another site.

Compartments are a notion created to represent those different places where you have accounts and profiles. There is always one default compartment on a datamart, and you can create more of them. Compartments are associated with user account IDs to create a user identifier.

UserProfile

A UserProfile is usually imported from an existing information system, for example CRM, and login database. We usually see our customers using the profile to collect:

Contact details
User preferences
Status in a loyalty program
Subscription to a newsletter
CRM information
Scoring calculated outside the platform
Aggregated Values
other details

Each UserProfile is associated with a UserPoint by a user identifier. It can also be linked to a UserAccount.

User profile object

field

type

description

$user_account_id

String (Optional)

The associated UserAccount ID. If none, the profile remains anonymous.

$compartment_id

Integer (Optional)

When importing profiles it is recommended to complete the $user_account_id and the $compartment_id event if the values are the same than the ones used as the identifier as the values are not inherited from the identifiers info. You can find more information about the user profiles import.

Example:

# UserProfile object 
{
    "$compartment_id": 1606,
    "$user_account_id": "c9879698769OIUYOIY9879879",
    "$last_modified_ts": 5467987654613,
    "$creation_ts": 6579874654654654,
    "firstname": "David",
    "lastname": "Guetta",
    "gender": 1,
    "newsletter_options": {
        "subscribed": true,
        "preferred_periods": "MONTHLY"
    }
    
}

# Complete payload when importing a profile 
{ 
    "operation": "UPSERT",
    "compartment_id": "1600", 
    "user_account_id": "identifier_account_id",
    "force_replace": true,
    "user_profile": {
        "$compartment_id": 1606,
        "$user_account_id": "c9879698769OIUYOIY9879879",
        "$last_modified_ts": 5467987654613,
        "$creation_ts": 6579874654654654,
        "firstname": "David",
        "lastname": "Guetta",
        "gender": 1,
        "newsletter_options": {
            "subscribed": true,
            "preferred_periods": "MONTHLY"
        }
    }
}

You can have different compartment IDs and different UserAccount between the one in the profile wrapper, as the UserPoint identifier and the one into the UserProfile object.

UserSegment

Audience segments represents a group of users and are central to most marketing actions. Users can be grouped by common profile characteristics, or similar behavior in their online browsing or in their purchases. Users can be grouped either using the mediarithmics platform, or externally and then imported.

Here is a list of audience segment types that differ from each other by the method used to group users:

Audience segments calculated from a query (type USER QUERY). Several tools are provided to define this type of segment. Occasional platform users will find it easier to use the Audience Builder. More advanced users such as data admin or data analyst will find a greater wealth of expression in the Segment Builder. Finally, technical users, data engineers or integrators, can directly use a textual query language (see OTQL).
Audience segments imported from an external system (type USER LIST)
Audience segments calculated from a likeness prediction algorithm (type USER LOOKALIKE)
Audience segments associated with the events of a campaign (eg: all the people exposed to a given video campaign) (type USER ACTIVATION)
Audience segments associated with A / B tests (control group and test group)

Audience Segment & UserSegments

An audience segment represents a group of users. A UserSegment is a piece of information that is associated with a user to indicate that this user belongs to the segment.

For example, if an audience segment has 10,000 users, each user has a UserSegment to signify their membership in this segment. So there are 10,000 UserSegment, one for each user in the segment.

In the data schema this information element is materialized in the form of an object of type UserSegment (see standard datamart schema). This object contains the following information:

The segment identifier
The date the user entered the segment (creation date of the UserSegment object)
The expiration date at the end of which the user will exit the segment. This date is optional and is only entered for some types of segments.

Counting and Persistence of an audience segment of type User Query

When working with a User Query audience segment, it is important to understand the difference between the count of the segment and the persistence of this segment.

Counting consists of calculating the number of users who verify the segment's grouping rules. That is to say the users who respond positively to the conditions and to the boolean operators present in the segment query. The counting of a segment is done in real time. It usually only takes a few seconds (2-5 sec) to get a result.

However, if the count is immediate, the process of bringing all the targeted users into the segment by creating a UserSegment type record for each of them may take more time. This time depends on the size of the segment, the segment refresh policy and the calculation budget allocated to the account.

Hyper point & Quarantine

Hyper point

A hyper point is a preventive way to flag a UserPoint whenever there are too many identifiers linked to it. Concretely, a UserPoint becomes a hyper point when mediarithmics tries to merge UserPoint and especially when at least one of the following conditions is met:

the frequency of user identifiers creation in this UserPoint reaches:
- more than 10 identifiers by Registry ID in 2 days,
- more than 4 Account ID in 7 days,
- more than 4 Email hash in 7 days,
more than 8 UserPoint were merged to that UserPoint in the last 14 days,
more than 100 user identifiers are attached to this UserPoint.

This system is a preventive action of flagging a UserPoint so that the UserPoint is still actionable in mediarithimics.

Quarantine

The quarantine job is a monthly process that flags any UserPoint which has too many objects attached to it. This happens especially when at least one of the following conditions is met:

more than 10.000 activities,
more than 5.000 segments.

A UserPoint in quarantine can still be looked up in Navigator but no more additions will happen to it.A UserPoint can be freed by the quarantine job if it gets below the above-mentionned limits. This particularly happens by deleting activities (through API or when cleaning rules are applied) on a quarantined UserPoint.

User identifiers deletion

This document import allows you to mark user identifiers for deletion. Each line in the document represents a different object to remove from the platform.

This is only supported for datamarts using a UserPoint system version of v201901 or later.

It only deletes the user identifier but not the associated UserPoint.

How-to

Use the bulk import endpoints to create a document import with theUSER_IDENTIFIERS_DELETIONdocument type and APPLICATION_X_NDJSON mime type. Only ndjson data is supported for user activities.
Create an execution with your commands formatted in ndjson. Each command can either be a user account deletion, a user email deletion or a user agent deletion.

Example

# Create the document import
curl -X POST \
  https://api.mediarithmics.com/v1/datamarts/<DATAMART_ID>/document_imports \
  -H 'Authorization: <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
	"document_type": "USER_IDENTIFIERS_DELETION",
	"mime_type": "APPLICATION_X_NDJSON",
	"encoding": "utf-8",
	"name": "<YOUR_DOCUMENT_IMPORT_NAME>"
}'

# Create the execution
curl -X POST \
  https://api.mediarithmics.com/v1/datamarts/1162/document_imports/<DOCUMENT_IMPORT_ID>/executions \
  -H 'Authorization: <API_TOKEN>' \
  -H 'Content-Type: application/x-ndjson' \
  -d '
    {
      "type": "USER_ACCOUNT",
      "compartment_id": "1000",
      "user_account_id": "8541254132"
    }
    {
      "type": "USER_EMAIL",
      "hash": "982f50d88d437d13bdbd541edfv4fe5176cc8d862f8cbe7ca4f0dc8ea"
    }
    { "type": "USER_AGENT", "user_agent_id": "vec:89998434" }
  '

You can, of course, remove different identifier types at the same time. Please note that the uploaded data is in ndjson and not json. That means the different deletions are not separated by commas, but by a line separator \n

User Account deletion command

field

type

description

type

String

USER_ACCOUNT

user_account_id

String

Example:

{
  "type": "USER_ACCOUNT",
  "compartment_id": "1000",
  "user_account_id": "8541254132"
}

User Email deletion command

field

type

description

type

String

USER_EMAIL

hash

String

Example:

{
  "type": "USER_EMAIL",
  "hash": "982f50d88d437d13bdbd541edfv4fe5176cc8d862f8cbe7ca4f0dc8ea"
}

User Agent deletion command

field

type

description

type

String

USER_AGENT

user_agent_id

String

User device point ids ("udp:123456") are not supported by this document import job and will cause the job to be rejected.

Use the Device points deletionjob type if you want to delete device points along with all their associated technical ids.

Example:

{ "type": "USER_AGENT", "user_agent_id": "vec:89998434" }

Device points deletion

This document import allows you to mark device points for deletion.

Each line in the document is a user agent identifier that is linked to a device point (or is a device point id directly). For each of those identifiers, the job will find its associated device point and delete it. Note that a device point may be linked to multiple user agent identifiers, all of which will be deleted once their device point is (including user agent identifiers that may not appear in your document).

This is only supported for datamarts using a UserPoint system version of v202205 or later.

It only deletes the device point and its identifiers but not the associated UserPoint.

How-to

Use the bulk import endpoints to create a document import with the USER_DEVICE_POINTS_DELETION document type and APPLICATION_X_NDJSON mime type. Only ndjson data is supported.
Create an execution with your commands formatted in ndjson. Each line represents a user agent.

Example

Please note that the uploaded data is in ndjson and not json. That means the different deletions are not separated by commas, but by a line separator.

A list of possible user_agent_id values can be found at user_agent_id

If you want to pass device point ids directly ("udp:987654") you must do so using the USER_AGENT type.

Activities analytics

Data coming into your datamart is stored in a multi-model database, optimizing it for different usages. To display performance analytics for elements like session duration, conversions, and funnel, the platform duplicates some user activities and information and optimizes them.

For that purpose, it is important that you use predefined event names and properties when possible. Custom events won't be taken into account when calculating metrics. For example, don't create order events when tracking an e-commerce site, but the predefined $transaction_confirmed event. $transaction_confirmed events are used when calculating conversions and amounts but not order events.

Here is a sample event that can be used in analytics:

{
    "$ts": 3489009384393,
    "$event_name": "$transaction_confirmed", // Conversion detected
    "$properties": {
        "$items": [
            {
                 "$id": "product_ID", // Used to filter in funnel analytics
                 "$qty": 20, // Used for conversion amounts
                 "$price": 102.8, // Used or conversion amounts
                 "$brand": "Apple" // Used to filter in funnel analytics
                 "$category1": "Category 1", // Used to filter in funnel analytics
                 "$category2": "Category 2", // Used to filter in funnel analytics
                 "$category3": "Category 3", // Used to filter in funnel analytics
                 "$category4": "Category 4" // Used to filter in funnel analytics
             },
             {
                 "$id": "product_ID2",
                 "$qty": 12,
                 "$price": 3.4,
                 "$brand": "Microsoft"
             }
        ],
        "$currency": "EUR"
    }
}

The list of predefined events that are used in analytics are as follows.

Event name

Usage

Important properties

$transaction_confirmed

Home dashboards (E-Commerce Engagement)

Segment dashboards (E-Commerce Engagement)

Funnel Analytics

$items : list of products in the transaction

$items.$qty : for the conversion amounts

$items.$price: for the conversion amounts

$items.$id : for the product IDs in funnel analytics

$items.$brand: for the brand filter in funnel analytics

$item_view

Funnel Analytics

Activities analytics data retention

Activities analytics data is kept 4 month in order to optimize performances.

Transforming important events into your custom events

While it is better to use predefined events when possible, it isn't always the best solution for you. To keep having analytics correctly stored, you can transform your custom events to predefined ones.

Only events coming into the datamart after an event transformation has been defined will be transformed.

Those transformations don't transform user activities and events anywhere else. You should use activity analyzers to transform them everywhere.

Event transformations

An event transformation is linked to a datamart. Here is a sample transformation:

{
    "id": 15, // Read only
    "datamart_id": "3333", // Read only
    "created_ts": <>, // Read only
    "created_by": <>, // Read only
    "last_modified_by": <>, // Read only
    "last_modified_ts": <>, // Read only

    "channel_id": "8888",
    "source_event_name": "order",
    "target_event_name": "$transaction_confirmed",
    "mapping_id": 15
}

Property

Type

Description

datamart_id

Integer

The ID of the datamart where the transformation is applied

channel_id

Integer

Property mappings

Event transformations use property mappings to choose which property in your custom event becomes which property in the predefined event.

Here is a sample property mapping to start with for $transaction_confirmed events.

// Comments are here to help you understand, 
// remove them before uploading mappings as they are not accepted in JSON
{
  "id": 17, // Read only
  "created_by": <>, // Read only
  "created_ts": <>, // Read only
  "mapping": {
    "values": [
      {
          // Maps $properties.order.order_products[] to $items[]
           "target_attribute_name": "$items",
           "source_attribute_path": {
               "attribute_name": "$properties",
               "sub_path": {
                   "attribute_name": "order",
                   "sub_path": {
                        "attribute_name": "order_products"
                   }
               }
           },
           // Alternative : mapping directly $properties if there are no multiple
           // elements in the event. It will be treated as an array of only one item
           "target_attribute_name": "$items",
           "source_attribute_path": {
                "attribute_name": "$properties"
           },
           
           // Maps $properties.order.order_products.xxx to $items.xxx
           // You can't use other target attributes than the ones 
           // in this example.
           // But they are not all mandatory : a non used target 
           // attribute will use the default value
           "children": [
               // $properties.order.order_products.product.id
               // becomes $items.$id
               // to be used by analytics database
               {
                   "target_attribute_name": "$id",
                   "source_attribute_path": {
                     "attribute_name": "product",
                     "sub_path": {
                        "attribute_name": "id"
                     }
                   }
               },
               // $properties.order.order_products.qty
               // becomes $items.$qty
               // to be used by analytics database
               {
                   "target_attribute_name": "$qty",
                   "source_attribute_path": {
                     "attribute_name": "qty"
                   }
               },
               {
                   "target_attribute_name": "$price",
                   "source_attribute_path": {
                     "attribute_name": "price"
                   }
               },
               {
                   "target_attribute_name": "$ean",
                   "source_attribute_path": {
                     "attribute_name": "ean",
                   }
               },
               {
                   "target_attribute_name": "$brand",
                   "source_attribute_path": {
                     "attribute_name": "brand",
                   }
               },
               {
                   "target_attribute_name": "$category1",
                   "source_attribute_path": {
                     "attribute_name": "cat1"
                   }
               },
               {
                   // In this example $category2 will be 
                   // event.$event_name instead of 
                   // $properties.order.order_products[].$event_name
                   // thanks to absolute_path
                   "target_attribute_name": "$category2",
                   "source_attribute_path": {
                     "absolute_path": true,
                     "attribute_name": "$event_name",
                   }
               },
               {
                   "target_attribute_name": "$category3",
                   "source_attribute_path": {
                     "attribute_name": "cat3"
                   }
               },
                {
                   "target_attribute_name": "$category4",
                   "source_attribute_path": {
                     "attribute_name": "cat4"
                   }
               }
           ]
       }
    ]
  }
}

Map events JSON as it is stored in the database and visible in user's timelines (post activity analyzers).

Get existing transformations

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_event_transformation

Path Parameters

Name

Type

Description

datamartId

integer

The datamart ID

{
    "status": "ok",
    "data": [
        {
          "datamart_id": ":datamartId",
          "channel_id": "8888",
          "source_event_name": "order",
          "target_event_name": "$transaction_confirmed",
          "mapping_id": xxx
        },
        {
            ...
        }
    ]
}

Create an event transformation

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_event_transformation

Path Parameters

Name

Type

Description

datamartId

integer

The datamart ID

Request Body

Name

Type

Description

Body

string

The event transformation object

Update an event transformation

PUT https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_event_transformation/:transformationId

Path Parameters

Name

Type

Description

transformationId

integer

The transformation ID

datamartId

integer

The datamart ID

Request Body

Name

Type

Description

Body

string

The event transformation object

Remove an event transformation

DELETE https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_event_transformation/:transformationId

Path Parameters

Name

Type

Description

transformationId

integer

The transformation ID

datamartId

integer

The datamart ID

Get property mappings

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_mapping

Path Parameters

Name

Type

Description

datamartId

integer

The datamart ID

Create property mappings

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_mapping

Path Parameters

Name

Type

Description

datamartId

integer

The datamart ID

Request Body

Name

Type

Description

Body

object

The property mapping object

{
  "status": "ok",
  "data": {
      id: 17,
      created_by: <>
      ...
  }
}

Delete property mappings

DELETE https://api.mediarithmics.com/v1/datamarts/:datamartId/analytics_mapping/:mappingId

Path Parameters

Name

Type

Description

mappingId

integer

The mapping ID

datamartId

integer

The datamart ID

{
    "status": "ok"
}

{
    "status": "error",
    "error": "Deleting a property mapping used in a transformation is forbidden",
    "error_code": "BAD_REQUEST_DATA",
    "error_id": "9460be23-0f80-4acb-9a33-dd8a1c5d08a9"
}

UserActivity API

The user activities endpoint gives you the ability to retrieve & delete any activities (and attached events) on a given UserPoint.

Retrieve activities & events from a UserPoint

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/user_timelines/:userpointId/user_activities?filters=:filters

Path Parameters

Name

Type

Description

datamartId*

String

The ID of the datamart want to retrieve activities for

userpointId*

String

The ID of the UserPoint you want to retrieve activities for

Query Parameters

Name

Type

Description

filters

String

Filter(s) to select appropriat user activities

{
    // Response
}

Delete activities & events from a UserPoint

DELETE https://api.mediarithmics.com/v1/datamarts/:datamartId/user_timelines/:userpointId/user_activities?filters=:filters

Path Parameters

Name

Type

Description

datamartId*

String

The ID of the datamart want to retrieve activities for

userpointId*

String

The ID of the UserPoint you want to retrieve activities for

Query Parameters

Name

Type

Description

filters

String

Filter(s) to select appropriat user activities

Filters

As mentionned above, filters are optional and give you the ability to narrow your query. You can apply filters on any custom fields you have in your activity object as well as the following proprietary fields:

$unique_key
$type
$channel_id
$ts (through start_ts & end_ts keywords)

To apply any filter, mention the field on which you want your filter to be applied, followed by double equal (==), then by value(s) for the field to be matched against.

Note that:

You can provide in your query multiple filters by seperating filters with a comma (,). In that case, it will be considered as an "AND" between those filters
A filter can take multiple values by separating values with a pipe (|). In that case, it will be considered as an "OR" between those values

Query examples

Advanced usages

Audience features

Audience features you create are available in the navigator, in Audience > Builders > Standard.

Let's take the following query as an example:

SELECT @count{} FROM UserPoint WHERE
events { 
    nature = "$transaction_confirmed" and 
    date >= $date 
    and products {brand in $brand and name in $name}
    }

It is technically an OTQL query based on your schema in which you registered parameters. In this case, it represents a business feature that may be used regularly by your users: selecting UserPoint that perform a transaction in a particular date range and for specific products.

Users will see this selector in the builder instead of an OTQL query.

This audience feature will automatically be combined with other audience features, which the user can select to create segments.

The process

Users will have access to the standard segment builder if at least one audience feature is set up. But you need multiple ones to create value for users.

Good knowledge of the schema and the queries that are usually created in your datamart is important for the success of this feature.

Here is a sample process to follow to enable audience features and create value for your users:

Know your schema. What is it optimized for? Which queries are regularly created? What are your actual segments and what are their queries? You should be able to create a list of useful audience features with these pieces of information.
Set up audience features, in the UI and/or by script.
Monitor usage and update audience features regularly!

Folders

You can store audience features in folders. Any audience feature without a folder will be assigned to the root folder. Here are some examples.

List folders

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders

Path Parameters

Name

Type

Description

datamart_id

integer

The ID of the datamart

{
  "first_result": 0,
  "count": 0,
  "max_results": 0,
  "status": "ok",
  "data": [
    {
      "id": "string",
      "children_ids": [
        "string"
      ],
      "audience_features_ids": [
        "string"
      ],
      "parent_id": "string",
      "datamart_id": "string",
      "name": "string"
    }
  ],
  "total": 0
}

List one folder

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders/{audience_feature_folders_id}

Path Parameters

Name

Type

Description

audience_feature_folders_id

integer

The ID of the folder

datamart_id

integer

The ID of the datamart

{
  "status": "ok",
  "data": {
    "id": "string",
    "children_ids": [
      "string"
    ],
    "audience_features_ids": [
      "string"
    ],
    "parent_id": "string",
    "datamart_id": "string",
    "name": "string"
  }
}

Create a folder

POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders

Path Parameters

Name

Type

Description

datamart_id*

integer

The ID of the datamart

Request Body

Name

Type

Description

children_ids

array

IDs of folder's children

audience_features_ids

array

IDs of audience features attached to the folder

// Create a folder payload
{
  "children_ids": [
    "string"
  ],
  "audience_features_ids": [
    "string"
  ],
  "parent_id": "string",
  "datamart_id": "string",
  "name": "string"
}

Edit a folder

PUT https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders/{audience_feature_folders}

Path Parameters

Name

Type

Description

datamart_id*

integer

The ID of the datamart

audience_feature_folders_id*

integer

The ID of the audience feature folder

Request Body

Name

Type

Description

children_ids

array

IDs of folders's children

audience_features_ids

array

IDs of audience features attached to the folder

{
  "status": "ok",
  "data": {
    "id": "string",
    "children_ids": [
      "string"
    ],
    "audience_features_ids": [
      "string"
    ],
    "parent_id": "string",
    "datamart_id": "string",
    "name": "string"
  }
}

// Editing a folder payload
{
  "children_ids": [
    "string"
  ],
  "audience_features_ids": [
    "string"
  ],
  "parent_id": "string",
  "datamart_id": "string",
  "name": "string"
}

Audience features

List audience features

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features

Path Parameters

Name

Type

Description

datamart_id

integer

The ID of the datamart

{
  "first_result": 0,
  "total": 0,
  "count": 0,
  "data": [
    {
      "object_tree_expression": "string",
      "description": "string",
      "id": "string",
      "variables": [
        {
          "field_name": "string",
          "data_type": "string",
          "reference_model_type": "string",
          "type": "string",
          "parameter_name": "string",
          "path": [
            "string"
          ],
          "reference_type": "string",
          "directive": "string",
          "container_type": "string"
        }
      ],
      "token": "string",
      "datamart_id": "string",
      "addressable_object": "string",
      "name": "string",
      "folder_id": "string",
      "creation_date": 0
    }
  ],
  "max_results": 0,
  "status": "ok"
}

Get an audience feature

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features/{audience_feature_id}

Path Parameters

Name

Type

Description

audience_feature_id

integer

The ID of the audience feature

datamart_id

integer

The ID of the datamart

{
  "status": "ok",
  "data": {
    "object_tree_expression": "string",
    "description": "string",
    "id": "string",
    "variables": [
      {
        "field_name": "string",
        "data_type": "string",
        "reference_model_type": "string",
        "type": "string",
        "parameter_name": "string",
        "path": [
          "string"
        ],
        "reference_type": "string",
        "directive": "string",
        "container_type": "string"
      }
    ],
    "token": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string",
    "creation_date": 0
  }
}

Create an audience feature

POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features

Path Parameters

Name

Type

Description

datamart_id

integer

The ID of the datamart

Request Body

Name

Type

Description

object_tree_expression

string

The WHERE statement of the query associated to the audience feature

description

string

The description of your audience feature

{
  "status": "ok",
  "data": {
    "object_tree_expression": "string",
    "description": "string",
    "id": "string",
    "variables": [
      {
        "field_name": "string",
        "data_type": "string",
        "reference_model_type": "string",
        "type": "string",
        "parameter_name": "string",
        "path": [
          "string"
        ],
        "reference_type": "string",
        "directive": "string",
        "container_type": "string"
      }
    ],
    "token": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string",
    "creation_date": 0
  }
}

// Creating an audience feature payload
{
    "object_tree_expression": "string",
    "description": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string"
}

Edit an audience feature

PUT https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features/{audience_feature_id}

Path Parameters

Name

Type

Description

audience_feature_id

integer

The ID of the audience feature to edit

datamart_id

integer

The ID of the datamart

Request Body

Name

Type

Description

object_tree_expression

string

The WHERE statement of the query associated to the audience feature

description

string

The description of your audience feature

{
  "status": "ok",
  "data": {
    "object_tree_expression": "string",
    "description": "string",
    "id": "string",
    "variables": [
      {
        "field_name": "string",
        "data_type": "string",
        "reference_model_type": "string",
        "type": "string",
        "parameter_name": "string",
        "path": [
          "string"
        ],
        "reference_type": "string",
        "directive": "string",
        "container_type": "string"
      }
    ],
    "token": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string",
    "creation_date": 0
  }
}

// Editing an audience feature payload
{
    "object_tree_expression": "string",
    "description": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string"
}

OTQL query rules

Parameters

Create query parameters using the $parameter_namesyntax. Example:

// The gender will be selectable by the user
SELECT @count{} FROM UserPoint 
where  profiles {gender in $gender}

// The date will be selectable by the user,
// but the nature will always be $transaction_confirmed
SELECT @count{} FROM UserPoint 
where events { nature = "$transaction_confirmed" and date >= $date }

The field in the audience feature will have the name you enter after the $ . Spaces in field name are not authorized. The type of selector in the audience feature is automatically chosen based on the field type

If you want to be able to select several values in a field, use keyword in instead of the classic ==.

// User will only be able to select one gender
SELECT @count{} FROM UserPoint 
where  profiles {gender == $gender}

// User will be able to select multiple gender values
SELECT @count{} FROM UserPoint 
where  profiles {gender in $gender}

You can create parameters for frequency requests with the @ScoreSum directive:

// User will be able to select the minimum number of transactions
SELECT @count{} FROM UserPoint 
WHERE events@ScoreSum(min: $frequency) { 
    purchase in $user_purchase 
}

UserActivity & UserEvent

User activity management is at the core of audience management services.

You send UserEvent to mediarithmics, that are aggregated and encapsulated into UserActivity. Some UserActivity only have one UserEvent, but some can have multiple UserEvent.

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

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.

A few things to keep in mind :

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.

CTV visits user activities

Their type is Ct_VISIT. They have those additional base properties :

field

type

description

$ctv_id

String

The CTV ID (channel)

$session_duration

Integer (Optional)

The session duration in seconds.

Channels

If you have multiple sites/apps (Mobile or CTV) 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

User Email

field

type

description

$type

Constant String

USER_EMAIL

$hash

String

User Agent

field

type

description

$type

Constant String

USER_AGENT

$user_agent_id

String

User Agent info

Property

Type

Description

$initial_ts

Timestamp

Timestamp at which device has been seen

$form_factor

Enum

Indicates the format of the device. Possible values: PERSONAL_COMPUTER, SMART_TV, GAME_CONSOLE, SMARTPHONE, TABLET, WEARABLE_COMPUTER, OTHER.

Activity Location

field

type

description

$source

String (Optional)

The location source (IP, GPS, OTHER)

$country

String (Optional)

Activity Origin

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, ...

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

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:

xtor=A-B-C-D-E-F-G-H

The xtor parameter is automatically analyzed to fill the following origin fields:

origin field

xtor field

example / description

$source

EPR when xtor=EPR-14234

$campaign_name

Marketing Channel inference

source

channel

EPR

$email

EREC

$email

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=crm_database

$campaign_name

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.

{
    "$ts": 3489009384393,
    "$event_name": "$transaction_confirmed", // Conversion detected
    "$properties": {
        "$items": [
            {
                 "$id": "product_ID", // Used to filter in funnel analytics
                 "$qty": 20, // Used for conversion amounts
                 "$price": 102.8, // Used or conversion amounts
                 "$brand": "Apple" // Used to filter in funnel analytics
                 "$category1": "Category 1", // Used to filter in funnel analytics
                 "$category2": "Category 2", // Used to filter in funnel analytics
                 "$category3": "Category 3", // Used to filter in funnel analytics
                 "$category4": "Category 4" // Used to filter in funnel analytics
             },
             {
                 "$id": "product_ID2",
                 "$qty": 12,
                 "$price": 3.4,
                 "$brand": "Microsoft"
             }
        ],
        "$currency": "EUR"
    }
}

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

$home_view

The user has viewed the home page

$item_view

The user has viewed an item

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 . Example value : [{"$id":"ProductID1"},{"$id":"ProductID2"}]

Each item has the $id, $ean, $qty , $price, $brand, $name, $category1,

$campaign_technical_name

Technical name of a campaign associated to the event when .

$sub_campaign_technical_name

Technical name of a sub campaign associated to the event when .

User Activity JSON schema and TypeScript interfaces

Below is the JSON schema for a single activity, according to the rules enacted in this documentation.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$ref": "#/definitions/UserActivity",
    "definitions": {
        "UserActivity": {
            "oneOf": [
                {
                    "$ref": "#/definitions/GenericUserActivity"
                },
                {
                    "$ref": "#/definitions/SiteVisitUserActivity"
                },
                {
                    "$ref": "#/definitions/AppVisitUserActivity"
                },
                {
                    "$ref": "#/definitions/CTVVisitUserActivity"
                }
            ]
        },
        "GenericUserActivity": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$session_status": {
                    "$ref": "#/definitions/UserActivitySessionStatus"
                },
                "$ttl": {
                    "type": "number"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$email_hash": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70767-70920-1071211137-0-212510%3Cdef-interface-792792747-896-1013-792792747-0-7494%2C%22%24type%22%3E%3E"
                },
                "$user_identifiers": {
                    "$ref": "#/definitions/Nullable%3Cdef-alias-792792747-1226-1323-792792747-0-7494%5B%5D%3E"
                },
                "$origin": {
                    "$ref": "#/definitions/Nullable%3CUserActivityOrigin%3E"
                },
                "$location": {
                    "$ref": "#/definitions/Nullable%3CUserActivityLocation%3E"
                },
                "$unique_key": {
                    "$ref": "#/definitions/UUID"
                },
                "$type": {
                    "type": "string",
                    "enum": [
                        "DISPLAY_AD",
                        "EMAIL",
                        "TOUCH",
                        "USER_SCENARIO_START",
                        "USER_SCENARIO_STOP",
                        "USER_SCENARIO_NODE_ENTER",
                        "USER_SCENARIO_NODE_EXIT"
                    ]
                },
                "$events": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/UserActivityEvent"
                    }
                }
            },
            "required": [
                "$email_hash",
                "$events",
                "$location",
                "$origin",
                "$session_status",
                "$ts",
                "$ttl",
                "$type"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "Timestamp": {
            "type": "number"
        },
        "UserActivitySessionStatus": {
            "type": "string",
            "enum": [
                "NO_SESSION",
                "IN_SESSION",
                "CLOSED_SESSION"
            ]
        },
        "Nullable<ID>": {
            "anyOf": [
                {
                    "$ref": "#/definitions/ID"
                },
                {
                    "type": "null"
                }
            ]
        },
        "ID": {
            "type": "string"
        },
        "Nullable<alias-1071211137-70767-70920-1071211137-0-212510<def-interface-792792747-896-1013-792792747-0-7494,\"$type\">>": {
            "anyOf": [
                {
                    "type": "object",
                    "properties": {
                        "$hash": {
                            "type": "string"
                        },
                        "$email": {
                            "$ref": "#/definitions/Nullable%3Cstring%3E"
                        }
                    },
                    "required": [
                        "$hash"
                    ],
                    "additionalProperties": false
                },
                {
                    "type": "null"
                }
            ]
        },
        "Nullable<string>": {
            "type": [
                "string",
                "null"
            ]
        },
        "Nullable<def-alias-792792747-1226-1323-792792747-0-7494[]>": {
            "anyOf": [
                {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/UserIdentifier"
                    }
                },
                {
                    "type": "null"
                }
            ]
        },
        "UserIdentifier": {
            "anyOf": [
                {
                    "$ref": "#/definitions/UserEmailIdentifier"
                },
                {
                    "$ref": "#/definitions/UserAccountIdentifier"
                },
                {
                    "$ref": "#/definitions/UserAgentIdentifier"
                }
            ]
        },
        "UserEmailIdentifier": {
            "type": "object",
            "properties": {
                "$type": {
                    "type": "string",
                    "const": "USER_EMAIL"
                },
                "$hash": {
                    "type": "string"
                },
                "$email": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                }
            },
            "required": [
                "$type",
                "$hash"
            ],
            "additionalProperties": false
        },
        "UserAccountIdentifier": {
            "type": "object",
            "properties": {
                "$type": {
                    "type": "string",
                    "const": "USER_ACCOUNT"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/ID"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$type",
                "$user_account_id",
                "$compartment_id"
            ],
            "additionalProperties": false
        },
        "UserAgentIdentifier": {
            "type": "object",
            "properties": {
                "$type": {
                    "type": "string",
                    "const": "USER_AGENT"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$type",
                "$user_agent_id"
            ],
            "additionalProperties": false
        },
        "Nullable<UserActivityOrigin>": {
            "anyOf": [
                {
                    "$ref": "#/definitions/UserActivityOrigin"
                },
                {
                    "type": "null"
                }
            ]
        },
        "UserActivityOrigin": {
            "type": "object",
            "properties": {
                "$campaign_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$campaign_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$channel": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$creative_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$creative_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$engagement_content_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$gclid": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$keywords": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$log_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$message_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$message_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$referral_path": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$social_network": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$source": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$sub_campaign_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$sub_campaign_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$ts": {
                    "type": "number"
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "Nullable<number>": {
            "type": [
                "number",
                "null"
            ]
        },
        "JsonType": {
            "anyOf": [
                {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                {
                    "type": "boolean"
                },
                {
                    "type": "object"
                },
                {
                    "type": "array",
                    "items": {}
                },
                {
                    "not": {}
                }
            ]
        },
        "Nullable<UserActivityLocation>": {
            "anyOf": [
                {
                    "$ref": "#/definitions/UserActivityLocation"
                },
                {
                    "type": "null"
                }
            ]
        },
        "UserActivityLocation": {
            "type": "object",
            "properties": {
                "$source": {
                    "$ref": "#/definitions/LocationSource"
                },
                "$country": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$region": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$iso_region": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$city": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$iso_city": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$zip_code": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$latlon": {
                    "$ref": "#/definitions/Nullable%3Cnumber%5B%5D%3E"
                }
            },
            "required": [
                "$latlon"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "LocationSource": {
            "type": "string",
            "enum": [
                "GPS",
                "IP",
                "OTHER"
            ]
        },
        "Nullable<number[]>": {
            "anyOf": [
                {
                    "type": "array",
                    "items": {
                        "type": "number"
                    }
                },
                {
                    "type": "null"
                }
            ]
        },
        "UUID": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{8}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{4}\\b-[0-9a-fA-F]{12}$"
        },
        "UserActivityEvent": {
            "anyOf": [
                {
                    "$ref": "#/definitions/GenericUserActivityEvent"
                },
                {
                    "$ref": "#/definitions/AdTrackingEvent"
                },
                {
                    "$ref": "#/definitions/SetUserChoiceEvent"
                },
                {
                    "$ref": "#/definitions/SetUserProfilePropertiesEvent"
                },
                {
                    "$ref": "#/definitions/RetailEvent"
                },
                {
                    "$ref": "#/definitions/ConversionEvent"
                }
            ]
        },
        "GenericUserActivityEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "anyOf": [
                        {
                            "$ref": "#/definitions/EventName"
                        },
                        {
                            "type": "string"
                        }
                    ]
                },
                "$properties": {
                    "$ref": "#/definitions/Customizable"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "Nullable<Timestamp>": {
            "anyOf": [
                {
                    "$ref": "#/definitions/Timestamp"
                },
                {
                    "type": "null"
                }
            ]
        },
        "EventName": {
            "anyOf": [
                {
                    "$ref": "#/definitions/DefaultEventName"
                },
                {
                    "type": "string"
                }
            ]
        },
        "DefaultEventName": {
            "type": "string",
            "enum": [
                "$page_view",
                "$home_view",
                "$category_view",
                "$email_view",
                "$email_click",
                "$email_sent",
                "$email_delivered",
                "$email_soft_bounce",
                "$email_hard_bounce",
                "$email_unsubscribe",
                "$email_complaint",
                "$content_corrections"
            ]
        },
        "Customizable": {
            "type": "object",
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "AdTrackingEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "type": "string",
                    "enum": [
                        "$ad_view",
                        "$ad_click"
                    ]
                },
                "$properties": {
                    "$ref": "#/definitions/AdTrackingEventProperties"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "AdTrackingEventProperties": {
            "type": "object",
            "properties": {
                "$url": {
                    "type": "string"
                },
                "$referrer": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$campaign_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$sub_campaign_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$creative_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$message_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$campaign_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$sub_campaign_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$message_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$creative_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            },
            "required": [
                "$url"
            ]
        },
        "SetUserChoiceEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "type": "string",
                    "const": "$set_user_choice"
                },
                "$properties": {
                    "$ref": "#/definitions/SetUserChoiceEventProperties"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "SetUserChoiceEventProperties": {
            "type": "object",
            "properties": {
                "$url": {
                    "type": "string"
                },
                "$referrer": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$processing_token": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$processing_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$choice_acceptance_value": {
                    "type": "boolean"
                },
                "$choice_source_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                }
            },
            "required": [
                "$choice_acceptance_value",
                "$url"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "SetUserProfilePropertiesEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "type": "string",
                    "const": "$set_user_profile_properties"
                },
                "$properties": {
                    "$ref": "#/definitions/Customizable"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "RetailEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "$ref": "#/definitions/RetailEventName"
                },
                "$properties": {
                    "$ref": "#/definitions/RetailEventProperties"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "RetailEventName": {
            "type": "string",
            "enum": [
                "$item_view",
                "$item_list_view",
                "$product_view",
                "$product_list_view",
                "$basket_view",
                "$transaction_confirmed"
            ]
        },
        "RetailEventProperties": {
            "type": "object",
            "properties": {
                "$url": {
                    "type": "string"
                },
                "$referrer": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$items": {
                    "$ref": "#/definitions/Nullable%3Cdef-interface-792792747-3521-3897-792792747-0-7494%5B%5D%3E"
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            },
            "required": [
                "$url"
            ]
        },
        "Nullable<def-interface-792792747-3521-3897-792792747-0-7494[]>": {
            "anyOf": [
                {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/RetailEventPropertiesItem"
                    }
                },
                {
                    "type": "null"
                }
            ]
        },
        "RetailEventPropertiesItem": {
            "type": "object",
            "properties": {
                "$id": {
                    "type": "string"
                },
                "$ean": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$qty": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$price": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$brand": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$category1": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$category2": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$category3": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$category4": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                }
            },
            "required": [
                "$id"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "ConversionEvent": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$expiration_ts": {
                    "$ref": "#/definitions/Nullable%3CTimestamp%3E"
                },
                "$event_name": {
                    "type": "string",
                    "const": "$conversion"
                },
                "$properties": {
                    "$ref": "#/definitions/ConversionEventProperties"
                }
            },
            "required": [
                "$event_name",
                "$properties",
                "$ts"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "ConversionEventProperties": {
            "type": "object",
            "properties": {
                "$conversion_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$goal_id": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$conversion_technical_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$goal_technical_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$conversion_value": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$log_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$conversion_external_id": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                },
                "$goal_technical_name": {
                    "$ref": "#/definitions/Nullable%3Cstring%3E"
                }
            },
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "SiteVisitUserActivity": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$session_status": {
                    "$ref": "#/definitions/UserActivitySessionStatus"
                },
                "$ttl": {
                    "type": "number"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$email_hash": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70767-70920-1071211137-0-212510%3Cdef-interface-792792747-896-1013-792792747-0-7494%2C%22%24type%22%3E%3E"
                },
                "$user_identifiers": {
                    "$ref": "#/definitions/Nullable%3Cdef-alias-792792747-1226-1323-792792747-0-7494%5B%5D%3E"
                },
                "$origin": {
                    "$ref": "#/definitions/Nullable%3CUserActivityOrigin%3E"
                },
                "$location": {
                    "$ref": "#/definitions/Nullable%3CUserActivityLocation%3E"
                },
                "$unique_key": {
                    "$ref": "#/definitions/UUID"
                },
                "$session_duration": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$error_analyzer_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$analyzer_errors": {
                    "type": "array",
                    "items": {
                        "type": "object"
                    }
                },
                "$topics": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Cnumber%3E%3E%3E"
                },
                "$type": {
                    "type": "string",
                    "const": "SITE_VISIT"
                },
                "$events": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/UserActivityEvent"
                    }
                },
                "$site_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$email_hash",
                "$events",
                "$location",
                "$origin",
                "$session_status",
                "$site_id",
                "$ts",
                "$ttl",
                "$type"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "Nullable<alias-1071211137-70404-70537-1071211137-0-212510<string,alias-1071211137-70404-70537-1071211137-0-212510<string,number>>>": {
            "anyOf": [
                {
                    "type": "object",
                    "additionalProperties": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "number"
                        }
                    }
                },
                {
                    "type": "null"
                }
            ]
        },
        "AppVisitUserActivity": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$session_status": {
                    "$ref": "#/definitions/UserActivitySessionStatus"
                },
                "$ttl": {
                    "type": "number"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$email_hash": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70767-70920-1071211137-0-212510%3Cdef-interface-792792747-896-1013-792792747-0-7494%2C%22%24type%22%3E%3E"
                },
                "$user_identifiers": {
                    "$ref": "#/definitions/Nullable%3Cdef-alias-792792747-1226-1323-792792747-0-7494%5B%5D%3E"
                },
                "$origin": {
                    "$ref": "#/definitions/Nullable%3CUserActivityOrigin%3E"
                },
                "$location": {
                    "$ref": "#/definitions/Nullable%3CUserActivityLocation%3E"
                },
                "$unique_key": {
                    "$ref": "#/definitions/UUID"
                },
                "$session_duration": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$error_analyzer_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$analyzer_errors": {
                    "type": "array",
                    "items": {
                        "type": "object"
                    }
                },
                "$topics": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Cnumber%3E%3E%3E"
                },
                "$type": {
                    "type": "string",
                    "const": "APP_VISIT"
                },
                "$events": {
                    "type": "array",
                    "items": {
                        "anyOf": [
                            {
                                "$ref": "#/definitions/UserActivityEvent"
                            },
                            {
                                "$ref": "#/definitions/AppActivityEvent"
                            }
                        ]
                    }
                },
                "$app_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$app_id",
                "$email_hash",
                "$events",
                "$location",
                "$origin",
                "$session_status",
                "$ts",
                "$ttl",
                "$type"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
		"CTVVisitUserActivity": {
            "type": "object",
            "properties": {
                "$ts": {
                    "$ref": "#/definitions/Timestamp"
                },
                "$session_status": {
                    "$ref": "#/definitions/UserActivitySessionStatus"
                },
                "$ttl": {
                    "type": "number"
                },
                "$user_agent_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$user_account_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$compartment_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$email_hash": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70767-70920-1071211137-0-212510%3Cdef-interface-792792747-896-1013-792792747-0-7494%2C%22%24type%22%3E%3E"
                },
                "$user_identifiers": {
                    "$ref": "#/definitions/Nullable%3Cdef-alias-792792747-1226-1323-792792747-0-7494%5B%5D%3E"
                },
                "$origin": {
                    "$ref": "#/definitions/Nullable%3CUserActivityOrigin%3E"
                },
                "$location": {
                    "$ref": "#/definitions/Nullable%3CUserActivityLocation%3E"
                },
                "$unique_key": {
                    "$ref": "#/definitions/UUID"
                },
                "$session_duration": {
                    "$ref": "#/definitions/Nullable%3Cnumber%3E"
                },
                "$error_analyzer_id": {
                    "$ref": "#/definitions/Nullable%3CID%3E"
                },
                "$analyzer_errors": {
                    "type": "array",
                    "items": {
                        "type": "object"
                    }
                },
                "$topics": {
                    "$ref": "#/definitions/Nullable%3Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Calias-1071211137-70404-70537-1071211137-0-212510%3Cstring%2Cnumber%3E%3E%3E"
                },
                "$type": {
                    "type": "string",
                    "const": "CTV_VISIT"
                },
                "$events": {
                    "type": "array",
                    "items": {
                        "anyOf": [
                            {
                                "$ref": "#/definitions/UserActivityEvent"
                            },
                            {
                                "$ref": "#/definitions/AppActivityEvent"
                            }
                        ]
                    }
                },
                "$ctv_id": {
                    "$ref": "#/definitions/ID"
                }
            },
            "required": [
                "$ctv_id",
                "$email_hash",
                "$events",
                "$location",
                "$origin",
                "$session_status",
                "$ts",
                "$ttl",
                "$type"
            ],
            "additionalProperties": {
                "$ref": "#/definitions/JsonType"
            }
        },
        "AppActivityEvent": {
            "type": "object",
            "properties": {
                "$event_name": {
                    "type": "string",
                    "enum": [
                        "$app_open",
                        "$app_update",
                        "$app_install"
                    ]
                },
                "$properties": {
                    "$ref": "#/definitions/Customizable"
                }
            },
            "required": [
                "$event_name",
                "$properties"
            ],
            "additionalProperties": false
        }
    }
}

OTQL queries

This page provides a formal description of OTQL capabilities.

Introduction

The Object Tree Query Language (OTQL) has been designed to help to search and calculate aggregates on a large collection of object trees. The object tree is defined in the schema using the @TreeIndexRoot and the @TreeIndex directives.

OTQL queries help you :

Build segments
Explore data
Monitor data integration

An OTQL query looks like an SQL query.

It is composed of three parts:

A SELECT Operation: It gives indications on what needs to be done: extracting field values or calculating aggregates
A FROM starting Object Type: It defines the starting object type in the evaluation process

There are two kinds of operations:

Selection Operations are similar to a GraphQL operation and return a list of objects containing the required fields.
Aggregation Operations return aggregated values (count, stats, histograms, ...) calculated on the selected objects.

The fields in the queries are completely related to .

Here are some examples of requests you can do with OTQL :

FROM - Starting object type

Imagining the following Object Tree:

You could build queries starting from all UserPoint, all UserActivity, UserEvent, UserEmail or UserAccount

You target object types with the FROM. In the example, the link field is activities, but we don't do SELECT (...) FROM activities.

WHERE - Object tree expressions

The expression contained in the WHERE clause is composed of a list of predicates, separated by logical operators AND, OR, and NOT . Parenthesis can be used to group together two predicates with a logical operator.

Examples :

Logical operators

Each predicate doesn't return directly a boolean but a score, 1 if the condition is respected else 0. At the end the score is compared to 0 and return true if it's higher than 0 else return false. These operator keep the same priority as boolean ones. The logical operators work as below :

Tree exploration

As we are querying an Object Tree, and as predicates are only possible on a leaf (e.g. fields that only contain a scalar value), it is natural to have a way of going from the root to each of the leaves by traversing the tree.

Braces symbols {} are used to traverse the tree through link fields. The sub-query written in the braces will be evaluated on each item in the linked list.

Let's see it in action.

Let's say we built a schema corresponding to the following Object Tree.

The following query will return all the UserPoint that have at least one UserEvent whose name is $transaction_confirmed .

As the root of the Object Tree is the UserPoint in this example, we'll need to start from there. And then follow the activities link to the associated UserActivity and then the events link to the associated UserEvent.

Scoring operator

The latest query returns items with at least one of the events have a $transaction_confirmed name. We return every user that did at least one purchase and at least one visit.

If we instead want the users that bought things through at least 3 different visits (frequent buyers), we will use a scoring operator.

Each time there is a pair of braces { } and a sub-query written in the braces, there is implicitly a score calculated for the sub-query. By default, the score will be the number of items matching the sub-query.

Only returns score if the nested sub-query has a score superior or equal to min.

Calculate the average from the sub-query matching scores and returns true if it's superior or equal to min.

Changing the way scores are calculated

As said above, by default, score values are equal to the number of items matching a sub-query when following a link.

However, your Object Tree leaves have some number typed fields (Int or Float). It is possible to use those values as the score of a sub-query.

Select a specific field in which the numeric value used as the score is stored.

The information of which field is selected bubble up still it didn't catch by a @ScoreSum, @ScoreAvg

Using this calculated score

With the possibility to use score in a field, you may want to return the calculated score of a @ScoreSum and not only it a sub-query validate the condition or not. This is why we add a new parameters to @ScoreSum :result.

Only returns score if the nested sub-query has a score superior or equal to min.

Go forward

It is possible to use these two ways at the same time but be careful, it is currently not possible to grow up a @ScoreField after a @ScoreSum(result: "boolean_score").

Example of possible use case :

However the following use case can't be written :

Using conditional and scoring ways in the same query is useful for many use case whose won't be detailed here. A specific page has been created for regroup examples of them if you want to .

Date operators

The following operators are available to work with dates :

>= Greater or equal
> Greater
<= Lower or equal

Dates can be formatted either

in ISO8601 format (time part is optional) 2012-09-27, 2012-09-27T12:42:00
in a timestamp in milliseconds 1549365498507

Date Math format

The idea of the date match syntax is to define a relative date compared to an anchor date. The anchor date is either now or a date (ISO8601 or timestamp format) followed by ||.

The expression begins with the anchor date and is followed by one or more math expressions :

+1h adds one hour
-1d substracts one day
/d rounds down to the nearest day

Example, assuming now is 2001-01-01 12:00:00 :

The supported units are the following :

Date operator

description

String operators

Only the indexed fields of type String are eligible. Depending on the specified data_type in the schema, the String operator will behave differently.

With `data_type: text` :

All operators are case-insensitive. .

String operator

description

The same transformation is done on the text data before storage is also done on the comparison value.

Diacritical marks (e.g. é, è, à, ç), number/digits, and word/expression containing apostrophe are usually stored as-is which means that you will need to provide the same value in the match function.

Below are some examples comparing the ingested and stored values, along with a demonstration of the match function:

Value ingested

Values stored

Value matching

Value not matching

With `data_type: keyword` :

All operators are case-sensitive. .

String operator

description

In operator

You can use the IN operator as a shortcut to filter on multiple values of the same field.

This operator offers better performances than multiple OR operators.

Is_defined operator

This is used to evaluate the value of a field and check if it is defined or not. The predicate can be applied in any indexed field in the schema and return a boolean.

Field Value

Return

****

JOIN operations

You may want to add another list of predicates FROM various objects. To do so, use JOIN clause to mention another object right after the FROM/WHERE clauses. It's possible to apply multiple JOIN in the same query.

LIMIT operations

In the Query Tools, we return 10 elements by default but you can easily override this by using the LIMIT clause followed by the number of elements required:

It's not possible to return more than 10 000 elements with LIMIT. The query will fail if you try it.

Note that the LIMIT clause will be ignored when using @count or @cardinality directives.

LIMIT operator isn't applied during the segment calculation.

If you create a User Query Segment with a LIMIT, it will be ignored and return all UserPoint who respect the WHERE clause.

If you're using an aggregation directive such as @map and you want to extend the number of buckets returned, you need to use the limit parameter of the aggregation directive (for instance: @map(limit:200)) and not the LIMIT clause. More details available hereunder.

SELECT operations

They are simply selecting fields. Every field present can be selected.

Filters

, the WHERE expression gives you the ability to filter a sublist of objects at FROM level. You also have the capability to filter in or out the data returned by the query using the @filter directive in SELECT :

Option

Mandatory

Usage

Tips

Here are some tips to properly use the @filter directive in your queries:

Filter multiple fields (note that you can used OR or AND between fields, based on the required filter logic):

Filter in multiple values for a given fields:

Filter out multiple values for a given fields:

Combine AND & OR filters:

Filter by a subfield:

When filter_empty:true option is provided, the following elements will be filtered out:

An optional array which is empty
An object which is empty and either optional or inside an array
A mandatory array where the following conditions are met :

Please note that the @filter directive cannot be used at the same time as aggregation operations such as @map, @date_histogram, ...

Example 1 - Usage of clause

The following query retrieves userpoints, activities, events and some of their field for each UserPoint that has an event named "display".

Let's assume it gives the following result :

The user might be surprised to find "click" events in this result. However remember that the where clause only filter the roots (i.e the UserPoints). To retrieve only "display" events, the user will need to add an @filter clause as follow:

Assuming the same data, this query would produce the following result :

Example 2 - Usage of filter_empty

The @filter predicate also filters by default empty result in its scope. To illustrate this, we reduce our query to retrieve only the score fields :

Still the same data, the result is the following:

You'll notice that two display events have disappeared. Since they don't have a score, they would be empty object. Actually, this "filter empty" behavior can be set using a second optional parameter to the @filter directive. If we set it to false, we will obtain the following result :

Example 3 - Usage of extra @filter

One might think that the previous result still contains a lot of noise (4 events retrieved for only one score). You can add an extra @filter before the object name to lighten the result:

You will get the following result :

Example 3 - Usage of @filter sub-field

@filter can be used to filter a field by a condition on a sub-field.

Aggregation Operations

The aggregation operations are initiated by a directive in the SELECT clause. They take into account the filter defined in the WHERE clause, however they are not compatible with the @filter directive that you can use in the SELECT clause.

@count

This directive is used to count the number of objects verifying the query

Metrics directives

Fields used with metrics directives should have the directive in your schema.

Those directives calculate a value per bucket created in the bucket directive, or with only one bucket containing all elements if you don't use bucket directives.

@avg: average value for a specific field (only applies to numeric values)

@min: minimum value for a specific field (only applies to numeric values)

@max: maximum value for a specific field (only applies to numeric values)

@sum: sum of value for a specific field (only applies to numeric values)

@cardinality: count of distinct values

Bucket directives

Fields used with bucket directives should have the directive in your schema.

Those directives separate values into buckets

@map one bucket per field value

@map does not count null values

You can use the limit function to extend the number or elements that can be returned by the directive (default: 50, maximum: 50 000) :

SELECT { name @map(limit:200) } FROM UserEvent

@histogram aggregated count on a specific field. The interval can be modified regarding the business needs

@date_histogram aggregated count by a period of an object associated with a date. Allowed intervals are 1M for a month and XXD for a XX number of days.

Please note that you cannot use bucket directives with metrics.

Aliases

It is possible to add an alias to the field expression. This alias is then used in the output to identify the field result.

Managing queries

You usually enter OTQL queries directly in tools like the navigator. However, they can be saved and managed by code as objects. Some features will require you to link an object to an OTQL query, instead of just saving the query as text.

Features asking you to save queries to reference them usually want to leverage this for performances optimisation.

Creating a query

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/queries

Create an OTQL query in the platform before creating an export based on this query

Path Parameters

Name

Type

Description

Request Body

Name

Type

Description

Check a query

POST https://api.mediarithmics.com/v1/datamarts/:datamartId/query_check/otql

Create an OTQL query in the platform before creating an export based on this query

Path Parameters

Name

Type

Description

Request Body

Name

Type

Description

Executing queries

You can execute queries in the different tools that mediarithmics offer, or using our API.

Execute a query

POST https://api.mediarithmics.com/v1/datamarts/:datamart_id/query_executions/otql?use_cache=true

Executes an OTQL query on the specified datamart

Path Parameters

Name

Type

Description

Query Parameters

Name

Type

Description

Request Body

Name

Type

Description

Query cache

When setting the use_cache query parameter to TRUE, the system returns the query from the cache if available.

To know if the returned value is from the cache or a new query execution, look at the cache_hit property from the response. Its value is TRUE if the response comes from the cache and FALSE otherwise.

The cache expiration delay is 12 hour.

When not setting the use_cache query parameter or setting its value to FALSE, the cache system is skipped. The query will be executed and its value won't be stored. You can't use this to force a cache update .

Running the query SELECT ... FROM ... WHERE ts >= "now-1h" (with a Date Math format from ) will return the same result now, in five minutes and during the next hour if using the cache.

Queries optimization

Our engine tries to automatically optimize queries before running them. For example, a query with multiple OR operators can use the IN operator instead if it is better.

Developer

UserPoint

hashtagUserPoint merges

User identifiers

Device-based Network IDs

hashtagManaging device registries in the mediarithmics platform

hashtagHow to active a Device Registry on a datamart

Custom Device ID integration

hashtagCreate a new registry

hashtagSubscribe to an existing registry

ID5

hashtagSubscribe to ID5

hashtagActivate ID5 ingestion for your websites

First ID

hashtagSubscribe to First ID

hashtagActivate First ID ingestion from websites

IP address

hashtagOption #1

hashtagOption #2

User-based Network IDs

hashtagManaging compartments in the mediarithmics platform

hashtagHow to activate a compartment on a datamart

hashtagActivate IDs across your organisations:

Custom User ID integration

hashtagCreate a Custom User ID

UTIQ martechpass

hashtagUnderstand UTIQ identifiers

hashtagSubscribe to UTIQ

hashtagActivate UTIQ ingestion from your websites

hashtagStorage and impact on user point merges

UserAccount

hashtagDefinition

UserEmail

UserDeviceTechnicalId

hashtagOrganizing device technical identifiers within registries

hashtagMerge of device points

hashtagDescription of device graph documents

hashtagUser device point

hashtag device property of user device point

hashtagUser device technical identifier

hashtaguser_agent_id

hashtaguser_agent_id formatting - Cookie-based identifiers

hashtagInstallation ID - First-party cookie generated by mediarithmics

hashtagVector ID - mediarithmics third-party cookie

hashtagPartners' third party cookies

hashtaguser_agent_id formatting - Mobile application identifiers

hashtagMobile advertising identifiers

hashtagMobile vendor identifiers

hashtaguser_agent_id formatting - CTV identifiers

hashtagCTV advertising identifiers

hashtagIP addresses captured on CTV channel

hashtaguser_agent_id formatting - Other device identifiers

hashtagUser agents (legacy)

UserActivity & UserEvent

hashtagUser Activity object

hashtagSite visits user activities

hashtagApp visits user activities

hashtagCTV visits user activities

hashtagChannels

hashtagUser Identifier

hashtagUser Account

hashtagUser Email

hashtagUser Agent

hashtagUser Agent info

hashtagActivity Location

hashtagActivity Origin

hashtagOrigin calculation

hashtagOrigin detection based on Google Analytics parameters (UTM)

hashtagOrigin detection based on AT Internet parameter (xtor)

hashtagMarketing Channel inference

hashtagOrigin declaration with predefined event properties

hashtagActivity unique key

hashtagUnique key calculation

hashtagUser Events object

hashtagPredefined event names

hashtagPredefined event properties

hashtagUser Activity JSON schema and TypeScript interfaces

Compartments

UserProfile

hashtagUser profile object

UserPoint merges

Managing device registries in the mediarithmics platform

How to active a Device Registry on a datamart

Create a new registry

Subscribe to an existing registry

Subscribe to ID5

Activate ID5 ingestion for your websites

Subscribe to First ID

Activate First ID ingestion from websites

Option #1

Option #2

Managing compartments in the mediarithmics platform

How to activate a compartment on a datamart

Activate IDs across your organisations:

Create a Custom User ID

Understand UTIQ identifiers

Subscribe to UTIQ

Activate UTIQ ingestion from your websites

Storage and impact on user point merges

Definition

Organizing device technical identifiers within registries

Merge of device points

Description of device graph documents

User device point

`device` property of user device point

User device technical identifier

`user_agent_id`

user_agent_id formatting - Cookie-based identifiers

Installation ID - First-party cookie generated by mediarithmics

Vector ID - mediarithmics third-party cookie

Partners' third party cookies

user_agent_id formatting - Mobile application identifiers

Mobile advertising identifiers

Mobile vendor identifiers

user_agent_id formatting - CTV identifiers

CTV advertising identifiers

IP addresses captured on CTV channel

user_agent_id formatting - Other device identifiers

User agents (legacy)

User Activity object

Site visits user activities

App visits user activities

CTV visits user activities

Channels

User Identifier

User Account

User Email

User Agent

User Agent info

Activity Location

Activity Origin

Origin calculation

Origin detection based on Google Analytics parameters (UTM)

Origin detection based on AT Internet parameter (xtor)

Marketing Channel inference

Origin declaration with predefined event properties

Activity unique key

Unique key calculation

User Events object

Predefined event names

Predefined event properties

User Activity JSON schema and TypeScript interfaces

User profile object

Example:

Audience Segment & UserSegments

Counting and Persistence of an audience segment of type User Query

Hyper point

Quarantine

How-to

Example

User Account deletion command

Example:

User Email deletion command

Example:

User Agent deletion command

How-to

Example

Activities analytics data retention

Transforming important events into your custom events

Event transformations