The Mobile Engage API uses HTTP basic authentication to authenticate the requests. The username and the password are provided by Emarsys. The username is the application_code and the password is generated during the Mobile Engage Onboarding process.

Mobile app developers should call the Mobile Engage API using mobile networking best practices. For both iOS and Android, network connections should be handled asynchronously, so as not to block or reduce the performance of the application or the operating system.

iOS developers may choose to use the native NSURLSession class for making HTTP requests or another HTTP client.

Android developers may choose to use Google’s preferred AsyncTask method for background network operations.

Developers may call the following endpoints from anywhere in the app:

• login
• message open
• custom event
• logout

Functions related to application lifecycle activities are maintained within the AppDelegate.m(iOS) or MainActivity.java (Android) files.

We have included the functionality of three earlier endpoints -  app_launch,  contact_update and push_accepted - into the new login endpoint.

The login endpoint offers the full functionality of the previous endpoints: it can handle the application launch, the registration process as well as the event where contacts agree to receive push notifications.

For those of you who have have implemented the earlier versions of our API endpoints, the task is simply to replace the three endpoints in the app with the new login endpoint.

For more information, see the description of the Login endpoint.

In our new data flow model, the app is always linked to the device and the platform. The difference from the earlier model is the way the users of the app are handled.

When an app is launched without a logged-in user and a push token, the login endpoint is called, but without the personal identifier data. In these cases it has to be determined if there is a contact associated with the device.

• If yes, its contact_id is associated with the device.
• If not, a Mobile Engage Created (MEC) contact is linked. Other identification means, such as the email address, are not known.

If there is a login event, the login endpoint is called again, with the personal identifier data, such as an email address. If there is a push token added to the data sent as well, push notifications can be sent to the client.

When the logout endpoint is called due to a logout event, the MEC contact is again associated to the device.

For more information, see the description of our data flow model.

The login endpoint is called to associate the Mobile Engage device with the Emarsys contact, to update the device-level information about the user, and to update the push token.

With this call the contact, the hardware and the app are identified, together with a valid push token, and therefore fully personalized push messages can be sent out.

This endpoint is called when the mobile device opens the app directly from a push message notification. This route will provide Emarsys with contact-level message open rate statistics.

Custom events are application behavior events you want to know about, collect and store, so that you can create segments based on them later.

You have to specify the name of the custom event and send it to Mobile Engage – we will store which device and app the event was sent from and when – and this will be available for segmentation later.

For more information on segmentation based on custom events, see Mobile Engage Segmentation.

If you wish to send attributes with the event, please contact Emarsys Support.

Request example

Calling this from iOS

Calling this from Android

This endpoint should be called when an Emarsys contact logs out of the application.

Calling this endpoint removes the association between the Mobile Engage device and the Emarsys contact and the contact is no longer reachable via push messages. The value of the push_accepted contact field changes from 1 to  empty. This DOES NOT create an anonymous user.

Request example

Responses

Calling this from iOS

To send a push message, the app user needs to enable (accept) push messages, and we need their permission to do that. The large platforms (iOS and Android) are pushing the developers to request permissions at a point where the benefit of giving this permission is most clear for the user. You should also ask for push permission at such a point. If the permission is granted, call the login endpoint with the push_token.

Start your application with the login event, to register the device and the app being used in the Mobile Engage database.

After the first Mobile Engage contact gets the push_token, you can create a segment in the Emarsys platform, using the <App name> Push accepted custom field that is created for you during the onboarding process.

In order to learn how many users opened your message, you have to send the message_open event to the message_open endpoint. Include the sid parameter in the call along with the application_id and hardware_id, and Mobile Engage will know which message was read by which Emarsys contact.