User guidesDeveloper websiteHelp centerLog in

Tracking API

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

UserActivity API

General information

You can import UserActivity using our dedicated API endpoint.

Import a UserActivity

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

The body of the request must be a UserActivity object.

Path Parameters

Name
Type
Description

datamartId

integer

The ID of the datamart in which the UserActivity should be imported

Headers

Name
Type
Description

Content-Type

string

application/json

Request Body

Name
Type
Description

body

object

The UserActivity object to import

The body must be a valid UserActivity object.

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 UserProfile from within an activity

A UserProfile can be created / updated by registering a UserActivity 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 UserProfile 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 UserPoint in the UserActivity object

Create / Update a UserChoice from within an activity

A UserChoice can be created / updated by registering a UserActivity 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.

Please note that those events will go through the processing pipeline before being stored as a UserChoice. You must ensure no activity analyzers is removing them during that process.

// Sample UserActivity 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>"
            }
        }
    ]
}

UserPoint API

UserPoint selector

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

// Select a UserPoint 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 UserPoint 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 UserPoint 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 UserPoint 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 UserProfile

An other way to create / update a UserProfile 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 UserProfile update as an event for further retrieval.

Create/Update a UserProfile

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 UserProfile 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 UserProfile should be imported

datamartId

integer

The ID of the datamart in which the UserProfile should be imported

userSelector

string

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

Query Parameters

Name
Type
Description

update_strategy

Enum (Optional)

Values are PARTIAL_UPDATE, PARTIAL_DELETE, FORCE_REPLACE (Detailed examples)

Legacy parameters (use update_strategy instead)

Name
Type
Description

force_replace

boolean (optional)

If true, then the UserProfile 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 UserProfile of the UserPoint.

merge_objects

boolean (optional)

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.

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

Headers

Name
Type
Description

Content-Type

string

application/json

Request Body

Name
Type
Description

body

object

The UserProfile object to import

The body must be a valid UserProfile object.

{ 
	"$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 UserPoint

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

Create / Update a UserChoice

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

Create/Update UserChoice

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 UserPoint for which the UserChoice should be added.

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 UserChoice

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 UserPoint for which the UserChoice should be added.

processingId

integer

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

Request Body

Name
Type
Description

Body

object

The payload

UserChoice 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 UserPoint for which the UserChoice should be added.

processingId

integer

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

Request Body

Name
Type
Description

Body

object

The payload

PreviousEmail views and clicksNextEvent rules

Last updated

Was this helpful?