API 使用入门
本文简要介绍了 Mobile Engage API 解析的最初几个步骤。
1.身份验证
Mobile Engage API 使用 HTTP 基本身份验证对请求进行身份验证。用户名和密码由 Emarsys 提供。用户名为 application_code，密码则在 Mobile Engage 注册流程中生成。
2.HTTP 通信
移动应用程序开发人员应使用移动网络连接最佳实践来调用 Mobile Engage API。对于 iOS 和 Android，应以异步方式处理网络连接，以免阻碍或降低应用程序或操作系统的性能。
iOS 开发人员可以选择使用本地 NSURLSession 类来发出 HTTP 请求，或者使用另一个 HTTP 客户端。
Android 开发人员可以选择使用 Google 的首选 AsyncTask 方法来进行后台网络操作。
3.集成
开发人员可以从应用程序中的任何位置调用以下端点：
与应用程序生命周期活动相关的功能在 AppDelegate.m(iOS) 或 MainActivity.java (Android) 文件内进行维护。
升级到 API 版本 2
本节介绍了升级到 Mobile Engage API 版本 2 的流程。我们建议所有客户立即进行升级。我们不仅将在版本 2 中提供独特的新功能，还将于 2016 年年底停止对版本 1 提供支持。我们在以下方面实施了更改：
1.将三个端点的功能添加到了一个端点中
我们已将 app_launch、contact_update 和 push_accepted 这三个早期端点的功能添加到了新的 login 端点中。
login 端点可提供之前端点的所有功能：它可以应对应用程序启动、注册流程，以及联系人同意接收推送通知的事件。
对于已实施我们较早版本的 API 端点的用户来说，只需将应用程序中的三个端点替换为新的 login 端点。
有关更多信息，请参见 Login 端点说明。
2.修改了数据流
在我们的新数据流模式中，应用程序始终与设备和平台相关联。与之前模式的区别在于对应用程序用户的处理方式。
当应用程序已启动，但用户未登录且没有推送令牌时，系统将调用 login 端点，但没有个人标识符数据。在这些情况下，必须确定是否存与设备关联的联系人。
- 如果有，则其
contact_id与设备关联。 - 如果没有，则会关联 Mobile Engage Created (MEC) 联系人。其他识别方式（如电子邮件地址）尚未知。
如果存在登录事件，则会使用个人标识符数据（如电子邮件地址）再次调用 login 端点。如果还向发送的数据添加了推送令牌，则可以向客户端发送推送通知。
当由于退出事件而调用 logout 端点时，MEC 联系人会再次与设备关联。
有关更多信息，请参见数据流模式说明。
API 端点
1.Login 端点
调用 login 端点可将 Mobile Engage 设备与 Emarsys 联系人相关联，从而更新关于用户的设备级信息，并更新推送令牌。
端点 URL
POST https://push.eservice.emarsys.net/api/mobileengage/v2/users/login
描述
每当应用程序转至前台时，都必须调用该端点，从而使设备级信息和推送令牌信息保持最新状态；在接受推送通知时也必须调用该端点。通过已知用户从设备调用端点时，会将设备重新与新联系人相关联。
此端点有两种主要用途，它们具有不同的数据流逻辑：
1.1.处理未登录的用户
只有在您希望处理未登录您的移动应用程序的用户时，才需进行此调用。系统会创建一个具有极少数据的联系人，并将其与设备相关联。将为此联系人填充硬件 ID、已安装的应用程序、上次移动端活动等联系人字段。响应信息将包含联系人的 ID。此时，用户为 Anonymous。
在本例中，push_token 参数的值应为 false。该值可以是布尔值或字符串类型。如果我们的数据库中之前存在 push_token，则会将其删除。在缺乏推送令牌或令牌过期时，我们应该收到通知，因为如果未收到通知，我们仍将发送推送信息，这将停止于 APN 或 GCM，进而导致报告严重失实。
所需参数
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
application_id | 字符串 | 应用程序 ID。 | 该 ID 在交付合作伙伴将您的应用程序添加到其服务中时生成。有关更多信息，请参见术语表。 |
hardware_id | 字符串 | 硬件 ID。 | 用于标识设备的唯一字符串。有关更多信息，请参见术语表。 |
platform | 字符串 | 使用的平台。 | 可能的值为 ios 和 android。 |
language | 字符串 | ISO 639-1 2 字符语言代码。 | |
timezone | 字符串 | 有关更多信息，请参见：https://www.ietf.org/rfc/rfc0822.txt。 | |
device_model | 字符串 | 使用的移动设备的类型。 | |
application_version | 字符串 | 应用程序的版本。 | 此参数应采用主要/次要/修补程序版本格式（例如：10、10.1 或 10.1.2）。 |
os_version | 字符串 | 操作系统的版本。 | 此参数应采用主要/次要/修补程序版本格式（例如：10、10.1 或 10.1.2）。 |
push_token | 布尔值/字符串 | 在本例中，不存在此联系人的推送令牌，或令牌已过期。 | 值应为 false，可以是布尔值或字符串。 |
请求示例
响应
| 状态代码 | 含义 |
|---|---|
| 202 | 用户数据已成功更新。 |
| 400 | 输入错误或缺少必需参数。 |
| 401 | HTTP 基本身份验证无效。 |
| 500 | 内部服务器错误。 |
1.2.处理已登录的用户
当应用程序已启动且用户已登录时，应进行此调用。在本例中，我们知道用户是谁，并且正在等待其接受推送信息。如果联系人决定不接受推送信息，则 push_token 的值为 false。如果接受信息，则应向调用中添加 push_token。
尽管缺乏推送令牌，无法发送推送通知，但仍可以通过其他方式来契合联系人（例如，请求选择推送的电子邮件）。此调用使用的两个参数为 contact_field_id 和 contact_field_value，它们用于标识 Emarsys 数据库中的联系人，并提供其他方式来与其联系。
所需参数
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
application_id | 字符串 | 应用程序 ID。 | 该 ID 在交付合作伙伴将您的应用程序添加到其服务中时生成。有关更多信息，请参见术语表。 |
hardware_id | 字符串 | 硬件 ID。 | 用于标识设备的唯一字符串。有关更多信息，请参见术语表。 |
platform | 字符串 | 使用的平台。 | 可能的值为 ios 和 android。 |
contact_field_id | 整数 | 联系人字段的 ID。 | Mobile Engage 服务可以使用此参数来查找 Emarsys 联系人，并将其与特定设备相关联。 |
contact_field_value | 字符串 | 联系人字段的值。 | 在下面的请求示例中，这个键的值为客户内部 ID 的哈希形式。 |
language | 字符串 | ISO 639-1 2 字符语言代码。 | |
timezone | 字符串 | 有关更多信息，请参见：https://www.ietf.org/rfc/rfc0822.txt。 | |
device_model | 字符串 | 使用的移动设备的类型。 | |
application_version | 字符串 | 应用程序的版本。 | 此参数应采用主要/次要/修补程序版本格式（例如：10、10.1 或 10.1.2）。 |
os_version | 字符串 | 操作系统的版本。 | 此参数应采用主要/次要/修补程序版本格式（例如：10、10.1 或 10.1.2）。 |
push_token | 布尔值/字符串 | 这是从交付合作伙伴那里获取的推送令牌。如果此联系人没有该令牌或令牌已过期，则值应为 false。 | 值 false 可以是布尔值或字符串。有关更多信息，请参见术语表。 |
请求示例
通过此调用，将通过一个有效推送令牌共同标识联系人、硬件和应用程序，从而可以发送完全个性化的推送信息。
2.Message open 端点
当移动设备直接从推送信息通知中打开应用程序时，将调用此端点。这一途径将为 Emarsys 提供联系人级别的信息打开率统计数据。
端点 URL
POST https://push.eservice.emarsys.net/api/mobileengage/v2/events/message_open
描述
开发人员应调用此端点，传入的推送信息会在其中进行处理。开发人员应从有效负载中检索自定义数据。它应包含在对 Mobile Engage 的调用中。
所需参数
| 名称 | 类型 | 描述 | 备注 |
|---|---|---|---|
application_id | 字符串 | 应用程序 ID。 | 该 ID 在交付合作伙伴将您的应用程序添加到其服务中时生成。有关更多信息，请参见术语表。 |
hardware_id | 字符串 | 硬件 ID。 | 用于标识设备的唯一字符串。有关更多信息，请参见术语表。 |
sid | 字符串 | 推送信息的字符串 ID。 | 有关更多信息，请参见术语表。 |
请求示例
响应
| 状态代码 | 含义 |
|---|---|
| 201 | 已创建。 |
| 500 | 数据库错误（其他一切）。 |
从 iOS 调用此端点
从 Android 调用此端点
3.Custom event 端点
自定义事件是您需要了解、收集和存储的应用程序行为事件，以便您稍后根据它们创建群组。
端点 URL
POST https://push.eservice.emarsys.net/api/mobileengage/v2/events/<name>
描述
您必须指定自定义事件的名称，并将其发送到 Mobile Engage，我们将存储发送事件的设备和应用程序及时间，这些信息稍后将用于进行筛选。
有关基于自定义事件进行筛选的更多信息，请参见 Mobile Engage 筛选。
如果您希望随事件发送属性，请联系 Emarsys 支持团队。
请求示例
从 iOS 调用此端点
从 Android 调用此端点
4.Logout 端点
当 Emarsys 联系人退出应用程序时，应调用此端点。
端点 URL
POST https://push.eservice.emarsys.net/api/mobileengage/v2/users/logout
描述
调用此端点可移除 Mobile Engage 设备与 Emarsys 联系人之间的关联，并且无法再向联系人发送推送信息。push_accepted 联系人字段的值在 1 到空之间变化。这不会创建匿名用户。
请求示例
响应
| 状态代码 | 含义 |
|---|---|
| 202 | 已接受。 |
| 409 | 硬件 ID 已存在。 |
| 500 | 数据库错误（其他一切）。 |
从 iOS 调用此端点
API 用例
此 API 的最常见用例包括：
2.查看信息打开报告
为了了解有多少用户打开了您的信息，您必须向 message_open 端点发送 message_open 事件。将 sid 参数与 application_id 和 hardware_id 一起添加到调用中，Mobile Engage 将了解各 Emarsys 联系人分别读取了哪些信息。