跳转到主要内容
要通过 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 IDCloud 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

I