Skip to main content
本指南将引导您使用 Android Studio 将 OneSignal 添加到您的 Android 应用中。您将安装我们的 SDK,设置推送通知和应用内消息,并发送测试消息以确认一切正常工作。 如果这是您首次使用 OneSignal,请按顺序完成这些步骤。如果您有经验,可以直接跳转到需要的部分。
使用 AI 编程助手? 如需 AI 驱动的安装,请使用以下提示:

步骤 0. 在 OneSignal 中配置 FCM(推送送达必需)

您可以在未完成此步骤的情况下安装和初始化 OneSignal Android SDK。但是,在 OneSignal 应用中配置 Firebase Cloud Messaging (FCM) 凭据之前,推送通知将无法送达
如果您的公司已有 OneSignal 账户,请要求以管理员角色被邀请以配置该应用。否则,请注册免费账户开始使用。
这些步骤将您的 OneSignal 应用连接到 Firebase Cloud Messaging (FCM)。每个应用只需执行一次。
  1. 登录 https://onesignal.com 并创建或选择您的应用。
  2. 导航到 Settings > Push & In-App
  3. 选择 Google Android (FCM)Continue 完成设置向导。
  4. 上传您的 FCM Service Account JSON
  5. 继续完成设置向导以获取您的 App ID。这将用于初始化 SDK。
有关完整的设置说明,请参阅我们的移动推送设置指南。

设置合约和要求

