The Mobile Engage API is a legacy product that does not support any of the new features, such as rich messaging or in-app messaging. Instead, we recommend that you incorporate the Mobile Engage SDK into your app.
Getting Started with the API
This article outlines the first steps of the integration of the Mobile Engage API.
1. Authentication
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.
2. HTTP communication
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.
3. Integration
Developers may call the following endpoints from anywhere in the app:
Functions related to application lifecycle activities are maintained within the AppDelegate.m(iOS) or MainActivity.java (Android) files.
Upgrading to v2 of the API
This section describes the process of upgrading to version 2 of the Mobile Engage API. We encourage all our customers to upgrade immediately. Not only is the new functionality only available in v2, but v1 will cease to be supported by the end of 2016. We have implemented changes in the following areas:
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_idis 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.
API Endpoints
The Mobile Engage API has four endpoints:
1. Login endpoint
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.
Endpoint URL
POST https://push.eservice.emarsys.net/api/mobileengage/v2/users/login
Description
The endpoint must be called whenever the app is brought to foreground, so that device-level and push token information can be kept up to date, and also when push notification is accepted. Calling the endpoint from a device with a known user re-associates the device with the new contact.
There are two main types of use for this endpoint, with differences in the data flow logic:
1.1. Working with users who are not logged in
A contact with minimal data is created and associated with the device. The contact fields Hardware ID, App installed, Last mobile activity will be populated for this contact. The response will contain the contact’s ID. At this point the user is “Anonymous”.
If the contact has disabled push notifications, the push_token parameter should have the value “false”. This can be of boolean or string type. If a push_token existed earlier in our database, it will be deleted. The reason why we should be notified about the lack or expiry of a push token is that if this does not happen, we will still send out the push messages, which will be stopped at the APNs or the GCMs, and this will cause serious distortion in the reporting.
Required parameters
| Name | Type | Description | Comments |
|---|---|---|---|
application_id |
string | The ID of the application. | This is generated by our delivery partner, upon adding your app to their service. For more information, see the Glossary. |
hardware_id |
string | The ID of the hardware. | A unique string to identify the device. For more information, see the Glossary. |
platform |
string | The platform used. | The possible values are “ios” and “android”. |
language |
string | The ISO 639-1 2-character language code. | |
timezone |
string | For more info, see: https://www.ietf.org/rfc/rfc0822.txt. | |
device_model |
string | The type of the mobile device used. | |
application_version |
string | The version of the application. | This should have the major/minor/patch version format (e.g.: 10 or 10.1 or 10.1.2). |
os_version |
string | The version of the operating system. | This should have the major/minor/patch version format (e.g.: 10 or 10.1 or 10.1.2). |
push_token |
boolean/string | If the contact is logged out, but push notifications are enabled for the contact associated with the hardware_id, the contact can be included in campaigns. |
The value can be boolean or string. |
Request example
Responses
| Status Code | Meaning |
|---|---|
| 202 | User data is successfully updated. |
| 400 | Wrong input or missing mandatory parameter. |
| 401 | Invalid HTTP basic Authentication. |
| 500 | Internal server error. |
1.2. Working with users who are logged in
This call should be made when the app is launched and the user is logged in, and when an anonymous contact registers. In this case we know who the user is, and we are waiting for acceptance of push messages. If the contact decides not to accept push messages, the value of the push_token is “false”. If the messages are accepted, the push_token should be added to the call.
Although in the absence of a push token, push notifications cannot be sent out, there is still a way to engage the contacts by other means (e.g. an email asking for opting in for push). The two parameters used for this are contact_field_id and contact_field_value, which identify the contacts in the Emarsys database and provide other ways of reaching out for them.
Required parameters
| Name | Type | Description |
Comments |
|---|---|---|---|
application_id |
string | The id of the application. | This is generated by our delivery partner, upon adding your app to their service. For more information, see the Glossary. |
hardware_id |
string | The id of the hardware. | A unique string to identify the device. For more information, see the Glossary. |
platform |
string | The platform used. | The possible values are “ios” and “android”. |
contact_field_id |
integer | The id of the contact field. | The Mobile Engage service can use this to look up an Emarsys contact and associate it with a specific device. |
contact_field_value |
string | The value of the contact field. | In the request example below, the value of this key is the hashed version of the customer’s internal ID. |
language |
string | The ISO 639-1 2-character language code. | |
timezone |
string | For more info, see: https://www.ietf.org/rfc/rfc0822.txt. | |
device_model |
string | The type of the mobile device used. | |
application_version |
string | The version of the application. | This should have the major/minor/patch version format (e.g.: 10 or 10.1 or 10.1.2). |
os_version |
string | The version of the operating system. | This should have the major/minor/patch version format (e.g.: 10 or 10.1 or 10.1.2). |
push_token |
boolean/string | This is the push token obtained from the delivery partner. If it does not exist for this contact or it has expired, the value should be “false”. |
The value “false” can be boolean or string. For more information, see the Glossary. |
Request example
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.
2. Message open endpoint
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.
Endpoint URL
POST https://push.eservice.emarsys.net/api/mobileengage/v2/events/message_open
Description
The developer should call this endpoint where an incoming push message is handled. The developer should retrieve custom data from the payload. It should be included in the call to Mobile Engage.
Required parameters
| Name | Type | Description | Comments |
|---|---|---|---|
application_id |
string | The ID of the application. | This is generated by our delivery partner, upon adding your app to their service. For more information, see the Glossary. |
hardware_id |
string | The ID of the hardware. | A unique string to identify the device. For more information, see the Glossary. |
sid |
string | The string ID of the push message. | For more information, see the Glossary. |
Request example
Responses
| Status Code | Meaning |
|---|---|
| 201 | Created. |
| 500 | Database error (everything else). |
Calling this from iOS
Calling this from Android
3. Custom event endpoint
Custom events are application behavior events you want to know about, collect and store, so that you can create segments based on them later.
Endpoint URL
POST https://push.eservice.emarsys.net/api/mobileengage/v2/events/<name>
Description
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.
Request example
Calling this from iOS
Calling this from Android
4. Logout endpoint
This endpoint must be called when an Emarsys contact logs out of the application.
Endpoint URL
POST https://push.eservice.emarsys.net/api/mobileengage/v2/users/logout
Description
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
| Status Code | Meaning |
|---|---|
| 202 | Accepted. |
| 409 | Hardware ID already exists. |
| 500 | Database error (everything else). |
Calling this from iOS
API use cases
The most common use cases for this API are the following:
1. Opt-in to push messages
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 anonymous 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.
2. Check message open reporting
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.