使用 AI 编程助手?
如需 AI 驱动的安装,请使用以下提示:
步骤 0. 在 OneSignal 中配置 FCM(推送送达必需)
您可以在未完成此步骤的情况下安装和初始化 OneSignal Android SDK。但是,在 OneSignal 应用中配置 Firebase Cloud Messaging (FCM) 凭据之前,推送通知将无法送达。如果您的公司已有 OneSignal 账户,请要求以管理员角色被邀请以配置该应用。否则,请注册免费账户开始使用。
配置 OneSignal 应用的步骤。
配置 OneSignal 应用的步骤。
这些步骤将您的 OneSignal 应用连接到 Firebase Cloud Messaging (FCM)。每个应用只需执行一次。
- 登录 https://onesignal.com 并创建或选择您的应用。
- 导航到 Settings > Push & In-App。
- 选择 Google Android (FCM) 并 Continue 完成设置向导。
- 输入您的 Firebase 服务器密钥或服务账户详细信息。
- 继续完成设置向导以获取您的 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.2.1+)
- Android API: 最低 23+(Android 6.0+),推荐 31+(Android 12+)
- 设备/模拟器: Android 7.0+ 且已安装 Google Play Services
- 必需依赖:
com.onesignal:OneSignal:[5.6.1, 5.6.99] - Application 类: SDK 正确初始化所必需
- App ID 格式: 36 个字符的 UUID(示例:
12345678-1234-1234-1234-123456789012)— 在 OneSignal 控制面板 > 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
- 在 Android Studio 中,打开您的
build.gradle.kts (Module: app)或build.gradle (Module: app)文件 - 将 OneSignal 添加到您的
dependencies部分:

- 同步 Gradle: 点击出现的横幅中的 Sync Now 或前往 File > Sync Project with Gradle Files
验证 Gradle 同步成功完成且没有依赖冲突。
步骤 2. 创建并配置 Application 类
最佳实践是在Application 类的 onCreate 方法中初始化 OneSignal,以确保在所有入口点都能正确设置 SDK。
如果您还没有 Application 类,请创建一个:
- File > New > Kotlin Class/File(或 Java Class)
- 名称:
ApplicationClass(或您首选的名称)

YOUR_APP_ID 替换为您在 Dashboard > Settings > Keys & IDs 中获取的实际 OneSignal App ID。

- 打开应用的
AndroidManifest.xml - 在
<application>标签中添加android:name=".ApplicationClass"(如果您设置了不同的类名,请替换.ApplicationClass)。
AndroidManifest.xml

验证应用构建并运行无错误。
步骤 3. 配置默认通知图标(推荐)
自定义通知图标以匹配您的应用品牌。此步骤是可选的,但为了专业外观建议完成。步骤 4. 测试集成
验证订阅创建:- 在带有 Google Play Services 的设备或模拟器上启动应用
- 检查 Dashboard > Audience > Subscriptions — 状态显示 “Never Subscribed”
- 当权限提示出现时接受
- 刷新控制面板 — 状态变为 “Subscribed”



您已成功创建了一个移动订阅。
移动订阅在用户首次在设备上打开您的应用或卸载后重新安装时创建。
创建测试订阅和细分
- 点击订阅旁边的 ⋮ > Add to Test Subscriptions > 为其命名
- 前往 Audience > Segments > New Segment
- 名称:
Test Users,添加 Test Users 筛选器 > Create Segment


您已成功创建了一个测试用户细分。现在我们可以测试向该设备和测试用户组发送消息。
通过 API 发送测试推送
- 导航到 Settings > Keys & IDs。
- 在提供的代码中,将下方代码中的
YOUR_APP_API_KEY和YOUR_APP_ID替换为您的实际密钥。此代码使用我们之前创建的Test Users细分。


验证测试设备收到了包含以下内容的通知:
- 您的自定义图标(如已配置)
- 展开时的大图
- Dashboard > Delivery > Sent Messages 显示 “Confirmed” 状态(免费计划不可用)。
测试应用内消息
- 关闭应用 30 秒以上
- Dashboard > Messages > In-App > New In-App > 选择 Welcome 模板
- 受众:Test Users 细分
- 触发器:On app open
- 计划:Every time trigger conditions are satisfied
- 点击 Make Message Live
- 打开应用