本节总结了本指南中使用的工具、版本和前提条件。
  • SDK 版本: 5.6.1+(最新版:查看 releases
  • AI 设置说明: https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
  • SDK 仓库: https://github.com/OneSignal/OneSignal-Android-SDK
  • Android Studio: Meerkat | 2024.3.1+
  • Android API: 最低 23+(Android 6.0+),推荐 31+(Android 12+)
  • 设备/模拟器: Android 7.0+ 且已安装 Google Play Services
  • 必需依赖: com.onesignal:OneSignal:[5.6.1, 5.99.99]
  • Application 类: SDK 正确初始化所必需
  • App ID 格式: 36 个字符的 UUID(示例:12345678-1234-1234-1234-123456789012)。在 Dashboard > Settings > Keys & IDs 中查找。
  • 初始化: OneSignal.initWithContext(this, "YOUR_APP_ID")
  • 电池优化: 可能影响后台通知
  • 推荐: 通过 OneSignal.login("user_id") 分配 External ID 以统一跨设备用户

Android 设置步骤

完成以下步骤后,您将:
  • 在您的 Android 应用中安装并初始化 OneSignal SDK
  • 在真实设备上正确提示推送通知权限
  • 成功送达测试推送和应用内消息
如果您跳过了步骤 0(在 OneSignal 中配置 FCM),您仍然可以完成以下 Android Studio 设置。请在测试或发送推送通知之前完成步骤 0。

步骤 1. 添加 OneSignal SDK

  1. 在 Android Studio 中,打开您的 build.gradle.kts (Module: app)build.gradle (Module: app) 文件
  2. 将 OneSignal 添加到您的 dependencies 部分:
Android Studio 中应用的 build.gradle.kts 文件,已添加 OneSignal implementation 依赖

示例展示了将 OneSignal 添加到应用的 build.gradle.kts 文件中。

  1. 同步 Gradle: 点击出现的横幅中的 Sync Now 或前往 File > Sync Project with Gradle Files
验证 Gradle 同步成功完成且没有依赖冲突。

步骤 2. 创建并配置 Application 类

最佳实践是在 Application 类的 onCreate 方法中初始化 OneSignal,以确保在所有入口点都能正确设置 SDK。 如果您还没有 Application 类,请创建一个:
  1. File > New > Kotlin Class/File(或 Java Class)
  2. 名称:ApplicationClass(或您首选的名称)
Android Studio 的 New Kotlin Class 对话框,名称为 ApplicationClass

示例展示了创建一个名为 ApplicationClass 的新 Kotlin 类。

将以下 OneSignal 代码添加到 Application 类中。 YOUR_APP_ID 替换为您在 Dashboard > Settings > Keys & IDs 中获取的实际 OneSignal App ID。
Android Studio 中的 ApplicationClass.kt,展示 OneSignal initWithContext 和 requestPermission

示例 ApplicationClass.kt 文件。

不建议在 Activity(如 MainActivity)中初始化,因为通过深度链接或通知冷启动应用时可能不会调用它。请始终在 Application 类中初始化 OneSignal 以确保可靠性。
注册 Application 类:
  1. 打开应用的 AndroidManifest.xml
  2. <application> 标签中添加 android:name=".ApplicationClass"(如果您设置了不同的类名,请替换 .ApplicationClass)。
AndroidManifest.xml
检查 <application> 标签是否包含 tools:node="replace"。该标记会删除库合并进来的组件,包括 OneSignal 的 PermissionsActivity。通知权限流程随后会因 ActivityNotFoundException 崩溃。请移除 tools:node="replace"。如果只需覆盖单个属性,请使用 tools:replace="android:theme"(或您正在更改的属性)。
AndroidManifest.xml 的 application 标签,android:name 设置为 .ApplicationClass

包含 .ApplicationClass 名称的 AndroidManifest.xml。

验证应用构建并运行无错误。

步骤 3. 配置默认通知图标(推荐)

用名为 ic_stat_onesignal_default 的小图标替换默认的铃铛图标。请使用透明背景上的单色剪影,否则 Android 会渲染成白色方块。
  1. 使用 Android Asset Studio 生成各种密度的图标。
  2. ic_stat_onesignal_default 放入每个密度文件夹:从 res/drawable-mdpi/(24×24)到 res/drawable-xxxhdpi/(96×96)。
有关大图标、强调色和 Android 17 启动器图标行为,请参阅通知图标

步骤 4. 测试集成

验证订阅创建:
  1. 在带有 Google Play Services 的设备或模拟器上启动应用。
  2. 检查 Dashboard > Audience > Subscriptions。状态显示 Never Subscribed
  3. 当权限提示出现时接受。
  4. 刷新控制面板。状态变为 Subscribed
请求允许通知的 Android 推送权限提示

Android 推送权限提示

控制面板显示状态为 'Never Subscribed' 的订阅。

控制面板显示状态为 'Never Subscribed' 的订阅

允许推送权限后,刷新控制面板可看到订阅状态更新为 'Subscribed'。

允许推送权限后,刷新控制面板可看到订阅状态更新为 'Subscribed'

移动订阅在用户首次在设备上打开您的应用时创建,或在他们于同一设备上卸载并重新安装时创建。在他们接受权限提示后,控制面板状态应显示 Subscribed

创建测试用户和细分

  1. 在订阅旁边,选择 Options > Add as test user 并输入名称。
  2. 前往 Audience > Segments > New Segment
  3. 名称:Test Users,添加筛选器 Test Users > Create Segment
订阅记录上的 Options 菜单,高亮显示 Add as test user

添加测试用户

使用 Test Users 筛选器创建 'Test Users' 细分。

使用 Test Users 筛选器创建 'Test Users' 细分

您现在可以向该设备和 Test Users 细分发送测试消息。

通过 API 发送测试推送

  1. 导航到 Settings > Keys & IDs
  2. 在提供的代码中,将下方代码中的 YOUR_APP_API_KEYYOUR_APP_ID 替换为您的实际密钥。此代码使用我们之前创建的 Test Users 细分。
推送通知中的图片在折叠通知视图中显示较小。展开通知可查看完整图片。

折叠通知视图中图片会显示较小。展开通知可查看完整图片。

显示确认送达的投递统计(免费计划不可用)。

显示确认送达的投递统计(免费计划不可用)

确认测试设备收到了带有您自定义图标(如已配置)的通知,并在展开时显示大图。在付费计划中,Dashboard > Delivery > Sent Messages 可以显示确认送达。
  • 未收到通知?请参阅移动推送未显示
  • 没有自定义图标?请验证图标名称为 ic_stat_onesignal_default 且位于正确的 drawable 文件夹中。
  • 遇到问题?请将 API 请求和从应用启动到结束的日志复制粘贴到 .txt 文件中,然后将两者发送至 support@onesignal.com

测试应用内消息

  1. 关闭应用 30 秒以上
  2. Dashboard > Messages > In-App > New In-App > 选择 Welcome 模板
  3. 受众:Test Users 细分
  4. 触发器:On app open
  5. 计划:Every time trigger conditions are satisfied
  6. 点击 Make Message Live
  7. 打开应用
使用应用内消息定向 'Test Users' 细分。

使用应用内消息定向 'Test Users' 细分

应用内 Welcome 消息的自定义示例。

应用内 Welcome 消息的自定义示例

应用内消息调度选项。

应用内消息调度选项

设备上显示的 Welcome 应用内消息。

设备上显示的 Welcome 应用内消息

测试设备应显示 Welcome 应用内消息。有关更多详情,请参阅应用内消息设置
未看到消息?
  • 开始新会话
    • 强制退出并重新打开应用,或将应用关闭/置于后台至少 30 秒后再重新打开。两种方式都能确保启动新的会话。请参阅会话
    • 有关更多信息,请参阅应用内消息的显示方式
  • 仍在 Test Users 细分中?
    • 如果您重新安装或切换了设备,请将设备重新添加到测试用户并确认它属于 Test Users 细分。
  • 遇到问题?
    • 在重现上述步骤时按照获取调试日志的说明操作。这将生成额外的日志信息,您可以将其分享至 support@onesignal.com,我们将帮助调查问题所在。
您现在拥有了订阅测试用户细分。您通过创建消息 API 发送了带图片的推送和一条应用内消息。继续阅读下文以识别用户并添加更多功能。
您已成功设置 OneSignal SDK 并学习了以下重要概念:继续阅读本指南以在您的应用中识别用户并设置其他功能。

常见错误和修复

用户管理

之前,我们演示了如何创建移动订阅。现在我们将扩展到使用 OneSignal SDK 通过所有订阅(包括推送、邮件和短信)来识别用户

分配 External ID(推荐)

使用 External ID 通过后端的用户标识符在设备、邮箱地址和电话号码之间一致地识别用户。这确保您的消息在渠道和第三方系统之间保持统一。
OneSignal 为订阅(Subscription ID)和用户(OneSignal ID)生成唯一的只读 ID。强烈建议通过我们的 SDK 设置 External ID,以便在所有订阅中识别用户,无论它们是如何创建的。在 SDK 参考中了解更多关于 login 方法的信息。

添加标签和自定义事件

标签和自定义事件都是向用户添加数据的方式。标签是用于用户属性的 key-value 字符串(如 usernamerolestatus)。自定义事件使用 JSON 格式,通常表示操作(如 new_purchaseabandoned_cart)。两者都可用于驱动消息个性化和 Journeys。
有关更多详情,请参阅标签自定义事件

添加邮件和/或短信订阅

除了推送通知外,您还可以通过邮件和短信联系用户。如果邮箱地址或电话号码已存在于 OneSignal 应用中,SDK 会将其添加到现有用户,不会创建重复项。请先调用 login(),以便该地址关联到已识别的用户。
通过 External ID 统一推送、邮件和短信订阅的用户资料。

通过 External ID 统一推送、邮件和短信订阅的用户资料

多渠道通信最佳实践
  • 在添加邮件或短信订阅之前获取明确同意。
  • 向用户说明每个通信渠道的好处。
  • 提供渠道偏好设置,让用户选择他们偏好的渠道。

隐私和用户同意

要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意管理方法。请在 initWithContext 之前调用 consentRequired

推送权限提示

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

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

使用 SDK 监听器来响应用户操作和状态变化。在 OneSignal.initWithContext() 之后将这些添加到您的 Application 类中。

推送通知事件

用户状态变化

此示例使用推送订阅观察者。用户状态观察者和通知权限观察者可在移动 SDK 参考中找到。

应用内消息事件

其他应用内消息方法可在移动 SDK 参考中找到。

高级设置和功能

Android 特定功能

通用功能

有关完整的 SDK 方法文档,请参阅移动 SDK 参考

常见问题(FAQ)

为什么 Android Studio 无法解析 OneSignal

SDK 依赖缺失或 Gradle 尚未同步。将 com.onesignal:OneSignal:[5.6.1, 5.99.99] 添加到应用模块的 build.gradle 中,并使用 File > Sync Project with Gradle Files

为什么找不到我的 Application 类?

该类未在清单中注册。在 AndroidManifest.xml<application> 标签中添加 android:name=".ApplicationClass"(或您的类名)。

为什么模拟器提示 Google Play Services 不可用?

模拟器镜像不包含 Play Services。请使用带有 Play Store 的设备,或包含 Google APIs 的模拟器系统镜像。

为什么通知显示默认的 Android 图标?

小图标缺失或名称错误。将 ic_stat_onesignal_default 添加到每个 res/drawable-* 密度文件夹中。请参阅通知图标

为什么我的测试设备没有收到推送?

FCM 凭据未配置,或设备未订阅。完成步骤 0 并确认订阅状态为 Subscribed。然后参阅移动推送未显示

为什么应用内消息不显示?

应用内消息需要新会话。强制退出应用,或将其置于后台至少 30 秒,然后重新打开。确认设备仍在 Test Users 细分中。请参阅会话应用内消息的显示方式

什么原因导致 Manifest merger failed

<application>android:name 值冲突或权限重复。在合并后的清单中搜索是否存在第二个 Application 类,并只保留一个 android:name

为什么电池优化会阻止通知?

某些 OEM 厂商会限制后台工作。如果通知在设备休眠后停止,请让用户为您的应用禁用电池优化。

如何获取更多日志输出?

设置 OneSignal.Debug.logLevel = LogLevel.VERBOSE(Kotlin)或 OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE)(Java),重现问题并捕获 logcat。请参阅获取调试日志
需要帮助?与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息:
  • 您遇到的问题详情以及复现步骤(如有)
  • 您的 OneSignal 应用 ID
  • 外部 ID 或订阅 ID(如适用)
  • 您在 OneSignal 控制台中测试的消息 URL(如适用)
  • 任何相关的日志或错误信息
我们很乐意为您提供帮助!