Workflow

This document describes the workflow of the v3 of the Mobile Engage API.

Process

  1. App start-up

  2. App/Browser loads Emarsys SDK

  3. As part of initialization (before any behavior could be tracked),

    1. If device properties have changed or were never sent: Emarsys SDK automatically registers the device properties with the ME Backend. Emarsys SDK gets back the X-CLIENT-STATE which it stores and then sends on every other request. See /apps/:appCode/client endpoint of Client Properties Service

    2. If there are no contact tokens and anonymous users are enabled: Emarsys SDK automatically links the anonymous user with the ME Backend and receives a refresh-token as well as a contact token and stores them on the device. See /apps/:appCode/client/contact?anonymous endpoint of Client Service

  4. The Emarsys SDK automatically registers a app:start internal event to the DES servers using the contact token received. See /apps/:appCode/client/events endpoint of Device Event Service

  5. The app may or may not receive a push token from the push token provider (fcm/apns/chrome/firefox/safari), but if it does, the Emarsys SDK always registers the push token with the ME Backend. See /apps/:appCode/client/push-token endpoint of Client Service.

  6. The app developer can ask the SDK to track interaction and events, and the Emarsys SDK will register the event with the ME Backend using the current contact token. See /apps/:appCode/client/events endpoint of Device Event Service

  7. The app user signs into the customer backend, the customer backend verifies the credentials and provides the app with the unique, non-guessable, immutable value assigned to an Emarsys CRM Database contact. The Emarsys SDK uses that value as the contact field value (together with the initially configured contact field id) and sends it to the ME backend to link the client to the contact. The Emarsys SDK receives new refresh and contact tokens. See /apps/:appCode/client/contact endpoint of Client Service.

  8. When the app user logs out from the customer backend, the app developer will trigger the Emarsys SDK to unlink the identified contact and link to a new anonymous contact. The Emarsys SDK receives new refresh and contact tokens. See /apps/:appCode/client/contact?anonymous endpoint of Client Service.

Typical scenario

App downloaded from app store and started for the first time

  1. Because there was never a registration of the device’s properties to the backend, the Emarsys SDK calls the /apps/:appCode/client endpoint without app developer input. The SDK stores X-CLIENT-STATE and a hash of what it sent to /apps/:appCode/client.

  2. Because the local contact token and refresh token do not exist, the Emarsys SDK calls the /apps/:appCode/client/contact?anonymous endpoint without app developer input just to link the device to an anonymous user. The SDK stores the returned contact- and refresh token.

  3. No matter what the state of previous calls were, the Emarsys SDK automatically calls the /apps/:appCode/client/events endpoint with X-CONTACT-TOKEN and the internal session:start event without app developer input. The SDK also sends the X-CLIENT-STATE it has stores the newly returned X-CLIENT-STATE and a hash of what it sent to /apps/:appCode/client.

Once the app receives the push token, either the SDK directly receives it and registers it or the app developer triggers an update of the push token with /apps/:appCode/client/push_token endpoint.

  1. If the app user at a later stage verifies their credentials with the customer backend, the app developer uses the immutable, unique and non-guessable identifier it stored on the Emarsys CRM DB it got from its backend and uses the Emarsys SDK to call /apps/:appCode/client/contact with that identifier. The SDK also sends the X-CLIENT-STATE it has and stores the newly returned X-CLIENT-STATE.

App was already on the device and the user already logged into to the customer backend and was started for the first time since it was upgraded to an Emarsys SDK using version

  1. Because there was never a registration of the device’s properties to the backend, the Emarsys SDK calls the /apps/:appCode/client endpoint without app developer input. The SDK stores X-CLIENT-STATE and a hash of what it sent to /apps/:appCode/client.

  2. Because the local contact token and refresh token do not exist, the Emarsys SDK calls the /apps/:appCode/client/contact?anonymous endpoint without app developer input just to link the device to an anonymous user. The SDK stores the returned contact- and refresh token.

  3. No matter what the state of previous calls were, the Emarsys SDK automatically calls the /apps/:appCode/client/events endpoint with X-CONTACT-TOKEN and the internal session:start event without app developer input. The SDK also sends the X-CLIENT-STATE it has stores the newly returned X-CLIENT-STATE and a hash of what it sent to /apps/:appCode/client/contact.

  4. Once the app receives the push token, either the SDK directly receives it and registers it or the app developer triggers an update of the push token with X-CONTACT-TOKEN and the /push-token endpoint. The SDK also sends the X-CLIENT-STATE it has and stores the newly returned X-CLIENT-STATE and a hash of what it sent to /pushtoken.

  5. As the app user was already authentified, the app developer uses the immutable, unique and non-guessable identifier it stored on the Emarsys CRM DB it got from its backend and uses the Emarsys SDK to call /apps/:appCode/client/contact with that identifier. The SDK stores the tokens. The SDK also sends the X-CLIENT-STATE it has and stores the newly returned X-CLIENT-STATE.

  6. If app developer decides to notify Emarsys of any event, the SDK queues it up to call the /events on a separate thread. Events are sent as an array of at least one event using X-CONTACT-TOKEN. The SDK also sends the X-CLIENT-STATE it has and stores the newly returned X-CLIENT-STATE.

App on the same version without any new push token is started a second time by a user

  1. Because nothing changed on the device properties, the Emarsys SDK does not call the /apps/:appCode/client/contact endpoint.

  2. No matter what the state of previous calls were, the Emarsys SDK automatically calls the /apps/:appCode/client/events endpoint with X-CONTACT-TOKEN and the internal session:start event without app developer input. The SDK also sends the X-CLIENT-STATE it has stores the newly returned X-CLIENT-STATE and a hash of what it sent to /apps/:appCode/client/contact.

  3. Once the app receives the push token, if it has not changed, the SDK does not call the /apps/:appCode/client/push_token endpoint.

  4. As the app user was already authentified, the app developer uses the immutable, unique and non-guessable identifier it stored on the Emarsys CRM DB it got from its backend and uses the Emarsys SDK to call /apps/:appCode/client/contact with that identifier. The SDK stores the returned tokens. The SDK also sends the X-CLIENT-STATE it has and stores the newly returned X-CLIENT-STATE.