本指南适用于将 OneSignal 与通过 Google Play Store 分发的 Android 移动应用集成的开发者。
- 本指南不适用于 Web Push。请参阅 Web push 设置。
- 对于通过华为应用市场分发的华为应用,请参阅 华为:授权 OneSignal。
要求
- 通过 Google Play Store 分发的 Android 应用
- Firebase 账户(免费)
- OneSignal 账户
设置
1. 创建或打开您的 Firebase 项目
转到 Firebase 控制台。- 如果您还没有项目,请点击添加项目并完成设置。
- 如果您已有项目,请选择它。

Firebase 中的项目页面
2. 启用 Firebase Cloud Messaging API v1
1
转到项目设置
在 Firebase 中,点击项目概览 > 项目设置旁边的齿轮图标。

Firebase 齿轮图标子菜单,显示项目设置
2
转到云消息传递
转到云消息传递选项卡。如果 Firebase Cloud Messaging API (V1) 已禁用,请点击 3 点菜单 > 在云控制台中打开。
在 Google Cloud 控制台中,点击启用。等待几分钟,等待更改在 Firebase 中生效。

此图中禁用了 Firebase Cloud Messaging API (V1)。请确保为您的项目启用它。

启用 Firebase Cloud Messaging API v1。
3. 生成服务账户 JSON 文件
1
返回项目设置 > 服务账户
在底部,点击生成新的私钥。

Firebase 中的服务账户部分
2
确认并生成密钥
在弹窗中点击生成密钥进行确认。

🔒 此文件包含敏感凭据。请勿分享或将其检入版本控制。
3
保存文件
将
.json
文件保存在安全的位置。您很快就会用到它。所需的服务账户权限:
cloudmessaging.messages.create
firebase.projects.get
roles/firebasemessaging.admin
roles/firebase.viewer
4. 将您的凭据上传到 OneSignal
1
转到 Android 平台设置
在您的 OneSignal 仪表板中,转到:设置 > 推送和应用内 > 推送平台 > Google Android (FCM)。点击激活。

OneSignal 应用设置中的平台屏幕
2
上传您的凭据
在服务账户 JSON 下通过点击选择文件上传 
.json
文件。
FCM 配置屏幕
如果出现提示,请从下拉菜单中选择 Firebase Cloud Messaging API (V1)。要验证您使用的是正确的 Firebase 项目,请将 Firebase 中的 Sender ID(
Cloud Messaging > Sender ID
)与 OneSignal 设置中显示的 ID 匹配。3
保存并继续
4
选择您的 SDK
选择您使用的 SDK 并点击保存并继续。

SDK 选择屏幕
5
将 OneSignal 应用 ID 添加到您的代码中
继续按照移动端 SDK 设置并将此 OneSignal 应用 ID 添加到您的代码中。

Android 配置安装和测试屏幕
您已成功将 OneSignal 应用连接到 Firebase Cloud Messaging (V1)。接下来,完成移动端 SDK 设置或转到移动端推送设置获取平台特定的说明。
常见问题
错误:“此配置适用于不同的 Firebase 项目…”
当上传的 JSON 文件属于不同的 Firebase 项目(即不同的 Sender ID)时会出现此错误。 解决方案:使用原始 Firebase 项目的 JSON 文件。如果无法获得,请联系support@onesignal.com
并提供您的应用 ID。切换项目会重置推送令牌——您的用户必须重新打开应用才能再次接收推送。
我可以更改我的 Sender ID 吗?
不可以。一旦您的应用超过 100 个 Android 用户,Sender ID 就会被锁定,以防止意外使推送令牌失效。 如有必要,请联系support@onesignal.com
并提供您的应用 ID 寻求帮助。
切换到 FCM V1 时需要更新我的代码吗?
不需要应用或 SDK 更改——这只是仪表板更新。切换到 FCM v1 的截止日期是什么时候?
Google 于 2024 年 7 月开始弃用旧版 FCM API。强烈建议迁移。请参阅 Google 的公告。为什么我在 OneSignal 中看不到 Sender ID?
如果您的 Firebase 服务器密钥看起来像AIz...
,您可能正在使用过时的 Google Cloud Messaging (GCM) 设置。请创建一个新的 Firebase 项目并上传服务账户 JSON 文件。
如何检查哪些应用仍在使用旧版 API?
使用 查看应用 API 并检查:"gcm_key"
→ 使用旧版,需要更新"fcm_v1_service_account_json"
→ 使用 V1 ✅- 都没有 → 应用不使用 Android push