跳转到主要内容

​
概述

本指南说明如何将 OneSignal 推送通知集成到在华为应用市场分发的华为应用中。 这些说明适用于使用 Java 或 Kotlin 编写的原生应用。有关其他支持的 SDK，请参见：

Ionic/Cordova/Capacitor

Flutter

React Native

Unity

​
要求

  • Android Studio
  • 安装了”华为应用市场”的华为设备
  • 已配置的 OneSignal 应用和平台

​
配置您的 OneSignal 应用和平台

推送通知所需设置 要开始使用 OneSignal 发送推送通知，您必须首先为您支持的所有平台配置 OneSignal 应用——Apple (APNs)、Google (FCM)、华为 (HMS) 和/或 Amazon (ADM)。
如果您的组织已有 OneSignal 账户，请要求邀请您为管理员角色以配置应用。否则，请注册免费账户以开始使用。
您可以在单个 OneSignal 应用下管理多个平台（iOS、Android、华为、Amazon、Web）。
1

创建或选择您的应用

  • 要向现有应用添加平台，请在 OneSignal 控制台中转到 设置 > 推送和应用内。
  • 要重新开始，请点击 新应用/网站 并按照提示操作。

示例显示创建新应用。

2

设置并激活平台

  • 为您的应用和组织选择一个清晰且易识别的名称。
  • 选择您要配置的平台（iOS、Android 等）。
  • 点击 下一步：配置您的平台。

设置首个 OneSignal 应用、组织和频道的示例。

3

配置平台凭据

根据您的平台按照提示操作：输入您的凭据后点击 保存并继续。
4

选择目标 SDK

选择与您的开发平台匹配的 SDK（例如，iOS、Android、React Native、Unity），然后点击 保存并继续。

选择您正在使用的 SDK 以导航到文档。

5

安装 SDK 并保存您的应用 ID

配置好您的平台后，将显示您的 OneSignal 应用 ID。复制并保存此 ID——在安装和初始化 SDK 时您将需要它。如果与他人协作，请使用 邀请 按钮添加开发人员或团队成员，然后点击 完成 以完成设置。

保存您的应用 ID 并邀请其他团队成员。

完成后，请遵循您所选平台的 SDK 安装指南以完成 OneSignal 集成。

​
设置

​
1. 设置 OneSignal SDK

OneSignal Android SDK 设置

按照 OneSignal Android SDK 设置指南将我们的 SDK 实现到您的应用中。 请注意，发布到华为应用市场的应用构建不需要 Firebase/Google 设置。

​
2. 华为配置 (agconnect-services.json)

如果您的 Android Studio 项目中已经有来自设置其他华为服务的华为 agconnect-services.json，则可以跳过此步骤。
在 AppGallery Connect 项目列表 中选择您的应用。 点击”agconnect-services.json”按钮下载此文件。
将此文件放置在 Android Studio 的应用目录中。

​
3. 生成签名证书指纹

如果您已经为其他华为服务将 SHA-256 证书指纹添加到华为的控制台，则可以跳过此步骤。
在您的 Android Studio 中，转到 View > Tool Windows > Gradle。
在这里选择 app > Tasks > android > signingReport。
复制您的 release 变体的 SHA-256。
  • 可选但建议为您的 debug 变体的 SHA-256 也复制，以便更快地进行测试。
  • 您的项目中可能还有其他自定义变体，如果您需要对它们的推送支持，也请复制这些。
在 AppGallery Connect 项目列表 中选择您的应用。 滚动到底部找到”SHA-256 证书指纹”字段，您应该在其中输入您的密钥。

​
4. 添加华为 gradle 插件和依赖项

在 Android Studio 中打开您的根 build.gradle（项目：），并在 buildscript { repositories } 和 allprojects { repositories } 下添加 maven {url 'https://developer.huawei.com/repo/'} 在 buildscript { dependencies } 下添加 classpath 'com.huawei.agconnect:agcp:1.6.5.300' 您的根 build.gradle 中总共应该有 3 行新内容，如下所示。
打开您的 app/build.gradle 文件，并在 dependencies 部分下添加 implementation 'com.huawei.hms:push:6.3.0.304'。 同样在 app/build.gradle 文件中，在文件的最底部添加 apply plugin: 'com.huawei.agconnect'。 您的 app/build.gradle 中总共应该有 2 行新内容，如下所示。
确保在保存后点击弹出横幅上的”立即同步”！

