Developer
User guidesDeveloper websiteHelp centerLog in
  • Welcome!
  • Organisations structure
    • Datamart
    • Users and roles
  • User points
    • User identifiers
      • Networks IDs
        • Device-based Network IDs
          • Custom Device ID integration
          • ID5
          • First ID
        • User-based Network IDs
          • Custom User ID integration
          • UTIQ martechpass
      • Accounts
      • Emails
      • Device identifiers
    • User activities and events
    • Compartments
    • User profiles
    • User segments
    • Hyper point & Quarantine
  • Data model
    • Defining your schema
    • Computed fields
      • Concepts
      • Setup
      • Development
      • Examples
  • Data ingestion
    • Real time user tracking
      • Website tracking
      • Mobile apps tracking
      • Ads exposure tracking
      • AMP tracking
      • Conversions tracking
      • Email views and clicks
      • Tracking API
      • Event rules
      • Activity analyzers
    • Bulk processing
      • Imports
        • User activities import
        • User profiles import
        • User choices import
        • Segments import
      • Deletions
        • User identifiers deletion
        • Device points deletion
        • User points deletion
      • User identifiers association
      • Integration batch
    • Activities analytics
    • Data warehouse
      • Preliminary setup
        • BigQuery
      • Create data warehouse
  • Querying your data
    • OTQL queries
    • OTQL examples
    • GraphQL queries
    • UserPoint API
    • User activities
    • Activities analytics queries
      • API Quickstart
      • Dimensions and metrics
      • Use cases
    • Funnel API
  • Alerting
    • Alert configurations
  • Data visualisation
    • Quickstart
    • Dashboards
    • Sections and cards
    • Charts
    • Datasets and data sources
      • Using a data file data source
    • Transformations
    • Filters
    • Cookbook
    • Reference
  • Advanced usages
    • Audience segmentation
      • Audience features
      • Segment builders
      • Audience segment metrics
      • Audience segment feed
        • Building new feeds
        • Monitoring a feed
        • Curated Audiences (SDA)
      • Edge segments
      • Cohort-based Lookalike
    • Contextual targeting
      • Setup
      • Activation
        • Google Ad Manager
        • Xandr (through prebid.js)
      • API documentation
    • Exporting your data
      • Query Exports
      • Datamart replication
    • Data privacy compliance
      • User choices
      • Cleaning rules
      • Exercise of user rights
      • Cookies
    • Campaigns
    • Automations
      • Email routers
      • Email renderers
      • Opt-in provider
      • Custom action plugins
      • Usage limits for automations
    • Plugins
      • Concepts
      • Creation & Deployment
      • Coding your plugin
      • Manage existing plugins
      • Layouts
      • Presets
      • Monitoring
      • Throttling
      • Batching (for external feeds)
    • Platform monitoring
      • Resources usage
        • Dimensions and metrics
      • Collection volumes
        • Dimensions and metrics
      • Events ingestion monitoring
        • Dimensions and metrics
    • Data Clean Room
      • Bunker
      • Clean room
  • Resources
    • Tutorial: Data Ingestion
      • Your first events
        • Add the mediarithmics tag
          • Getting the tag
          • Adding the tag
        • Send events using the tag
          • Adding event properties
          • Finding the UserEvent type in your schema
          • Matching your schema
          • Standard events
      • Your first bulk imports
        • API basics
          • Authentication
          • Your first API call
        • Send documents using the API
          • Requirements
          • Sending documents
    • Using our API
      • Authentication
    • Tools & libraries
      • mics CLI
      • JS Tag
      • Plugin SDK
    • Data cubes
      • Creating a report
      • Reference
Powered by GitBook
On this page
  • User activity API
  • General information
  • Import a user activity
  • Create / Update a user profile from within an activity
  • Create / Update a user choice from within an activity
  • User point API
  • User point selector
  • Create / Update a user profile
  • Create/Update a user profile
  • Create / Update a user choice
  • Create/Update user choices
  • List user choices
  • User choices history

Was this helpful?

Export as PDF
  1. Data ingestion
  2. Real time user tracking

Tracking API

PreviousEmail views and clicksNextEvent rules

Last updated 2 days ago

Was this helpful?

Beware of the you choose, so that it is adapted to the context running API calls.

User activity API

General information

You can import using our dedicated API endpoint.

Import a user activity

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

The body of the request must be a User Activity object.

Path Parameters

Name
Type
Description

datamartId

integer

The ID of the datamart in which the user activity should be imported

Headers

Name
Type
Description

Content-Type

