徽标 Help Portal
  • 现在开始

    Introduction

    • Onboarding overview
    • Project Initiation
    • Email compliance
    • 帐户管理

    数据

    • Data Exchange
    • 数据登入
    • Web data collection
    • 整合

    Channels

    • Email onboarding
    • Smart Insight
    • Predict
  • 培训视频

    Resources

    • Introduction
    • Online Self-learning
    • Onboarding Videos

    Events

    • Instructor-led Training
    • Webinars
    • Seminars
    • Training Calendar
  • 用户指引

    策略

    • 个性化
    • 自动
    • Data Monitoring

    Channels

    • 电子邮件
    • 移动端 Apps
    • Web
    • Ads
    • SMS

    Add-ons

    • Smart Insight
    • Predict
    • 优惠信息推荐
    • AIM
    • Relational Data
  • 支持文档
    Forrester Wave CCCM (Independent Platforms) Report Q4 2019

    新消息

    • Emarsys 平台有哪些新增功能?
    • Updates from the CSA
    • 试验功能
    • 关于数据保护和 GDPR 的文章

    Support

    • 如何获得帮助?
    • 编辑用户配置
    • Preparing for Black Friday 2019
    • Black Friday 2019 - Best practices
  • |
  • Partners

    Enhance Partners

    • Getting Started as an Emarsys Partner
    • The Emarsys Integration Platform
    • Automation Center Integrations
  • 开发人员
  • 系统情况
需要协助?
简体中文 Deutsch English Español Français Русский Türkçe Test New Chat
登录
  • 移动端 Apps
  • Legacy Functionality - The Mobile Engage API
  • 0 移动端 Apps Legacy Functionality - The Mobile Engage API

In this section:

  • Mobile Engage API
EDIT
Expand all

Mobile Engage API

Updated: 2019年04月26日 08:32

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:

  • login
  • message open
  • custom event
  • logout

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:

1. Included the functionality of three endpoints into one endpoint

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.

2. Modified the data flow

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.

API Endpoints

The Mobile Engage API has four endpoints:

  1. Login endpoint
  2. Message open endpoint
  3. Custom event endpoint
  4. Logout endpoint

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.

 
这篇文章有帮助吗?

还有其它问题?提交请求
返回页首

Emarsys is a Leader

You may also be interested in:

相关文章

  • The Mobile Engage SDK
  • Overview:: Mobile Engage - Overview
  • End-user guides:: Mobile Engage - Advanced features
  • Introduction to the Emarsys API
  • The Emarsys Personalization Service
Copyright © 2019 Emarsys eMarketing Systems. All rights reserved
Legal Notice Privacy Policy Master Services Agreement Anti-spam Policy