​
其他配置步骤

​
与其他 HMS 推送库或您自己的 HmsMessageService 类的兼容性

需要时：
  • 除了 OneSignal 之外，您的应用中还有另一个 HMS 推送 SDK/库
  • 您有自己的 HmsMessageService
创建一个继承自 HmsMessageService 的类（如果您还没有的话），并添加以下方法。
如果您已经有一个继承自 HmsMessageService 的类，请添加两行新的 OneSignalHmsEventBridge 代码，而不是创建另一个类。
Java
public class YourHmsMessageService extends HmsMessageService {
  public void onNewToken(String token) {
      // ...
      // Forward event on to OneSignal SDK
      OneSignalHmsEventBridge.onNewToken(this, token);
  }

  @Override
  public void onMessageReceived(RemoteMessage message) {
      // ...
      // Forward event on to OneSignal SDK
      OneSignalHmsEventBridge.onMessageReceived(this, message);
  }
}
这是为了通过 OneSignalHmsEventBridge 将 onNewToken 和 onMessageReceived 转发给 OneSignal。如果您之前没有继承自 HmsMessageService 的类，请确保将其添加到 <application> 标签下的 AndroidManifest.xml 中。
AndroidManifest.xml
<application>
    ...

    <!--
      Ensure you only have one intent-filter for "com.huawei.push.action.MESSAGING_EVENT".
      HMS only supports one per app.
    -->
    <service
        android:name=".YourHmsMessageService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.huawei.push.action.MESSAGING_EVENT" />
        </intent-filter>
    </service>

    ...
</application>

​
为华为应用市场构建省略 Google 库（可选）

  • 选项 1
  • 选项 2
如果您的应用仅在华为应用市场上可用，并且您希望省略 OneSignal 包含的任何 Google 相关依赖项，您可以在 app/build.gradle 中使用 implementation 的 exclude。
implementation('com.onesignal:OneSignal:[5.0.0-beta, 5.99.99]') {
    exclude group: 'com.google.android.gms'
    exclude group: 'com.google.firebase'
}

​
首选 HMS 而不是 FCM（可选）

如果您在上面的华为应用市场构建中已经省略了 Google 库，则此步骤不适用。默认情况下，如果您的应用中包含 FCM 和 HMS，OneSignal 更倾向于使用 FCM。如果您希望将其更改为首选 HMS，可以将以下内容添加到您的 AndroidManifest.xml 中：
<application>
        ...
        <meta-data android:name="com.onesignal.preferHMS" android:value="true"/>
        ...
 </application>

​
华为故障排除

在测试时，确保将 OneSignal setLogLevel 方法 设置为 VERBOSE。 检查日志以查看抛出的任何错误和 华为通用错误代码。
您可能需要创建调试或发布密钥库签名（选择正确的应用构建路径，debug 或 release），以便在使用 OneSignal SDK 注册华为 pushToken 时避免 6003 错误。请参见 “配置签名” 部分
"notification_types":-25 意味着 OneSignal 在等待华为 HMS 响应以获取推送令牌时超时。这很可能是由于另一个第三方 HMS 推送 SDK 或您自己的 HmsMessageService 获取了此事件而不是 OneSignal。请查看 有关如何检查此情况并在此情况下转发事件的步骤。
这意味着应用中缺少推送所需的 HMS 类。只要在 build.gradle 中有 com.huawei.hms:push，就不会再发生这个特定错误。但是，如果您有一些激进的 Proguard 或 R8 设置，这可能会导致问题。如果您有的话，我们建议暂时关闭 minifyEnabled，看看这是否是问题的根源。另外，您不应该混合其他 HMS 库的主要发布版本。从 4 或 5 开始。确保不要有从 3 到 5 的混合，这会产生其他错误
E/OneSignal: HMS ApiException getting Huawei push token!
    com.huawei.hms.common.ApiException: -5: Core error
检查您的 Proguard 或 R8 规则以确保它们设置正确。可能暂时禁用它，看看是否相关。如果在禁用 Proguard 或 R8 后修复了问题，那么您可以按照此指南重新启用它。请参见 “配置签名” 部分