string

application/json

Request Body

Name
Type
Description

body

object

The user activity object to import

Identification of the user or of the device is achieved through the $user_identifiers property. We encourage you to use as many identifiers as available in your environment at the time of the capture.

{ 
	"$ts" : 3489009384393,
	"$type" : "APP_VISIT",
	"$session_status" : "IN_SESSION",
	"$user_identifiers" : [{
		"$type": "USER_ACCOUNT",
		"$compartment_id" : "<COMPARTMENT_ID-1>",
		"$user_account_id" : "<ACCOUNT_ID-1>"
	},
	{
		"$type": "USER_ACCOUNT",
		"$compartment_id" : "<COMPARTMENT_ID-1>",
		"$user_account_id" : "<ACCOUNT_ID-2>"
	},
	{
		"$type": "USER_AGENT",
		"$user_agent_id" : "<USER_AGENT_ID>"
	},
	{
		"$type": "USER_EMAIL",
		"$hash" : "<USER_EMAIl_HASH>",
		"$email" : "<USER_EMAIl>"
	}],
	"$app_id" : "1023",
	"$events" : [
	{
		"$ts" : 3489009384393,
		"$event_name" : "$app_open",
		"$properties" : {}
	}]
}

It is still possible to use the identifiers properties at the activity root level ($user_agent_id, $user_account_id + $compartment_id, $email_hash), however these are to be considered as legacy.

$user_identifiers property is to be preferred.

{ 
	"$ts" : 3489009384393,
	"$type" : "APP_VISIT",
	"$session_status" : "IN_SESSION",
	"$user_agent_id" : "<USER_AGENT_ID>",
	"$compartment_id" : "<COMPARTMENT_ID>",
	"$user_account_id" : "<ACCOUNT_ID>",
	"$app_id" : "1023",
	"$events" : [
	{
		"$ts" : 3489009384393,
		"$event_name" : "$app_open",
		"$properties" : {}
	}]
}

Create / Update a user profile from within an activity

A user profile can be created / updated by registering a user activity containing a $set_user_profile_properties event. In that case you would need to use $user_account_id and $compartment_id inside $properties to identify the user profile to update:

{ 
	"$ts" : 3489009384393,
	"$type" : "APP_VISIT",
	"$session_status" : "IN_SESSION",
	"$user_identifiers" : [{
		"$type": "USER_ACCOUNT",
		"$compartment_id" : "<COMPARTMENT_ID>",
		"$user_account_id" : "<ACCOUNT_ID>"
	}],
	"$app_id" : "1023",
	"$events" :[{
        	"$ts" : 1679588413000,
	        "$event_name" : "$set_user_profile_properties",
        	"$properties" : {
               		"$compartment_id" : "<COMPARTMENT_ID>",
               		"$user_account_id" : "<ACCOUNT_ID>",
               		"gender" : "Male",
	               	"zipcode" : "78000"
        	}
	}]
}

Note that you can used any identifier available on the user point in the user activity object

Create / Update a user choice from within an activity

A user profile can be created / updated by registering a user activity containing a $set_user_choice event.

This method is used when you want to achieve real-time tracking but can't use the mediarithmics JavaScript Tag. In mobile applications for example.

// Sample user activity to add using the tracking API
{
    "$user_account_id":"<your_user_account_id>",
    "$compartment_id":<your_compartement_id>,
    "$type":"<your_activity_type (ex: SITE_VISIT)",
    "$site_id": "<your_site_id>",
    "$session_status":"NO_SESSION",
    "$ts":<a_timestamp (ex:1572947762)>,
    "$events": [
        {
        "$event_name":"$set_user_choice",
        "$ts":<a_timestamp (ex:1572948120)>,
        "$properties":{
            "$processing_id": "<your_processing_id>", // Mandatory
            "$choice_acceptance_value":<true/false>, // Mandatory
            "<your_custom_field>" : "<your_custom field_value>"
            }
        }
    ]
}

User point API

User point selector

The attribute :userPointSelector is used to select the user point on which apply the query. You can provide the following values :

// Select a user point using a user_point_id
/v1/datamarts/<DATAMART_ID>/user_points/<USER_POINT_ID>/user_profiles/compartment_id=:compartmentId/user_account_id=:userAccountId
/v1/datamarts/<DATAMART_ID>/user_points/user_point_id=<USER_POINT_ID>/user_profiles/compartment_id=:compartmentId/user_account_id=:userAccountId

