Device identifiers

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

Devices are represented by user device points
Device identifiers are represented by user device technical ids

A user point 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

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).
`TV_ADVERTISING_ID`	Includes all registries that refer to Smart TVs and TV boxes: AAID on Android TV and Android boxes, IDFA on Apple TV, Amazon Advertising ID on Fire TV, Tizen Advertising ID on Samsung Smart TV etc.
`NETWORK_DEVICE_ID`	For registries designating IDs that are device-related & managed by third parties actors. For instance ID5, First-ID etc. Some network identifiers are directly user-related and not device related (such as the ones generated from the email)
`CUSTOM_DEVICE_ID`	If you want to use your own device identifier (for instance: a 1P cookie that you generate), you can create it under this type.
`MUM_ID`	"mediarithmics User Mapping Identifier" This type and the single registry it contains are dedicated to hosting mediarithmics 3P cookie (vector_id) and references to partners' 3P cookies, until their deprecation

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

TV_ADVERTISING_ID

Includes all registries that refer to Smart TVs and TV boxes: AAID on Android TV and Android boxes, IDFA on Apple TV, Amazon Advertising ID on Fire TV, Tizen Advertising ID on Samsung Smart TV etc.

NETWORK_DEVICE_ID

For registries designating IDs that are device-related & managed by third parties actors. For instance ID5, First-ID etc. Some network identifiers are directly user-related and not device related (such as the ones generated from the email)

CUSTOM_DEVICE_ID

If you want to use your own device identifier (for instance: a 1P cookie that you generate), you can create it under this type.

MUM_ID

"mediarithmics User Mapping Identifier"

This type and the single registry it contains are dedicated to hosting mediarithmics 3P cookie (vector_id) and references to partners' 3P cookies, until their deprecation

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, or subscribe to existing registries under other types.

Once created, you can activate them on the organisation datamarts.

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.

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

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

Property	Type	Description
id	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"`
creation_ts	Timestamp	Timestamp at which the device point was created
last_activity_ts	Timestamp	Last time an event was ingested from this device. This property is not updated at the moment.
device	Object of type `DeviceInfo`	Description of the device through a set of normalized properties
technical_identifiers	List of objects	List of available identifiers for the device

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"

creation_ts

Timestamp

Timestamp at which the device point was created

last_activity_ts

Timestamp

Last time an event was ingested from this device. This property is not updated at the moment.

device

Object of type DeviceInfo

Description of the device through a set of normalized properties

technical_identifiers

List of objects

List of available identifiers for the device

`device` property of user device point

Property Type Description

Property	Type	Description
brand	String	The brand of the device (ex.: "Apple")
model	String	The model of the device (ex.: "Iphone 14")
agent_type	Enum UserAgentType	Indicates the type of device. Possible values: `WEB_BROWSER` or `MOBILE_APP`
browser_family	Enum BrowserFamily	If the device is a browser. Possible values: `OTHER`, `CHROME`, `IE`, `FIREFOX`, `SAFARI`, `OPERA`, `STOCK_ANDROID`, `BOT`, `EMAIL_CLIENT`, `MICROSOFT_EDGE.`
browser_version	String	The version of the browser.
form_factor	Enum FormFactor	Indicates the format of the device. Possible values: `PERSONAL_COMPUTER`, `SMART_TV`, `GAME_CONSOLE`, `SMARTPHONE`, `TABLET`, `WEARABLE_COMPUTER`, `OTHER`.
os_family	Enum OperatingSystemFamily	The operating system family of the device. Possible values: `WINDOWS`, `MAC_OS`, `LINUX`, `ANDROID`, `IOS`, `OTHER`.
os_version	String	The version of the operating system (ex.: "macOS 10.15 Catalina")
carrier	String	The service provider that ensures connectivity of the device.

brand

String

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

model

String

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

agent_type

Enum UserAgentType

Indicates the type of device. Possible values: WEB_BROWSER or MOBILE_APP

browser_family

Enum BrowserFamily

If the device is a browser.

Possible values: OTHER, CHROME, IE, FIREFOX, SAFARI, OPERA, STOCK_ANDROID, BOT, EMAIL_CLIENT, MICROSOFT_EDGE.

browser_version

String

The version of the browser.

form_factor

Enum FormFactor

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

os_family

Enum OperatingSystemFamily

The operating system family of the device. Possible values: WINDOWS, MAC_OS, LINUX, ANDROID, IOS, OTHER.

os_version

String

The version of the operating system (ex.: "macOS 10.15 Catalina")

carrier

String

The service provider that ensures connectivity of the device.

User device technical identifier

Property	Type	Description
user_agent_id	String	The value of the identifier. See format hereunder
registry_id	String	The registry to which the technical identifier
type	Enum RegistryType	The type of the registry to which it is attached. See section above for possible values
creation_ts	Timestamp	Timestamp at which the document was created
last_activity_ts	Timestamp	Last time an event was ingested with this identifier. This property is not updated at the moment.
expiration_ts	Timestamp	Timstamp at which this document will expire. For the moment, technical ids are stored for a period of 1 year after their creation

Property

Type

Description

user_agent_id

String

The value of the identifier. See format hereunder

registry_id

String

The registry to which the technical identifier

type

Enum RegistryType

The type of the registry to which it is attached.

See section above for possible values

creation_ts

Timestamp

Timestamp at which the document was created

last_activity_ts

Timestamp

Last time an event was ingested with this identifier. This property is not updated at the moment.

expiration_ts

Timestamp

Timstamp at which this document will expire. For the moment, technical ids are stored for a period of 1 year after their creation

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 be seen in two formats:

ins:<registry_id>:<value> for all authenticated endpoints
ins:<registry_token>:<version_prefix><base64(value)> for storage in the browser cookie and for non-authenticated endpoints (pixel routes), with version_prefix currently defined as a

Example:

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

Until their planned deprecation, 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 - Other device identifiers

net:<registry_id>:<value> for device technical ids of type NETWORK_ID
dev:<registry_id>:<value> for type CUSTOM_DEVICE_ID
tv:<registry_id>:<value> for type TV_ADVERTISING_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 user point, 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
creation_ts	Timestamp	When the user agent was registered on the platform
mappings	Array	Additional identifiers called the device mappings. They are cookie-based identifiers or mobile application identifiers associated with the agent.

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

creation_ts

Timestamp

When the user agent was registered on the platform

mappings

Array

Additional identifiers called the device mappings. They are cookie-based identifiers or mobile application identifiers associated with the agent.

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",
        }
    ]
},

PreviousEmails NextUser activities and events

Last updated 1 month ago

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 - Other device identifiers

User agents (legacy)

`device` property of user device point

`user_agent_id`