Amazon SDK 设置

概述

本指南解释了如何将 OneSignal 推送通知集成到 Amazon Fire OS 应用中。它涵盖了从安装到配置和服务工作程序管理的所有内容。

要求

您的应用必须在 Amazon AppStore 上分发
Android 7.0+ 设备或模拟器
已配置的 OneSignal 应用和平台

配置您的 OneSignal 应用和平台

使用您支持的平台配置您的 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。

如果您的组织已有 OneSignal 账户，请申请加入组织。否则，请注册免费账户以开始使用。

分步设置说明

创建或选择您的应用

点击 新应用/网站 创建新应用，或在 设置 > 推送和应用内 中向现有应用添加平台。选择您要配置的平台，然后点击 下一步：配置您的平台。

配置平台凭据

为您的平台输入凭据：

输入您的凭据后点击 保存并继续。

保存您的应用 ID 并安装 SDK

您的 应用 ID 显示在最终屏幕上。复制并保存它——初始化 SDK 时需要使用它。选择您的 SDK 平台，然后按照设置指南操作。

设置

更新 `AndroidManifest.xml`

打开您的 AndroidManifest.xml 文件，在 xmlns:android 属性后的 manifest 标签中添加 xmlns:amazon="http://schemas.amazon.com/apk/res/android"。

xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:amazon="http://schemas.amazon.com/apk/res/android"
    package="com.onesignal.example"
    android:versionCode="1"
    android:versionName="1.0" >

添加以下权限，将 COM.YOUR.PACKAGE_NAME 替换为您的实际包名：

xml

<uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />
<permission
  android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE"
  android:protectionLevel="signature"
/>
<uses-permission android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" />

在 <application> 标签中配置 ADM 服务和接收器，将 COM.YOUR.PACKAGE_NAME 替换为您的实际包名：

xml

<application ....>
  <amazon:enable-feature android:name="com.amazon.device.messaging"
                         android:required="false"/>
  <service android:name="com.onesignal.notifications.services.ADMMessageHandler"
           android:exported="false" />
  <service android:name="com.onesignal.notifications.services.ADMMessageHandlerJob"
           android:permission="android.permission.BIND_JOB_SERVICE"
           android:exported="false" />
  <receiver android:name="com.onesignal.notifications.receivers.ADMMessageReceiver"
           android:permission="com.amazon.device.messaging.permission.SEND"
            android:exported="true" >
    <intent-filter>
      <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
      <action android:name="com.amazon.device.messaging.intent.RECEIVE" />
      <category android:name="COM.YOUR.PACKAGE_NAME" />
    </intent-filter>
  </receiver>

</application>

Amazon API 密钥文件配置

将您的 api_key.txt 放在 Android 项目根目录的 assets 文件夹中。

要为您的应用创建 api_key.txt，请按照我们的生成 Amazon API 密钥指南。在构建 APK 时，请确保使用与 Amazon 配置指南中步骤 2.4 相同的密钥库。在测试 Amazon 推送通知时，请确保您没有构建 debug 应用。它必须是 release 类型。将签名的 APK 提交到实时应用测试。提交签名的 APK 是 ADM 正常工作的必要要求。

测试 OneSignal SDK 集成

本指南帮助您通过测试推送通知、订阅注册和应用内消息来验证 OneSignal SDK 集成是否正常工作。

检查移动端订阅

在测试设备上启动您的应用。

如果您在初始化时添加了 requestPermission 方法，原生推送权限提示应该会自动出现。

检查您的 OneSignal 控制台

在接受提示之前，请检查 OneSignal 控制台：

转到 受众 > 订阅。
您应该看到一个状态为”从未订阅”的新条目。

返回应用并在提示中点击允许。

刷新 OneSignal 控制台的订阅页面。

订阅状态现在应该显示为已订阅。

您已成功创建了移动端订阅。移动端订阅是在用户首次在设备上打开您的应用时创建的，或者在同一设备上卸载并重新安装您的应用时创建的。

设置测试订阅

测试订阅有助于在发送消息之前测试推送通知。

添加到测试订阅。

在控制台中，在订阅旁边，点击选项（三个点）按钮并选择添加到测试订阅。

为您的订阅命名。

为订阅命名，以便您稍后能够在测试订阅标签中轻松识别您的设备。

创建测试用户分组。

转到 受众 > 分组 > 新建分组。

为分组命名。

将分组命名为 Test Users（名称很重要，因为稍后会使用到）。