验证测试设备收到了应用内消息。有关更多详情,请参阅应用内消息设置指南。
常见错误和修复
| 错误 / 症状 | 原因 | 修复方法 |
|---|---|---|
Cannot resolve symbol 'OneSignal' | 未添加 SDK 依赖或未同步 Gradle | 将依赖添加到 build.gradle 并同步项目 |
Application class not found | Application 类未在清单中注册 | 在 <application> 标签中添加 android:name=".ApplicationClass" |
Google Play Services not available | 模拟器/设备缺少 Play Services | 使用带有 Play Store 的设备或带有 Google APIs 的模拟器 |
| 收到推送但显示默认 Android 图标 | 自定义图标未配置或名称错误 | 创建名为 onesignal_small_icon_default 的通知图标资源 |
| 未收到推送通知 | FCM 未在 OneSignal 中配置 | 完成步骤 0:在 OneSignal 控制面板中配置 FCM 凭据 |
| 应用内消息不显示 | 会话未启动或网络问题 | 关闭应用 30 秒以上,重新打开,检查网络连接 |
Manifest merger failed | 清单属性冲突 | 检查是否有重复的应用名称或权限冲突 |
| 电池优化阻止通知 | 设备电源管理 | 引导用户为您的应用禁用电池优化 |
| 无法诊断问题 | 日志信息不足 | 添加详细日志并检查 logcat 输出中的错误 |
用户管理
之前,我们演示了如何创建移动订阅。现在我们将扩展到使用 OneSignal SDK 通过所有订阅(包括推送、邮件和短信)来识别用户。分配 External ID(推荐)
使用 External ID 通过后端的用户标识符在设备、邮箱地址和电话号码之间一致地识别用户。这确保您的消息在渠道和第三方系统之间保持统一。有关更多详情和 Java 代码示例,请参阅我们的移动 SDK 参考。Kotlin
OneSignal 为订阅(Subscription ID)和用户(OneSignal ID)生成唯一的只读 ID。强烈建议通过我们的 SDK 设置 External ID,以便在所有订阅中识别用户,无论它们是如何创建的。在 SDK 参考指南中了解更多关于
login 方法的信息。添加标签和自定义事件
标签和自定义事件都是向用户添加数据的方式。标签是key-value 字符串,通常与用户属性相关联(如 username、role 或 status),而自定义事件具有 JSON 格式,通常与操作相关联(如 new_purchase、abandoned_cart 及相关属性)。两者都可用于驱动高级消息个性化和 Journeys。有关更多详情和 Java 代码示例,请参阅我们的移动 SDK 参考。
Kotlin
添加邮件和/或短信订阅
除了推送通知外,您还可以通过邮件和短信渠道联系用户。如果邮箱地址和/或电话号码已存在于 OneSignal 应用中,SDK 会将其添加到现有用户 — 不会创建重复项。有关更多详情和 Java 代码示例,请参阅我们的移动 SDK 参考。Kotlin

多渠道通信最佳实践
- 在添加邮件或短信订阅之前获取明确同意。
- 向用户说明每个通信渠道的好处。
- 提供渠道偏好设置,让用户选择他们偏好的渠道。
隐私和用户同意
要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意管理方法。有关更多详情和 Java 代码示例,请参阅我们的移动 SDK 参考。Kotlin
推送权限提示
不要在应用打开时立即调用requestPermission(),而是采取更具策略性的方法。使用应用内消息在请求权限之前向用户说明推送通知的价值。
有关最佳实践和实现详情,请参阅我们的推送权限提示指南。
监听推送、用户和应用内事件
使用 SDK 监听器来响应用户操作和状态变化。在OneSignal.initWithContext() 之后将这些添加到您的 Application 类中。
推送通知事件
Kotlin
用户状态变化
示例展示了如何使用推送订阅观察者。其他用户状态事件,如用户状态观察者和通知权限观察者,可在移动 SDK 参考中找到。Kotlin
应用内消息事件
其他应用内消息方法可在移动 SDK 参考中找到。Kotlin
高级设置和功能
Android 特定功能
通用功能
有关完整的 SDK 方法文档,请访问移动 SDK 参考。需要帮助?与我们的支持团队聊天或发送邮件至
support@onesignal.com请包含以下信息:- 您遇到的问题详情以及复现步骤(如有)
- 您的 OneSignal 应用 ID
- 外部 ID 或订阅 ID(如适用)
- 您在 OneSignal 控制台中测试的消息 URL(如适用)
- 任何相关的日志或错误信息