Mobile tracking is a variation of the usual web tracking, but it isn’t tracking user behaviour (viewed pages, orders etc.) and other user updates via a webbrowser with the help of a cookie to continuously identify users.
Instead a separate mobile id (e.g. app id) gets assigned to a user profile, which is then used for any future updates to the user. These mobile ids must be unique, but a user can have multiple active mobile ids that could connect different apps or other sources to the user profile.
In this article you will read more about:
Tracking Methods
There are two methods, “identify” and “track”, similar to the regular web tracking. Both have a slightly different API endpoint, which includes the Mobile tracking API key which can be found in the System Setup.
Identify
The main purpose of “identify” is to assign the mobile Id of a user to an already existing user profile (or lead). In order to do that, either the external Id or the combination of email and businessUnit must be known, since these are the unique identifier in the Spotler ActivatePro system.
Additionally its also possible to update user traits with this method.
API endpoint
POST /api/v1/mobile/{mobileApiKey}/identify
Headers
Content-Type: application/json
Parameter list in the payload
| Parameter | Required | Info |
|---|---|---|
| mobileId | Required | mobile id of customer |
| userId | Optional* | external user id of customer |
| Optional* | email of customerParameter | |
| businessUnit | Optional* | business unit of customer |
| timestamp | Automatic | now |
| traits | Optional | traits of customer |
*Either userId (=external Id) or email+businessUnit must be provided in every “identify”-call.
Example payload
{
"userId": "ext123456",
"mobileId": "mob123456",
"type": "identify",
"traits": {
"firstName": "Brad",
"lastName": "Pitt",
"language": "en"
}
}
{
"email": "ext123456@example.com",
"businessUnit":"test",
"mobileId": "mob123456",
"type": "identify",
"traits": {
"firstName": "Brad",
"lastName": "Pitt",
"language": "en"
}
}
Track
“Track” is the method to send events to the system, which uses the previously assigned mobile Id as the identifier. It is possible to send any event, similar to the regular API.
API endpoint
POST /api/v1/mobile/{mobileApiKey}/track
Headers
Content-Type: application/json
Parameter list in the payload
| Parameter | Required | Info |
|---|---|---|
| mobileId | Required | mobile id of customer |
| type | Required | send as "track" |
| event | Required | event name |
| properties | Optional | properties of the event |
| timestamp | Automatic | now |
Example payload
{
"mobileId": "mob123456",
"type": "track",
"event": "Completed Order",
"properties": {
"cart": {
"total": 0,
"currency": "EUR",
"products": [
{
"id": "507f1f77bcf86cd879439023",
"sku": "61979589",
"name": "Zegna Shirt",
"price": 150,
"quantity": 1,
"category": "Shirts",
"hasZipper": false
},
{
"id": "507f1f77bcf86cd799439011",
"sku": "51979501",
"name": "Levi Jeans",
"price": 100,
"quantity": 1,
"category": "Jeans",
"hasZipper": true
}
]
}
}
}
{
"mobileId": "mob123456",
"type": "track",
"event": "Viewed Page",
"properties": {
"url":"www.example.com"
}
}
Update User-Traits (with and without "Identify"-call)
The mobile tracking API does not have an "Update"-method like the regular web tracking to update user-traits, but user trait can be updated with both the "Identify"- and the "Track"-method.
Example "track":
{
"mobileId": "mob123456",
"type": "track",
"event": "Viewed Page",
"properties": {
"url":"www.example.com"
},
"traits": {
"language": "de"
}
}
Anonymous Tracking
Its not mandatory to identify users before tracking can happen. If a mobile Id used by the “track”-method is not yet assigned to an existing user, its still possible to track the events. Similar to a not identified regular web tracking user, the system will create a new user profile as an anonymous user.
If at any time later this mobile id is used in an “identify”-call, then this anonymous user will get merged into the already existing user (or updated with the external Id if no user with that id exists yet).
Known issues
Re-assigning mobile Ids
There is no functionality that prevents assigning a mobile Id to a new user. In this case the mobile Id simply gets removed from the old user and added to the new one. Any previously merged events and traits remain in the old user and don’t get moved with the id.
API calls too fast
Example: If a user gets identified and a track call for the same mobile Id gets sent too fast or even at the same time, this could in some rare cases result in duplicated users/multiple users with the same mobile Id.
It is recommended to have at least a few hundred ms between calls.