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

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 an already 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:

Working with users who are not logged in

Make this call only if you would like to handle the users who are not logged in to your mobile app. 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”.

The push_token parameter in this case 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.

The following parameters are used here:

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.
hardware_id string The id of the hardware. 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 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 The push token does not exist for this contact or it has expired. The value should be “false”, which can be boolean or string.

Request example:

{
  "application_id": "29820-CA1E9",
  "hardware_id": "8E3FD635-7D9C-497E-AB84-1D61BED61F4B",
  "platform": "ios", // ios, android
  "language": "en", // ISO 639-1 2-character language code
  "timezone": "+0200", // https://www.ietf.org/rfc/rfc0822.txt
  "device_model": "iPhone7,1",
  "application_version": "10.1.2",
  "os_version": "9.2",
  "push_token": "false"
}

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.

Working with users who are logged in

This call should be made when the app is launched and the user is logged in. 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.
hardware_id string The id of the hardware. 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 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.

Request example:

{
  "application_id": "29820-CA1E9",
  "hardware_id": "8E3FD635-7D9C-497E-AB84-1D61BED61F4B",
  "contact_field_id": 158,
  "contact_field_value": "a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2",
  "platform": "ios", // ios, android
  "language": "en", // ISO 639-1 2-character language code
  "timezone": "+0200", // https://www.ietf.org/rfc/rfc0822.txt
  "device_model": "iPhone7,1",
  "application_version": "10.1.2",
  "os_version": "9.2",
  "push_token": "f2411061b5727f55c...362bee46dd840e5569891"
}

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.