> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Android Firebase 凭据

> 在 OneSignal 中配置 Firebase Cloud Messaging (FCM) 服务账户凭据，为 Google Play Store 上的应用启用 Android 推送通知。

要向通过 Google Play Store 下载您 Android 应用的用户发送推送通知，您必须创建一个 Firebase Cloud Messaging (FCM) 服务账户私钥并将其上传到 OneSignal。

<Note>
  本说明不适用于：

  * **Web Push。** Android 设备无需 FCM 服务账户即可订阅您的网站或 PWA。请参阅 [Web push 设置](./web-push-setup)。
  * **通过华为应用市场分发的华为应用。** 请参阅 [华为授权](./authorize-onesignal-to-send-huawei-push)。
</Note>

***

## 要求

* 通过 Google Play Store 分发的 Android 应用
* 一个 [OneSignal 账户](https://onesignal.com)
* 一个 [Firebase 账户（免费）](https://firebase.google.com)
* 具有 `cloudmessaging.messages.create` 和 `firebase.projects.get` 权限的 Firebase 服务账户私钥
  * 如果您还没有，请按以下步骤[创建 Firebase 服务账户私钥](#create-a-firebase-service-account-private-key)
  * 如果您已有私钥，请[检查现有权限](#how-do-i-check-my-service-account-permissions)

***

<h2 id="create-a-firebase-service-account-private-key">
  创建 Firebase 服务账户私钥 \\
</h2>

<Steps>
  <Step title="创建或打开您的 Firebase 项目">
    转到您的 [Firebase 控制台](https://console.firebase.google.com/)，创建或选择一个项目。

    <Frame caption="Firebase 中的项目页面">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-projects.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=aca8614ec0e40fc63fd71f3160098778" alt="Firebase 控制台显示可用项目列表" width="2656" height="1780" data-path="images/mobile/firebase-projects.png" />
    </Frame>
  </Step>

  <Step title="启用 Firebase Cloud Messaging API V1">
    在**项目设置**中，选择 **Cloud Messaging** 选项卡。

    <Frame caption="Firebase 项目设置中的 Cloud Messaging 选项卡">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-project-settings-cloud-messaging.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=e877c1d0ca51b85b1f2e80418e0195c4" alt="Firebase 项目设置显示 Cloud Messaging 选项卡，Firebase Cloud Messaging API (V1) 状态为已启用" width="2956" height="1140" data-path="images/mobile/firebase-project-settings-cloud-messaging.png" />
    </Frame>

    检查 **Firebase Cloud Messaging API (V1)** 状态：

    * 如果显示**已启用**（绿色对勾），请继续下一步。
    * 如果显示**已禁用**，请点击 **3 点菜单 > 在 Google Cloud Console 中管理 API**。在 Google Cloud Console 中点击**启用**，等待出现绿色对勾和 "API Enabled" 字样。

    <Frame caption="在 Google Cloud Console 中启用的 Firebase Cloud Messaging API">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-cloud-messaging-api-v1-enabled.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=9239c8baa0659152d8aed6fc6af810a7" alt="Google Cloud Console 上的 Firebase Cloud Messaging API 页面显示 API Enabled 状态和绿色对勾" width="1616" height="750" data-path="images/mobile/firebase-cloud-messaging-api-v1-enabled.png" />
    </Frame>

    <Note>
      此时正适合检查您的 Firebase 服务账户是否具有所需权限：

      * `cloudmessaging.messages.create`
      * `firebase.projects.get`

      新创建的 Firebase 项目通常默认就拥有这些权限。如果不确定或使用的是较旧的项目，请在继续之前先检查。详情请参阅[我如何检查我的服务账户权限？](#how-do-i-check-my-service-account-permissions)。
    </Note>
  </Step>

  <Step title="生成新的私钥">
    回到**项目设置**，选择**服务账户**选项卡，点击**生成新的私钥**。

    <Frame caption="Firebase 中的服务账户部分">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-project-settings-service-accounts.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=d0b4a6d7c84cd1a639b6de79c3789363" alt="Firebase 项目设置中的服务账户选项卡，显示生成新的私钥按钮" width="2978" height="1734" data-path="images/mobile/firebase-project-settings-service-accounts.png" />
    </Frame>

    在弹窗中点击**生成密钥**进行确认。

    <Frame caption="为服务账户生成私钥。">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-generate-new-private-key.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=6b3ca4145c180400cf80a434adbbc216" alt="Firebase 为服务账户生成新私钥的确认对话框" width="1432" height="572" data-path="images/mobile/firebase-generate-new-private-key.png" />
    </Frame>

    <Warning>
      下载的私钥包含敏感凭据。请勿共享或将其提交到版本控制中。
    </Warning>

    将 `.json` 文件保存在安全的位置。下一节会用到它。
  </Step>
</Steps>

***

## 将服务账户私钥上传到 OneSignal

在您的 OneSignal 控制台中：

<Steps>
  <Step title="打开 Android 设置">
    转到**设置 > 推送和应用内消息 > 平台 > Google Android (FCM)**。

    点击**激活**（初次设置）或**设置**（如果 Android 已配置）。

    <Frame caption="OneSignal 应用设置中的平台屏幕">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/onesignal-push-platforms.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=9b8af64aae3dd5fdcb715731710785ca" alt="OneSignal 推送和应用内消息设置显示平台选项卡，包含 Google Android (FCM) 磁贴和设置按钮" width="2496" height="648" data-path="images/mobile/onesignal-push-platforms.png" />
    </Frame>
  </Step>

  <Step title="上传您的服务账户私钥">
    点击**选择文件**，选择您在上一节中保存的 `.json` 私钥。

    <Frame caption="FCM 配置屏幕">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/onesignal-fcm-configuration.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=5fb6b977bf1517c453b1c0b0c9b57274" alt="OneSignal Google Android (FCM) 配置屏幕，包含 Service Account JSON 文件上传字段和选择文件按钮" width="1780" height="702" data-path="images/mobile/onesignal-fcm-configuration.png" />
    </Frame>
  </Step>

  <Step title="保存并继续">
    点击**保存并继续**。OneSignal 会验证私钥，并将您带到设置流程的下一步，在那里您将选择 SDK。

    <Warning>
      如果控制台显示 **Invalid request** 或其他错误，您的服务账户可能缺少一个或多个所需角色。请参阅[我如何检查我的服务账户权限？](#how-do-i-check-my-service-account-permissions)。
    </Warning>
  </Step>
</Steps>

<Check>
  您的 OneSignal 应用现已连接到 Firebase Cloud Messaging (V1)。接下来，按照[移动 SDK 设置](./mobile-sdk-setup)中适用于您所用 SDK 的说明，在您的应用中安装并初始化 OneSignal。
</Check>

***

## 常见问题

<h3 id="how-do-i-check-my-service-account-permissions">
  我如何检查我的服务账户权限？ \\
</h3>

服务账户权限在 **Google Cloud Console** 中管理，而不是在 Firebase 控制台中。您上传到 OneSignal 的私钥所对应的服务账户必须同时具有：

* `cloudmessaging.messages.create`——由 **Firebase Cloud Messaging API Admin**（`roles/firebasecloudmessaging.admin`）授予。
* `firebase.projects.get`——由 **Firebase Viewer**（`roles/firebase.viewer`）授予。

像 **Firebase Admin**（`roles/firebase.admin`）、**Editor** 或 **Owner** 这样更宽泛的角色也包含这两项权限，同样满足要求。对于仅用于 OneSignal 的服务账户，建议优先使用上述精细的角色组合，以限制私钥泄露时的影响。

如果在上传服务账户私钥后 OneSignal 控制台显示 **Invalid request**，缺少角色是最常见的原因。

<Steps>
  <Step title="在 Google Cloud Console 中打开 IAM">
    登录 [Google Cloud Console](https://console.cloud.google.com/)，选择与您的 Firebase 应用关联的项目，然后转到 **IAM 和管理 > IAM**。
  </Step>

  <Step title="找到您的服务账户">
    将主体邮箱与您上传的私钥中的 `client_email` 字段匹配。
  </Step>

  <Step title="添加任何缺少的角色">
    点击铅笔（编辑）图标，然后点击**添加其他角色**，添加尚未分配的任一角色。
  </Step>

  <Step title="保存">
    点击**保存**。IAM 更改可能需要一分钟才能生效。
  </Step>
</Steps>

### 为什么我看到 "This configuration is for a different Firebase Project"？

当上传的私钥属于不同的 Firebase 项目（不同的 Sender ID）时会出现此错误。

**解决方案**：使用原始 Firebase 项目的私钥。如果无法获得，请联系 `support@onesignal.com` 并提供您的应用 ID。切换项目会重置推送令牌。您的用户必须重新打开应用才能再次接收推送。

### 我可以更改 Sender ID 吗？

可以，但会影响您的现有用户。

设备令牌与原始 Sender ID 绑定。更改它会使现有令牌失效。

<Warning>
  在用户重新打开应用并生成新令牌之前，他们将停止接收推送通知。
</Warning>

如果需要帮助，请联系 `support@onesignal.com` 并提供您的应用 ID。

### 为什么我在 OneSignal 中看不到 Sender ID？

如果您的 Firebase 服务器密钥看起来像 `AIz...`，您可能在使用过时的 Google Cloud Messaging (GCM) 配置。请创建一个新的 Firebase 项目并上传一个服务账户私钥。

### 切换到 FCM V1 时我需要更新代码吗？

不需要应用或 SDK 更改。这仅是控制台更新。

### 切换到 FCM V1 的截止日期是什么时候？

Google 的旧版 FCM API 现已完全弃用。如果您仍在使用旧版 API，**应立即迁移到 FCM V1**。

### 我如何检查哪些应用仍在使用旧版 API？

对每个应用调用[查看应用](/reference/view-an-app) API，并检查响应中的 `fcm_v1_service_account_json` 字段：

* **存在且非空**：应用使用 FCM V1。
* **缺失或为空**：应用未配置 FCM V1。如果该应用发送 Android 推送，则仍在使用旧版 API，必须进行迁移。

要先列出您的应用及其应用 ID，请使用[查看应用列表](/reference/view-apps) API。

<h3 id="what-is-firebase-cloud-messaging-and-why-does-onesignal-need-a-service-account-private-key">
  什么是 Firebase Cloud Messaging，OneSignal 为什么需要服务账户私钥？ \\
</h3>

**Firebase Cloud Messaging (FCM)** 是 Google 用于向 Android 设备发送推送通知的服务。**服务账户**是 OneSignal 用于向您的 Firebase 项目进行身份验证的 Google 身份，其**私钥**是证明该身份的 JSON 文件。上传私钥即授权 OneSignal 代表您通过 Firebase 发送推送。有关更多详细信息，请参阅 [Google 的服务账户文档](https://cloud.google.com/iam/docs/service-account-overview)。

***

## 相关页面

<Columns cols={2}>
  <Card title="移动 SDK 设置" icon="mobile-screen" href="./mobile-sdk-setup">
    在您的 Android 应用中安装并初始化 OneSignal SDK。
  </Card>

  <Card title="移动推送设置" icon="bell" href="./mobile-push-setup">
    针对 Android、iOS 及其他移动平台的平台特定设置步骤。
  </Card>

  <Card title="华为推送设置" icon="mobile" href="./authorize-onesignal-to-send-huawei-push">
    授权 OneSignal 向通过华为应用市场分发的华为应用发送推送。
  </Card>

  <Card title="Web push 设置" icon="globe" href="./web-push-setup">
    为网站配置推送通知。
  </Card>
</Columns>