This document outlines the data flow model used by Mobile Engage.
Contents
Device and user registration
When customers install your mobile app they have the opportunity to register with you. When they do, the data is sent to your backend. Here, an internal contact identifier is created and this is sent back to the app, where it is stored locally.
Apart from this, the customer’s data should be created through your CRM system, or updated in the Emarsys API database.
When these are ready, the app should call the appLogin function (iOS, Android) with the contact identifier and device data.
Obtaining and storing the push token
When your app is registered with Google and/or Apple, a push token is created for you. As soon as your clients opt in as an anonymous user to receiving push notifications, this push token becomes available from our SDK incorporated in your app.
The push token is now sent to the Mobile Engage API where it is stored in its database. At the same time, Mobile Engage sets the push_accepted field to 1 in the Emarsys contact database and the device is listed in the Mobile Engage device registry.
Handling user data
After the mobile app is installed, it can immediately start to process events. These events are sent to the Mobile Engage SDK and their data is stored locally in the SDK.
If there is a logout or login event happening in the app and the active contact in the app has changed, the app has to decide whether it should update the contact data or not.
From this point the loop repeats itself.
Working with contacts
When the app starts on the mobile device, the appLogin function (iOS, Android) can be called in two ways:
- Without contact identifier data
- With contact identifier data
1. Calling without contact identifier data
If the appLogin function (iOS, Android) is called without contact identifier data, the email address (or any other identifying field) of the contact is not known. Mobile Engage will first determine whether a Mobile Engage Created (MEC) contact exists for this device or not.
- If there is an MEC contact for the device, the
contact_idis associated with the device. - If not, the MEC contact is created.
Later on, when the contact enters their personal data, the MEC contact will either be synced with an existing Emarsys contact, or a new Emarsys contact will be created.
When to use this method
If you do not require the contact to enter personal data on app download and installation, you must use this method.
Even if you do collect data on installation, this is still the safest method to use, since it guarantees that the contact will be created as an MEC first and then synced to Emarsys.
2. Calling with contact identifier data
If the appLogin function (iOS, Android) is called with the contact identifier data, the active contact_id is associated with the device, together with the other known data of the user, e.g. email address. If there is also a valid push token associated to the user, personalized push notifications can be sent out.
If the logout function is called, since the contact has logged out, the MEC contact is re-associated with the device and from this point the MEC contact is using the app again.
If the contact identifier is not known to Mobile Engage, and new MEC is not created, and therefore this contact will not later be synced to Emarsys.
When to use this method
Because this method does not create a new MEC contact for new app users, this method should only be used if your app pushes the contacts to another CRM tool, which then synchronizes with Emarsys. Otherwise you will not be able to engage with these new registrations using any of the other Emarsys channels.
Handling opened messages
When a push message is sent from Emarsys, we forward the message to Google or Apple. From these messaging platforms the message is sent to your mobile app.
When the user opens the push notification, the trackMessageOpen function must be called in the SDK. On Android, this happens automatically, but on iOS it should be done manually. Then the SDK sends the sid parameter contained in the message to the API.
The Mobile Engage backend is linked to the Mobile Engage reporting service, where this information is processed.