Mobile Web Tracking

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.

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 Crossengage 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
email	Optional*	email of customer
businessUnit	Optional*	business unit of customer
type	Required	send as "identify"
timestamp	Optional	if not provided, it will be “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": "[e-mail]",
	"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	Optional	if not provided, it will be “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.