> ## 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.

# Firebase Installation ID 注册

> 了解 Android 上的 Firebase Installation ID（FID）注册、如何判断您的应用是否已启用它，以及 OneSignal 的要求。

Firebase Installation ID（FID）注册是 `firebase-messaging` 25.1.x 中引入的 **Firebase** 功能，它用 Firebase Installation ID 取代旧版 FCM 注册令牌。

它由名为 `firebase_messaging_installation_id_enabled` 的清单设置控制。**这是 Firebase 设置，而不是 OneSignal 设置。** OneSignal 会读取它来决定如何注册推送，但不会定义它、无法更改它，也无法仅将其应用于 OneSignal。

> [!WARNING]
>
> `firebase_messaging_installation_id_enabled` 适用于您的**整个应用**。当它为 `true` 时，Firebase 会为您进程中的所有 SDK 停用 `getToken()`：包括 OneSignal、任何其他第三方 SDK 以及您自己的 Firebase 代码。
>
> 由于 Android 会合并依赖项的清单，**其他 SDK 可能会替您启用它。** 即使您没有主动选择，也可能已经在使用此路径。

***

## 您应该启用它吗？ \\

FID 注册是可选的，但**建议启用**。Google 已[弃用 FCM 注册令牌](https://firebase.google.com/docs/cloud-messaging/android/client#access-fcm-registration-token)，转而使用 Firebase Installation ID，因此所有应用最终都需要迁移。切换后，现有用户会保持订阅并继续接收消息，OneSignal 也会继续通过您的 FCM 服务账户发送。每台设备会在下次启动时用新的推送令牌值（FID）替换旧版 FCM 注册令牌。

### 启用之前 \\

在启用 FID 注册之前，请检查以下事项：

* **旧设备。** FID 注册需要 Google Play 服务 `261200000` 或更高版本。已订阅的设备会保留当前的推送令牌。在旧 Android 设备上，或在不接收 Google Play 服务更新的设备上进行的新安装，在 Google Play 服务更新之前无法接收推送。这些设备会显示 notification\_type 状态 [`-34`](#34-fid-registration-failed)。
* **其他推送 SDK。** 该设置适用于整个应用，并会为所有 SDK 停用 `getToken()` 和 `deleteToken()`。这主要影响其他发送推送通知的 SDK。请确认每个 SDK 都支持 Firebase Installation ID。
* **推送令牌格式。** `OneSignal.User.pushSubscription.token` 和 `IPushSubscriptionObserver` 返回的是 Firebase Installation ID，而不是 FCM 注册令牌。属性类型不变，因此编译时不会失败。任何将该值作为 FCM 令牌进行存储、验证或发送的代码都会在没有报错的情况下失效。
* **自定义 Firebase 集成。** 如果您的应用有自己的 `FirebaseMessagingService`，Firebase 会调用 `onRegistered()` 而不是 `onNewToken()`。请将令牌处理逻辑移至 `onRegistered()`。如果您的应用会调用 `deleteToken()`（例如在退出登录时），请改用 `unregister()`。OneSignal 不需要这两个回调。请参阅 Firebase 的[通过 Firebase Installation ID 注册](https://firebase.google.com/docs/cloud-messaging/android/client#enable-registration-via-firebase-installation-id)指南，以及与 OneSignal 一起使用时的 [Firebase Messaging SDK 冲突](https://documentation.onesignal.com/docs/cn/notifications-show-successful-but-are-not-being-shown.md#firebase-messaging-sdk-conflict)。
* **构建要求。** 您的应用必须声明 `firebase-messaging` 25.1.2 或更高版本，并使用 `minSdk` 23 或更高。使用 `firebase-messaging` 26.x 时，您的应用需要 `minSdk` 24 或更高，以及 Kotlin 2.0.0 或更高版本。请参阅[要求](#requirements)。
* **回滚需要发布新版本。** 该设置是应用构建的一部分。开启或关闭它都需要新的应用构建和商店发布。没有服务器端开关。

***

## 您的应用是否已启用？ \\

请检查**合并后**的清单，而不仅仅是您自己的 `AndroidManifest.xml`。依赖项可能会添加此设置，而它不会出现在您的源代码中。

**1. 构建合并后的清单**

```bash theme={null}
./gradlew :app:processDebugManifest
```

**2. 搜索合并后的输出**

```bash theme={null}
grep -r "firebase_messaging_installation_id_enabled" app/build/intermediates/ --include=AndroidManifest.xml
```

grep 命中并不足够。请读取合并后的 `android:value`。只有当该值为布尔值 `true` 时，FID 注册才会启用。

没有 `meta-data` 条目，或合并后的值为 `false`，表示您处于旧版令牌路径。若要在依赖项将其设为 `true` 时强制将值设为 `false`，请参阅[停用 FID 注册](#disable-fid-registration)。

注册失败时，错误中会包含清单值、是否找到默认 `FirebaseApp`，以及 `register()` 是否可用。注册成功时不会记录这三项，因此在正常设备上，[详细日志](https://documentation.onesignal.com/docs/cn/capturing-a-debug-log.md)不会显示它们。请使用合并后的清单来确认该设置。

> [!NOTE]
>
> **已知会启用此设置的 SDK。** Braze Android SDK 43.0.0 及更高版本会通过清单合并添加 `firebase_messaging_installation_id_enabled="true"`。如果您的应用包含 Braze 43+，无论您是否自行添加了该设置，FID 注册都会启用。

***

## 启用 FID 注册 \\

要启用 FID 注册，请为您的应用提供自己的 Firebase 配置，要求 `firebase-messaging` 25.1.2 或更高版本，并开启清单设置。然后确认设备使用 Firebase Installation ID 完成注册。

### 要求 \\

FID 注册需要满足以下所有条件。缺少任何一项，注册都会失败，并显示[故障排除](#troubleshooting)中的某个状态。

* **OneSignal Android SDK** `5.11.0` 或更高版本，或包含它的封装 SDK 版本。请参阅[最低 OneSignal SDK 版本](#minimum-onesignal-sdk-versions)
* 由您的应用声明的 **`com.google.firebase:firebase-messaging`** `25.1.2` 或更高版本。较早的 25.1.x 版本存在注册缺陷，包括在恢复备份后或克隆应用数据时失败
* **Android API 23+**（`firebase-messaging` 25.0.0 将最低版本从 21 提高到 23）。使用 `firebase-messaging` 26.x 时，需要 API 24+ 和 Kotlin 2.0.0 或更高版本。请参阅[使用 firebase-messaging 26.x](#using-firebase-messaging-26-x)
* 设备上的 **Google Play 服务**版本 `261200000` 或更高
* **您自己的 Firebase 项目的默认 `FirebaseApp`。** 请参阅[第 1 步：将 google-services.json 添加到您的应用](#step-1-add-google-services-json-to-your-app)
* **匹配的 Firebase 项目。** 您的 `google-services.json` 中的项目必须与上传到 OneSignal 的 FCM 服务账户属于同一项目。请参阅[匹配您的 Firebase 项目](https://documentation.onesignal.com/docs/cn/android-firebase-credentials.md#match-your-firebase-projects)

#### 最低 OneSignal SDK 版本 \\

FID 注册支持随 OneSignal Android SDK `5.11.0` 发布。下表中的每个封装 SDK 版本都是首个包含该支持的版本。更早的版本只使用旧版令牌路径，因此在开启该设置时，这些版本上的推送注册会失败。

| SDK | 最低版本 | 备注 |
| - | - | - |
| Android（原生） | `5.11.0` | |
| Flutter | `5.7.2` | |
| React Native | `5.5.16` | |
| Expo | `react-native-onesignal` `5.5.16` | `onesignal-expo-plugin` `2.8.0` 新增了 `enableFirebaseInstallationId` 属性，可替您写入清单设置。需要开发构建。不支持 Expo Go |
| Cordova | `5.6.2` | |
| Capacitor | `1.2.2` | |
| Unity | `5.4.2` | |
| .NET / MAUI | `6.4.2` | |

### 第 1 步：将 google-services.json 添加到您的应用 \\

FID 注册需要在客户端获取您的 Firebase 项目详情。请从与上传到 OneSignal 的 FCM 服务账户相同的 Firebase 项目下载 `google-services.json`。如果项目不匹配，注册会失败并显示 [`-6`](#6-sender-id-mismatch)。将文件添加到您的应用，并应用 Google Services Gradle 插件。文件的位置取决于您的应用。具体步骤请参阅[添加您的 Firebase 配置文件](https://documentation.onesignal.com/docs/cn/android-firebase-credentials.md#add-your-firebase-configuration-file)。您可能已经完成了这一步。

### 第 2 步：声明 firebase-messaging 25.1.2 或更高版本 \\

OneSignal 基于 `firebase-messaging` 24.x 编译，该版本使用 `FirebaseMessaging.getToken()` 获取旧版 FCM 注册令牌。

FID 注册使用 `FirebaseMessaging.register()`，这需要 `firebase-messaging` 25.1.2 或更高版本。

要升级 `firebase-messaging`，请将以下内容添加到应用模块的 Gradle 文件中：

```kotlin app/build.gradle.kts theme={null}
implementation("com.google.firebase:firebase-messaging:[25.1.2, 25.99.99]")
```

```groovy app/build.gradle theme={null}
implementation 'com.google.firebase:firebase-messaging:[25.1.2, 25.99.99]'
```

#### 使用 firebase-messaging 26.x \\

`[25.1.2, 25.99.99]` 范围会让您的应用保持在没有额外要求的 25.x 上。如果您的应用或其他依赖项引入了 `firebase-messaging` 26.x，Gradle 会解析为 26.x，您的应用还需要：

* `minSdk` 24 或更高
* Kotlin 2.0.0 或更高版本

检查您的应用解析到的版本：

```bash theme={null}
./gradlew :app:dependencies --configuration releaseRuntimeClasspath | grep firebase-messaging
```

### 第 3 步：添加 Firebase 清单设置 \\

在 `AndroidManifest.xml` 的 `<application>` 标签内添加以下内容：

```xml AndroidManifest.xml theme={null}
<meta-data
    android:name="firebase_messaging_installation_id_enabled"
    android:value="true" />
```

在 Expo 上，请改为在 `onesignal-expo-plugin` 配置（版本 `2.8.0` 或更高）中设置 `enableFirebaseInstallationId: true`，然后运行 `expo prebuild`。

### 第 4 步：验证 FID 注册 \\

在设备上构建并运行，然后在日志或 **Dashboard > Audience > Subscriptions** 中检查 **Push Token**。

> [!TIP]
>
> 您的 OneSignal Subscription 应为 **Subscribed**，推送令牌应是类似 `cXp9fY-TRFCLSy9kVTqorZ` 的简短 Firebase Installation ID，而不是类似 `dN8Ya5MTR2OO-0BXdqimCI:APA91bFw...` 这样包含冒号的较长旧版 FCM 令牌。如果状态为负数，请参阅[故障排除](#troubleshooting)。

***

## 停用 FID 注册 \\

所需方法取决于该设置的来源。

> [tab] 由您添加
>
> 从您的 `AndroidManifest.xml` 中删除 `<meta-data>` 元素，然后重新构建。

> [tab] 由依赖项添加
>
> 如果该设置是通过清单合并引入的，删除您自己的条目不会有任何作用，因为根本没有这样的条目。请改为覆盖合并后的值。带有 `tools:replace` 的 `false` 值会在合并中胜出，因此依赖项中的 `true` 永远不会生效：
>
> ```xml AndroidManifest.xml theme={null}
> <manifest xmlns:android="http://schemas.android.com/apk/res/android"
>     xmlns:tools="http://schemas.android.com/tools">
>
>     <application>
>         <meta-data
>             android:name="firebase_messaging_installation_id_enabled"
>             android:value="false"
>             tools:replace="android:value" />
>     </application>
> </manifest>
> ```
>
> 重新构建，并再次检查合并后的清单，确认该值现在为 `false`。

> [!WARNING]
>
> 停用 FID 注册会影响您应用中的所有 SDK，而不仅仅是 OneSignal。如果其他 SDK 依赖 FID 注册，请在关闭该设置前查阅其文档。

设备会在下次启动应用时重新注册。现有 Subscription 会保留，并获得新的令牌值。

***

## 故障排除 \\

在 **Dashboard > Audience > Subscriptions** 中找到该 Subscription 并检查其状态。下面每个状态都对应一个原因和一个修复方法。

在您修正配置并发布新构建后，**同一个 Subscription 会在之后的会话中恢复**。无需重新安装，也不会创建新的 Subscription。

| 状态 | 含义 | 修复方法 |
| - | - | - |
| `-32` | 已启用 FID 注册，但您的应用没有默认 `FirebaseApp` | [添加 Firebase 配置](#32-no-default-firebase-app) |
| `-33` | 已启用 FID 注册，但 `FirebaseMessaging.register()` 不可用 | [升级 firebase-messaging](#33-register-api-unavailable) |
| `-34` | FID 注册失败，或 Google Play 服务已过时 | [更新 Google Play 服务](#34-fid-registration-failed) |
| `-6` | 您的应用与 OneSignal 之间的 Sender ID 不匹配 | [匹配您的 Firebase 项目](#6-sender-id-mismatch) |

### -32：没有默认 Firebase 应用 \\

FID 注册需要您应用自己的默认 `FirebaseApp`。OneSignal 的共享 Firebase 项目无法生成 installation ID。

最常见的原因（按顺序）：

1. **缺少 `google-services.json`。** 请从 [Firebase 控制台](https://console.firebase.google.com/)的 **Project settings > Your apps** 下载它，并添加到您的应用。原生 Android 应用使用 `app/` 目录。其他平台使用不同的路径。请参阅[添加您的 Firebase 配置文件](https://documentation.onesignal.com/docs/cn/android-firebase-credentials.md#add-your-firebase-configuration-file)。
2. **未应用 Google Services Gradle 插件。** 仅有文件不会起任何作用。插件会将其转换为 Firebase 在运行时读取的资源。请参阅[添加您的 Firebase 配置文件](https://documentation.onesignal.com/docs/cn/android-firebase-credentials.md#add-your-firebase-configuration-file)。
3. **插件应用在错误的 Gradle 文件中。** `apply` 必须位于**应用模块**的 `build.gradle` 中，而不是项目级文件中。
4. **以编程方式初始化运行得太晚，或根本没有运行。** 如果您自行初始化默认应用（例如因为您在用户同意后才加载 Firebase），它必须在 OneSignal 初始化之前完成。请参阅[不使用 google-services.json 设置 Firebase](https://documentation.onesignal.com/docs/cn/android-firebase-credentials.md#set-up-firebase-without-google-services-json)。

如果您本来就不打算使用 FID 注册，请改为[停用它](#disable-fid-registration)。

### -33：register API 不可用 \\

您的应用解析到的 `firebase-messaging` 版本中不存在 `FirebaseMessaging.register()` API，或者它已从您的发布构建中被移除。

1. **声明 `firebase-messaging` 25.1.2 或更高版本。** `register()` 首次出现在 25.1.0 中，而 OneSignal 基于 24.x 编译，因此您的应用必须引入较新的库。请使用 25.1.2 或更高版本，而不是 25.1.0 或 25.1.1。请参阅[要求](#requirements)。

2. **检查解析到的版本。** 其他依赖项可能固定了较旧的版本：

   ```bash theme={null}
   ./gradlew :app:dependencies --configuration releaseRuntimeClasspath | grep firebase-messaging
   ```

3. **如果仅在发布构建中出现，** 说明 R8 移除或重命名了该方法。请确认 OneSignal 的消费者 ProGuard 规则已应用，并且您没有停用它们。

### -34：FID 注册失败 \\

此状态可以重试。SDK 会在之后的会话中再次尝试。

1. **Google Play 服务已过时。** FID 注册需要版本 `261200000` 或更高。低于该版本时，Firebase 会请求旧版令牌而不是注册 installation ID，而该令牌永远不会提供给您的应用。SDK 会直接失败，而不是报告一个无法接收推送的 Subscription。请通过 Play 商店更新设备上的 Google Play 服务。
2. **临时性的 Firebase 故障。** 无需任何操作。注册会在之后启动应用时恢复。

### -6：Sender ID 不匹配 \\

在控制台中显示为 `Invalid Google Project Number`。您应用的 Firebase 项目与上传到 OneSignal 的 FCM 服务账户不是同一个项目。

只有在启用 FID 注册时，项目不匹配才会导致此状态。在旧版令牌路径上，同样的不匹配不会失败，SDK 会改为通过 OneSignal 的共享 Firebase 项目注册。这就是为什么即使之前推送正常，`-6` 也可能在您启用 FID 注册后立即出现。

使用[匹配您的 Firebase 项目](https://documentation.onesignal.com/docs/cn/android-firebase-credentials.md#match-your-firebase-projects)比较这两个项目。如果值不同，请上传正确 Firebase 项目的服务账户，或在应用中附带与您所上传服务账户同一项目的 `google-services.json`。

> [!WARNING]
>
> 与其他状态不同，`-6` 会将现有 Subscription 标记为无效。请修正配置并发布更新后的构建；设备会在下次启动时重新注册并恢复为 **Subscribed**。

***

## 常见问题

### 即使不使用 FID，我也需要 `google-services.json` 吗？ \\

目前没有它推送也能工作，但您应该添加它。添加该文件不会开启清单设置。请参阅[如果跳过 google-services.json 会怎样？](https://documentation.onesignal.com/docs/cn/android-firebase-credentials.md#what-happens-if-i-skip-google-services-json)

### 我现有的 Subscription 会丢失吗？ \\

不会。设备会在下次启动应用时重新注册，并保留同一个 Subscription，同时获得新的推送令牌值。无论启用还是停用都是如此。例外情况是 Firebase 项目不匹配，在您发布修复之前，它会将现有 Subscription 标记为无效。请参阅 [`-6`](#6-sender-id-mismatch)。

### 我可以只为 OneSignal 启用 FID 注册吗？ \\

不可以。该设置适用于整个进程，并会为所有 SDK 停用 `getToken()`。installation ID 注册只能使用您的默认 `FirebaseApp`。OneSignal 的共享应用无法生成该 ID。

### 为什么我的推送令牌格式变了？ \\

您的应用现在使用 Firebase Installation ID 进行注册。Installation ID 较短且不含冒号，例如 `cXp9fY-TRFCLSy9kVTqorZ`。旧版 FCM 令牌较长且包含冒号，例如 `dN8Ya5MTR2OO-0BXdqimCI:APA91bFw...`。

***

## 相关页面

> [card] [Android Firebase 凭据](https://documentation.onesignal.com/docs/cn/android-firebase-credentials.md)
>
> 上传您的 FCM 服务账户私钥，并将 `google-services.json` 添加到您的应用。

> [card] [Android SDK 设置](https://documentation.onesignal.com/docs/cn/android-sdk-setup.md)
>
> 安装并初始化 OneSignal Android SDK。

> [card] [Subscriptions](https://documentation.onesignal.com/docs/cn/subscriptions.md)
>
> 查看 Subscription 状态，包括 `-6` 和 FID 状态 `-32` 至 `-34`。

> [card] [捕获调试日志](https://documentation.onesignal.com/docs/cn/capturing-a-debug-log.md)
>
> 收集详细的 SDK 日志以查看注册错误。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.