// Select a user point using a user_agent_id
/v1/datamarts/<DATAMART_ID>/user_points/user_agent_id=<USER_AGENT_ID>/user_profiles/compartment_id=:compartmentId/user_account_id=:userAccountId

// Select a user point using a user_account_id + compartment_id
/v1/datamarts/<DATAMART_ID>/user_points/compartment_id=<COMPARTMENT_ID>,user_account_id=<USER_ACCOUNT_ID>/user_profiles/compartment_id=:compartmentId/user_account_id=:userAccountId

// Select a user point using an email_hash
/v1/datamarts/<DATAMART_ID>/user_points/email_hash=<EMAIL_HASH>/user_profiles/compartment_id=:compartmentId/user_account_id=:userAccountId

Create / Update a user profile

An other way to create / update a user profile is to use the user_profiles API endpoint . Prefer this method if you are able to integrate various API endpoints and if you don't need to track the user profile update as an event for further retrieval.

Create/Update a user profile

PUT https://api.mediarithmics.com/v1/datamarts/:datamartId/user_points/:userPointSelector/user_profiles/compartment_id=:compartmentId/user_account_id=:userAccount

The body of the request must be a User Profile object.

Path Parameters

Name
Type
Description

userAccount

string

The user_account_id linked to the user_profile that should be imported

compartmentId

integer

The ID of the compartment in which the user profile should be imported

datamartId

integer

The ID of the datamart in which the user profile should be imported

userSelector

string

The identifier of the user for whom the user profile should be imported. see the options of the user selector.

Query Parameters

Name
Type
Description

update_strategy

Enum (Optional)

Legacy parameters (use update_strategy instead)

Name
Type
Description

force_replace

boolean (optionnal)

If true, then the User Profile will be completely replaced by the object passed in the user_profile field. If false, the object passed in the user_profile field will be merged with the existing User Profile of the User Point.

merge_objects

boolean (optionnal)

Only considered if force_replace is false.

Manage the comportement between two objects with a same property.

If false (default value), the new object overrides the existing one.

Headers

Name
Type
Description

Content-Type

string

application/json

Request Body

Name
Type
Description

body

object

The user profile object to import

{ 
	"$compartment_id" : ":compartment_id",
	"$user_account_id" : ":user_account_id",
	"gender" : "female",
	"zipcode" : "75001"
}

$compartment_id & $user_account_id in the payload are not mandatory since they are already provided as query parameters.

Beware of :

  • <COMPARTMENT_ID> & <USER_ACCOUNT_ID> which are used to select the user point

  • :compartmentId & :userAccountId which are used to select the profile to update

Create / Update a user choice

An other way to create / update a user choice is to use the user_choices API endpoint . Prefer this method if you are able to integrate various API endpoints.

Create/Update user choices

PUT https://api.mediarithmics.com/v1/datamarts/:datamartId/user_points/:userSelector/user_choices/processing_id=:processingId

Path Parameters

Name
Type
Description

datamartId

integer

The datamart ID

userSelector

integer

An identifier to the user point for which the user choice should be added.Could be :

processingId

integer

The ID of the associated processing

Request Body

Name
Type
Description

Body

object

The payload

// Sample payload
{
    "$choice_ts": "<a_timestamp (ex:1573135588140)>", // Mandatory
    "$choice_acceptance_value":<true/false>, // Mandatory
    "<your_custom_field>" : "<your_custom field_value> // Optional
}

List user choices

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/user_points/:userSelector/user_choices/processing_id=:processingId

Path Parameters

Name
Type
Description

datamartId

integer

The datamart ID

userSelector

integer

An identifier to the user point for which the user choice should be added.Could be :

processingId

integer

Optional. The ID of the processing for which you want to list user choices.

Request Body

Name
Type
Description

Body

object

The payload

User choices history

GET https://api.mediarithmics.com/v1/datamarts/:datamartId/user_points/:userSelector/user_choices/processing_id=:processingId/change_log

Path Parameters

Name
Type
Description

datamartId

integer

The datamart ID

userSelector

integer

An identifier to the user point for which the user choice should be added.Could be :

processingId

integer

The ID of the processing for which you want to get user choices history.

Request Body

Name
Type
Description

Body

object

The payload

The body must be a valid object.

Please note that those events will go through the before being stored as a user choice. You must ensure no is removing them during that process.

Values are PARTIAL_UPDATE, PARTIAL_DELETE, FORCE_REPLACE ()

If true the new object is merged in deep to the existing one (see ).

The body must be a valid object.

authentication method
user activities
user activity
user profile
activity analyzers
processing pipeline
Detailed examples
example