Advanced topics:: Anonymous and known user data flow in Mobile Engage – Emarsys

Terms

Here you can find the most important terms related to anonymous and known user data flow in Mobile Engage:

Emarsys Mobile Engage Database (ME DB): a device database collecting all device-specific information. For example: hardware ID (= device identifier), push token, device language, mobile application version, etc.
Emarsys Contact Database (Contact DB): a consumer database, where the Emarsys client is collecting all personal data of their consumers. For example: first name, last name, email, address.
Contact ID: the contact identifier that is reserved and sent by the customer’s platform to Emarsys via Contact API or CSV imports when it adds the contact to the Emarsys Contact DB.

Please note it is not allowed to use hashed email address, salted hashed email, or email in plain text as contactID. For more information about this security requirement, see Contact Management.

Anonymous Contact identifier: a field in the Emarsys Contact DB that is populated only for anonymous contact records filled with HardwareID of the device of the anonymous contact. This field connects the anonymous contact record in the Emarsys Contact DB and the device record in the Emarsys ME DB.
Anonymous contact: Personal information (name, email, address, etc.) of such contacts is not stored by Emarsys, apart from their device information (i.e. device type, app version, platform of the device, etc.). Creation of anonymous contact records in the Contact DB is triggered by Emarsys SDK for the first time when the mobile application is started on a new device. The anonymous contact is created even before the contact logs in, except if the Disable generating anonymous contact records feature is activated within the app settings. contactID is the only field that is populated in the anonymous contact record that is used to link the anonymous contact record to the device record in the ME DB.
Known contact: Emarsys stores personal profile information (e.g. name, email, address, etc.) of such contacts. Furthermore, if the contact has used your mobile application, then Emarsys stores the contact's device information. Known contacts are created in the Contact DB by Emarsys clients via the Contact API (or automated CSV file import).

You can see the difference between anonymous and known contact records in the following image.

Anonymous contact-specific use cases

You can engage with contacts who have not registered or logged in to your mobile application yet. For example, you can send push notifications to anonymous contacts if they have accepted push notifications.
You can engage with contacts who logged out from your mobile application. Their full history before they logged in to the mobile application is also at your disposal. For example, you can convert these contacts to known contacts. After logging out, if anonymous contact records of contacts are not deleted (for more information, see the Removing already existing anonymous contact records feature), you can still reach them because the Emarsys Platform falls back to the anonymous contact records (and you can convert them to known contacts).

How does the data flow work for anonymous and known users?

Anonymous contact data workflow

You can see the data flow of anonymous contacts in the following diagram:

A contact has a new device (i.e. a device the HardwareID of which does not exist in the Mobile Engage database) and downloads and installs the mobile application to which the Emarsys Mobile SDK is integrated.
The contact opens the app for the first time.
Emarsys SDK triggers the Emarsys Platform with an unknown login call.
The Emarsys Platform checks whether this device (based on the HardwareID) is already stored in the ME DB and in the Contact database.
If the device has not yet been stored in the Contact DB, then a new anonymous contact record is created. The anonymous contact record will contain a mobile app-specific AnonymousContactIdentifier field which is populated with the HardwareID of the device. Using the unique HardwareID prevents creating duplicate anonymous contact records. The anonymous contact record does not contain profile data (e.g. the name, email, address, etc. fields will be empty).
If the device has not yet been stored in the ME DB, then a new record is created. The device record in the ME DB will contain a field (HardwareID) which stores the HardwareID of the device.
The contact can decide whether they wish to grant push notification permission for the device.
If the contact grants push notification permission, then Emarsys SDK acquires a push token from Firebase Cloud Messaging (FCM) or Apple Push Notification Service (APNS) and sends the received push token to the Emarsys Platform.
Since a device had been already created in the ME DB, the Emarsys Platform stores the push token for that device record in the ME DB (which is connected to an anonymous contact record in the Contact DB).
The stored push token allows you to send non-personalized (it's important that the contact is anonymous) push notifications to the contact.
If the contact does not grant push notification permission, then the anonymous contact record is still kept, but you cannot send push notifications to that contact.

In this case, you can still reach the anonymous contact via other Mobile Engage channels such as In-app Messages or Inbox campaigns.

Known contact data workflow

You can see the data flow of known contacts in the following diagram:

When the contact logs in to the app for the first time, the mobile application makes a call to the client's platform which contains data given by the contact (e.g. first name, last name, email address, etc.).
The client's platform checks whether it is a new contact based on the data given by the contact.
If it is a new contact, then a new record is created for the contact in the database of the client's platform.
The client's platform sends the data of the new contact (e.g. contactID (internal, non-PII identified), first name, last name, email address, etc.) to the Emarsys Platform and requests it to create a known contact record in the Contact database. The client's platform uses the Contact API or CSV file import.

Please bear in mind that the SDK cannot create any known contacts in the Contact DB. This means that you will need to create known contacts (with externalID, first name, email, etc.) via the ContactAPI or file imports.

The client's platform sends the contactID back to the mobile application.
The mobile application uses the Emarsys Mobile SDK setContact method with the contactID (that consists of contactFieldValue and contactFieldID).
The Emarsys Platform checks whether the contactID is available in the Contact DB.
If the contactID cannot be found in the Contact DB, then a retry mechanism is triggered, which keeps trying to find the contact up to 48 hours until the contact is defined in the Contact DB. If the contact cannot be found within 48 hours, then the Emarsys Mobile SDK setContact method is dropped and the device will stay associated with the anonymous contact.

There might be some delay between the setContact call and creation of the known contact via the API or file import that's the reason for triggering the retry mechanism.

If the contactID is found in the Contact DB, then the device record in the Mobile Engage database is mapped to the known contact record that has just been created.
Since a known contact is mapped to a device record which stores the push token, the contact can receive personalized push messages.
The following two steps describes what happens when the contact logs out from your mobile app.
The mobile app logs out the contact by calling the Emarsys SDK clearContact method.
The Emarsys SDK clearContact method triggers the Emarsys Platform to unmap the device record from the known contact record and at the same time map the device record back to the anonymous contact record. If the Emarsys Platform still stores the push token, it is possible to send non-personalized push messages to this anonymous contact.

It is possible to set up an automatic deletion of anonymous contacts (e.g. if they are inactive for a specific timeframe). For this reason, it's important to know that if we receive a clearContact call and the Emarsys Platform cannot find the anonymous contact in the contact database, then Emarsys automatically creates a new anonymous contact record for the contact.