This document outlines the data flow model used by Mobile Engage. The following cases are covered:

Device and user registration

device-and-user-registration

When customers install your mobile application 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 application, where it is stored locally.

Apart from this, the customer’s data should be created (or updated) in the Emarsys API database.

When these are ready, the app should call the login endpoint with the contact identifier and device data. These are stored in the Mobile Engage API and it responds with the contact_id parameter.

Obtaining and storing the push token

obtaining-andstoring-push-token

When your application is registered with Google and/or iOS, a push token is created for you. As soon as your clients opt in to receiving push notifications, this push token becomes available from our delivery partner’s 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

handling-user-data

After the mobile app is installed, it can immediately start to process events. These events are sent to the Mobile Engage API and their data is stored locally in the app.

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.

  • If the answer is yes, the contact update should take place from the locally stored data and then the app waits for the next events.
  • If the answer is no, there is no action to be taken; the app now waits for the next events.

From this point the loop repeats itself.

Working with contacts

creating-contact

When the app starts on the mobile device, the login endpoint can be called in two ways:

  • Without contact identifier data.
  • With contact identifier data.

Contact identifier data means data that can be used to determine exactly who the contact using the app is.

Calling without contact identifier data

If the login endpoint is called without contact identifier data, it has to determined whether a Mobile Engage Created (MEC) contact exists for this device or not. If not, the MEC contact is created. If there is a contact for the device, the contact_id is associated with the device. The email of the contact is not known.

Calling with contact identifier data

If the login endpoint 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 push token associated to the user, personalized push notifications can be sent out.

If the logout endpoint 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.

Handling opened messages

handling-opened-messages

When a push message is sent from Emarsys, our delivery partner handles and forwards 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 app obtains the sid (message identifier) parameter. The app now calls the message_open API endpoint with the application_id, the hardware_id and the sid parameters.

The Mobile Engage API is linked to the Mobile Engage reporting service, where this information is processed.