Tracking API
Beware of the authentication method you choose, so that it is adapted to the context running API calls.
User activity API
General information
You can import user activities 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
datamartId
integer
The ID of the datamart in which the user activity should be imported
Headers
Content-Type
string
application/json
Request Body
body
object
The user activity object to import
The body must be a valid user activity 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" : {}
}]
}
{
"$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"
}
}]
}
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.
Please note that those events will go through the processing pipeline before being stored as a user choice. You must ensure no activity analyzers is removing them during that process.
// 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
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
update_strategy
Enum (Optional)
Values are PARTIAL_UPDATE
, PARTIAL_DELETE
, FORCE_REPLACE
(Detailed examples)
Legacy parameters (use update_strategy instead)
force_replace
boolean (optional)
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 (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
Content-Type
string
application/json
Request Body
body
object
The user profile object to import
The body must be a valid user profile object.
{
"$compartment_id" : ":compartment_id",
"$user_account_id" : ":user_account_id",
"gender" : "female",
"zipcode" : "75001"
}
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
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
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
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
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
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
Body
object
The payload
Last updated
Was this helpful?