使用 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 完成设置向导。
- 上传您的 FCM Service Account JSON。
- 继续完成设置向导以获取您的 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
- 在 Android Studio 中,打开您的
build.gradle.kts (Module: app)或build.gradle (Module: app)文件 - 将 OneSignal 添加到您的
dependencies部分:

示例展示了将 OneSignal 添加到应用的 build.gradle.kts 文件中。
- 同步 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(或您首选的名称)

示例展示了创建一个名为 ApplicationClass 的新 Kotlin 类。
YOUR_APP_ID 替换为您在 Dashboard > Settings > Keys & IDs 中获取的实际 OneSignal App ID。

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

包含 .ApplicationClass 名称的 AndroidManifest.xml。
验证应用构建并运行无错误。
步骤 3. 配置默认通知图标(推荐)
用名为ic_stat_onesignal_default 的小图标替换默认的铃铛图标。请使用透明背景上的单色剪影,否则 Android 会渲染成白色方块。
- 使用 Android Asset Studio 生成各种密度的图标。
- 将
ic_stat_onesignal_default放入每个密度文件夹:从res/drawable-mdpi/(24×24)到res/drawable-xxxhdpi/(96×96)。
步骤 4. 测试集成
验证订阅创建:- 在带有 Google Play Services 的设备或模拟器上启动应用。
- 检查 Dashboard > Audience > Subscriptions。状态显示 Never Subscribed。
- 当权限提示出现时接受。
- 刷新控制面板。状态变为 Subscribed。

Android 推送权限提示

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

允许推送权限后,刷新控制面板可看到订阅状态更新为 'Subscribed'
创建测试用户和细分
- 在订阅旁边,选择 Options > Add as test user 并输入名称。
- 前往 Audience > Segments > New Segment。
- 名称:
Test Users,添加筛选器 Test Users > Create Segment。

添加测试用户

使用 Test Users 筛选器创建 'Test Users' 细分
通过 API 发送测试推送
- 导航到 Settings > Keys & IDs。
- 在提供的代码中,将下方代码中的
YOUR_APP_API_KEY和YOUR_APP_ID替换为您的实际密钥。此代码使用我们之前创建的Test Users细分。

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

显示确认送达的投递统计(免费计划不可用)
测试应用内消息
- 关闭应用 30 秒以上
- Dashboard > Messages > In-App > New In-App > 选择 Welcome 模板
- 受众:Test Users 细分
- 触发器:On app open
- 计划:Every time trigger conditions are satisfied
- 点击 Make Message Live
- 打开应用

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

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

应用内消息调度选项

设备上显示的 Welcome 应用内消息
常见错误和修复
用户管理
之前,我们演示了如何创建移动订阅。现在我们将扩展到使用 OneSignal SDK 通过所有订阅(包括推送、邮件和短信)来识别用户。分配 External ID(推荐)
使用 External ID 通过后端的用户标识符在设备、邮箱地址和电话号码之间一致地识别用户。这确保您的消息在渠道和第三方系统之间保持统一。OneSignal 为订阅(Subscription ID)和用户(OneSignal ID)生成唯一的只读 ID。强烈建议通过我们的 SDK 设置 External ID,以便在所有订阅中识别用户,无论它们是如何创建的。在 SDK 参考中了解更多关于
login 方法的信息。添加标签和自定义事件
标签和自定义事件都是向用户添加数据的方式。标签是用于用户属性的key-value 字符串(如 username、role 或 status)。自定义事件使用 JSON 格式,通常表示操作(如 new_purchase 或 abandoned_cart)。两者都可用于驱动消息个性化和 Journeys。
添加邮件和/或短信订阅
除了推送通知外,您还可以通过邮件和短信联系用户。如果邮箱地址或电话号码已存在于 OneSignal 应用中,SDK 会将其添加到现有用户,不会创建重复项。请先调用login(),以便该地址关联到已识别的用户。

通过 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(如适用)
- 任何相关的日志或错误信息