​
测试 OneSignal SDK 集成

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

​
检查移动端订阅

1

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

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

iOS 和 Android 推送权限提示

2

检查您的 OneSignal 控制台

在接受提示之前，请检查 OneSignal 控制台：
  • 转到 受众 > 订阅。
  • 您应该看到一个状态为”从未订阅”的新条目。

控制台显示 '从未订阅' 状态的订阅

3

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

4

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

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

控制台显示 '已订阅' 状态的订阅

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

​
设置测试订阅

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

添加到测试订阅。

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

将设备添加到测试订阅

2

为您的订阅命名。

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

控制台显示 '为您的订阅命名' 字段

3

创建测试用户分组。

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

为分组命名。

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

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

使用测试用户过滤器创建 'Test Users' 分组

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

​
通过 API 发送测试推送

1

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

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

更新提供的代码。

将下面代码中的 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"
}'
3

运行代码。

在您的终端中运行代码。
4

检查图片和确认送达。

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

iOS 和 Android 上包含图片的推送通知

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

检查确认送达。

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

显示确认送达的送达统计

如果您使用的是专业版或更高版本，请滚动到受众活动以查看订阅级别的确认：

受众活动中设备级别的确认送达

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

​
发送应用内消息

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

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

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

创建应用内消息。

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

使用应用内消息定位 'Test Users' 分组

3

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

应用内欢迎消息的自定义示例

4

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

5

安排频率。

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

应用内消息安排选项

6

使消息生效。

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

打开应用并查看消息。

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

在设备上显示的欢迎应用内消息

没有看到消息？
  • 开始新会话
    • 您必须关闭或将应用切换到后台至少 30 秒后再重新打开。这可以确保开始新会话。
    • 更多信息，请参阅应用内消息如何显示。
  • 仍在 Test Users 分组中？
    • 如果您重新安装或更换了设备，请重新将设备添加到测试订阅并确认它是 Test Users 分组的一部分。
  • 遇到问题？
    • 在重现上述步骤时，请遵循获取调试日志。这将生成额外的日志，您可以与 support@onesignal.com 分享，我们将帮助调查正在发生的情况。
您已成功设置 OneSignal SDK 并学习了重要概念，如：继续阅读本指南以在您的应用中识别用户并设置其他功能。

​
用户识别

之前，我们演示了如何创建移动端订阅。现在我们将扩展到使用 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。

OneSignal 中带有名为'current_level'标签设置为'6'的用户档案

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

分组编辑器显示针对 current_level 值大于 4 且小于 10 的用户的分组


屏幕截图显示针对 5-10 级分组发送的个性化推送通知


iOS 和 Android 设备上收到的包含个性化内容的推送通知

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

之前我们了解了我们的 SDK 如何创建移动端订阅来发送推送和应用内消息。您还可以通过创建相应的订阅，通过电子邮件和短信渠道联系用户。 如果电子邮件地址和/或电话号码在 OneSignal 应用中已存在，SDK 会将其添加到现有用户，不会创建重复项。 您可以通过控制台中的 受众 > 用户 或使用查看用户 API查看统一的用户。

通过外部 ID 统一的包含推送、电子邮件和短信订阅的用户档案

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

​
隐私和用户同意

要控制 OneSignal 何时收集用户数据，请使用 SDK 的同意管控方法： 有关更多信息，请参阅我们的隐私和安全文档：

​
提示推送权限

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

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

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

​
推送通知事件

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

​
用户状态变化

​
应用内消息事件

​
高级设置和功能

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

​
移动端 SDK 设置和参考

通过查看移动端推送设置指南，确保您已启用所有关键功能。 有关可用方法和配置选项的完整详细信息，请访问移动端 SDK 参考。
恭喜！您已成功完成移动端 SDK 设置指南。
需要帮助？与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息：
  • 您遇到的问题详情以及复现步骤（如有）
  • 您的 OneSignal 应用 ID
  • 外部 ID 或订阅 ID（如适用）
  • 您在 OneSignal 控制台中测试的消息 URL（如适用）
  • 任何相关的日志或错误信息
我们很乐意为您提供帮助！
⌘I