添加测试用户过滤器并点击创建分组。

您已成功创建了测试用户分组。现在我们可以测试向这个单独的设备和测试用户组发送消息。

通过 API 发送测试推送

获取您的应用 API 密钥和应用 ID。

在您的 OneSignal 控制台中，转到 设置 > 密钥和 ID。

更新提供的代码。

将下面代码中的 YOUR_APP_API_KEY 和 YOUR_APP_ID 替换为您的实际密钥。此代码使用我们之前创建的 Test Users 分组。

curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "ios_attachments": {
    "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  },
  "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

运行代码。

在您的终端中运行代码。

检查图片和确认送达。

如果所有设置步骤都成功完成，测试订阅应该会收到包含图片的通知：

图片在折叠的通知视图中会显得很小。展开通知以查看完整图片。

检查确认送达。

在您的控制台中，转到 送达 > 已发送消息，然后点击消息查看统计数据。您应该会看到已确认统计，表示设备收到了推送。

您已成功通过我们的 API 向分组发送了通知。

没有收到图片？您的通知服务扩展可能缺失。
没有确认送达？请检查您的应用组设置。
遇到问题？将 API 请求和应用启动从开始到结束的日志复制粘贴到 .txt 文件中。然后将两者都发送给 support@onesignal.com。

发送应用内消息

应用内消息让您可以在用户使用您的应用时与他们进行沟通。

在设备上关闭或将您的应用切换到后台。

这是因为用户必须在新会话开始_之前_满足应用内受众条件。在 OneSignal 中，当用户在应用处于后台或关闭至少 30 秒后重新打开应用时，会开始一个新会话。更多详情，请参阅我们的应用内消息如何显示指南。

创建应用内消息。

在您的 OneSignal 控制台中，导航到 消息 > 应用内 > 新建应用内消息。
找到并选择欢迎消息。
将您的受众设置为我们之前使用的 Test Users 分组。

如需要，请自定义消息内容。

将触发器设置为 '应用打开时'。

安排频率。

在 安排 > 您希望多久显示一次此消息？ 下选择 每次触发条件满足时。

使消息生效。

点击 使消息生效，这样每次测试用户打开应用时都可以使用该消息。

打开应用并查看消息。

应用内消息生效后，打开您的应用。您应该会看到它显示：

没有看到消息？

开始新会话
- 您必须关闭或将应用切换到后台至少 30 秒后再重新打开。这可以确保开始新会话。
- 更多信息，请参阅应用内消息如何显示。
仍在 Test Users 分组中？
- 如果您重新安装或更换了设备，请重新将设备添加到测试订阅并确认它是 Test Users 分组的一部分。
遇到问题？
- 在重现上述步骤时，请遵循获取调试日志。这将生成额外的日志，您可以与 support@onesignal.com 分享，我们将帮助调查正在发生的情况。

您已成功设置 OneSignal SDK 并学习了重要概念，如：

收集订阅，设置测试订阅，以及创建分组。
使用分组和我们的创建消息 API 发送带图片的推送和确认送达。
发送应用内消息。

继续阅读本指南以在您的应用中识别用户并设置其他功能。

用户识别

之前，我们演示了如何创建移动端订阅。现在我们将扩展到使用 OneSignal SDK 在所有订阅（包括推送、电子邮件和短信）中识别用户。我们将涵盖外部 ID、标签、多渠道订阅、隐私和事件跟踪，以帮助您统一用户并跨平台与他们互动。

分配外部 ID

使用外部 ID 通过您后端的用户标识符在设备、电子邮件地址和电话号码之间一致地识别用户。这确保您的消息传递在各个渠道和第三方系统中保持统一（对集成特别重要）。每次您的应用识别用户时，使用我们 SDK 的login 方法设置外部 ID。

OneSignal 为订阅（订阅 ID）和用户（OneSignal ID）生成唯一的只读 ID。当用户在不同设备上下载您的应用、订阅您的网站，和/或在您的应用之外提供电子邮件地址和电话号码时，将创建新的订阅。强烈建议通过我们的 SDK 设置外部 ID，以在用户的所有订阅中识别用户，无论订阅是如何创建的。

添加数据标签

标签是字符串数据的键值对，您可以使用它们来存储用户属性（如 username、role 或偏好）和事件（如 purchase_date、game_level 或用户交互）。标签支持高级消息个性化和分组，允许更高级的用例。在您的应用中发生事件时，使用我们 SDK 的addTag 和 addTags 方法设置标签。在这个示例中，用户达到了第 6 级，可以通过名为 current_level 的标签识别，其值设置为 6。

我们可以创建一个等级在 5 到 10 之间的用户分组，并使用它来发送有针对性的个性化消息：

添加电子邮件和/或短信订阅

之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。

使用addEmail 方法创建电子邮件订阅。
使用addSms 方法创建短信订阅。

如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 会将其添加到现有用户，不会创建重复项。您可以通过控制台中的 受众 > 用户 或使用查看用户 API查看统一的用户。

多渠道沟通的最佳实践

在添加电子邮件或短信订阅之前获得明确同意。
向用户解释每个沟通渠道的好处。
提供渠道偏好，让用户可以选择他们偏好的渠道。

隐私和用户同意

要控制 OneSignal 何时收集用户数据，请使用 SDK 的同意管控方法：

setConsentRequired(true)：阻止数据收集直到获得同意。
setConsentGiven(true)：一旦获得同意即启用数据收集。

有关更多信息，请参阅我们的隐私和安全文档：

提示推送权限

不要在应用打开时立即调用 requestPermission()，而是采取更策略性的方法。在请求权限之前，使用应用内消息解释推送通知的价值。有关最佳实践和实现细节，请参阅我们的提示推送权限指南。

监听推送、用户和应用内事件

使用 SDK 监听器来响应用户操作和状态变化。 SDK 提供了几个事件监听器供您使用。更多详情请参阅我们的SDK 参考指南。

推送通知事件

addClickListener()：检测通知被点击时。对深度链接有帮助。
addForegroundLifecycleListener()：控制通知在前台的行为方式。

要进行完全自定义，请参阅移动端服务扩展。

用户状态变化

addObserver() 用于用户状态：检测外部 ID 设置时。
addPermissionObserver()：跟踪用户与原生推送权限提示的特定交互。
addObserver() 用于推送订阅：跟踪推送订阅状态变化时。

应用内消息事件

addClickListener()：处理应用内点击操作。适用于深度链接或跟踪事件。
addLifecycleListener()：跟踪应用内消息的完整生命周期（显示、点击、关闭等）。

高级设置和功能

探索更多功能以增强您的集成：

移动端 SDK 设置和参考

通过查看移动端推送设置指南，确保您已启用所有关键功能。有关可用方法和配置选项的完整详细信息，请访问移动端 SDK 参考。

恭喜！您已成功完成移动端 SDK 设置指南。

需要帮助？与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息：

您遇到的问题详情以及复现步骤（如有）
您的 OneSignal 应用 ID
外部 ID 或订阅 ID（如适用）
您在 OneSignal 控制台中测试的消息 URL（如适用）
任何相关的日志或错误信息

我们很乐意为您提供帮助！

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

概述

要求

配置您的 OneSignal 应用和平台

设置

更新 `AndroidManifest.xml`

Amazon API 密钥文件配置

测试 OneSignal SDK 集成

检查移动端订阅

设置测试订阅

通过 API 发送测试推送

发送应用内消息

用户识别

分配外部 ID

添加数据标签

添加电子邮件和/或短信订阅

隐私和用户同意

提示推送权限

监听推送、用户和应用内事件

推送通知事件

用户状态变化

应用内消息事件

高级设置和功能

移动端 SDK 设置和参考

​概述

​要求

​配置您的 OneSignal 应用和平台

​设置

​更新 AndroidManifest.xml

​Amazon API 密钥文件配置

​测试 OneSignal SDK 集成

​检查移动端订阅

​设置测试订阅

​通过 API 发送测试推送

​发送应用内消息

​用户识别

​分配外部 ID

​添加数据标签

​添加电子邮件和/或短信订阅

​隐私和用户同意

​提示推送权限

​监听推送、用户和应用内事件

​推送通知事件

​用户状态变化

​应用内消息事件

​高级设置和功能

​移动端 SDK 设置和参考

概述

要求

配置您的 OneSignal 应用和平台

设置

更新 `AndroidManifest.xml`

Amazon API 密钥文件配置

测试 OneSignal SDK 集成

检查移动端订阅

设置测试订阅

通过 API 发送测试推送

发送应用内消息

用户识别

分配外部 ID

添加数据标签

添加电子邮件和/或短信订阅

隐私和用户同意

提示推送权限

监听推送、用户和应用内事件

推送通知事件

用户状态变化

应用内消息事件

高级设置和功能

移动端 SDK 设置和参考