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

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 user points, a merge of device points will induce the merge of user points as well.

For some ids that are considered as probabilistic (e.g. that can create false positive matchings of users), the merge of device points/user points 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
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

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

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.

user_agent_id formatting - Cookie-based identifiers

Installation ID - First-party cookie generated by mediarithmics

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

Vector ID - mediarithmics third-party cookie

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.

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.

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