跳转到主要内容
要通过 Google Play Store 向 Android 设备发送推送通知，OneSignal 需要 Firebase Cloud Messaging (FCM) 凭据。本指南将带您生成所需的服务账户 JSON 文件并将其上传到 OneSignal 应用设置。 有关技术背景，请参阅 Google 的服务账户文档。
本指南适用于将 OneSignal 与通过 Google Play Store 分发的 Android 移动应用集成的开发者。

​
要求

​
设置

​
1. 创建或打开您的 Firebase 项目

转到 Firebase 控制台。
  • 如果您还没有项目，请点击添加项目并完成设置。
  • 如果您已有项目，请选择它。

Firebase 中的项目页面

​
2. 启用 Firebase Cloud Messaging API v1

1

转到项目设置

在 Firebase 中，点击项目概览 > 项目设置旁边的齿轮图标。

Firebase 齿轮图标子菜单，显示项目设置

2

转到云消息传递

转到云消息传递选项卡。如果 Firebase Cloud Messaging API (V1) 已禁用，请点击 3 点菜单 > 在云控制台中打开。

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

在 Google Cloud 控制台中，点击启用。等待几分钟，等待更改在 Firebase 中生效。

启用 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