Firebase Installation ID 注册

Firebase Installation ID（FID）注册是 firebase-messaging 25.1.x 中引入的 Firebase 功能，它用 Firebase Installation ID 取代旧版 FCM 注册令牌。它由名为 firebase_messaging_installation_id_enabled 的清单设置控制。这是 Firebase 设置，而不是 OneSignal 设置。 OneSignal 会读取它来决定如何注册推送，但不会定义它、无法更改它，也无法仅将其应用于 OneSignal。

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

您应该启用它吗？ \

FID 注册是可选的，但建议启用。Google 已弃用 FCM 注册令牌，转而使用 Firebase Installation ID，因此所有应用最终都需要迁移。切换后，现有用户会保持订阅并继续接收消息，OneSignal 也会继续通过您的 FCM 服务账户发送。每台设备会在下次启动时用新的推送令牌值（FID）替换旧版 FCM 注册令牌。

启用之前 \

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

旧设备。 FID 注册需要 Google Play 服务 261200000 或更高版本。已订阅的设备会保留当前的推送令牌。在旧 Android 设备上，或在不接收 Google Play 服务更新的设备上进行的新安装，在 Google Play 服务更新之前无法接收推送。这些设备会显示 notification_type 状态 -34。
其他推送 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 注册指南，以及与 OneSignal 一起使用时的 Firebase Messaging SDK 冲突。
构建要求。 您的应用必须声明 firebase-messaging 25.1.2 或更高版本，并使用 minSdk 23 或更高。使用 firebase-messaging 26.x 时，您的应用需要 minSdk 24 或更高，以及 Kotlin 2.0.0 或更高版本。请参阅要求。
回滚需要发布新版本。 该设置是应用构建的一部分。开启或关闭它都需要新的应用构建和商店发布。没有服务器端开关。

您的应用是否已启用？ \

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

构建合并后的清单

./gradlew :app:processDebugManifest

搜索合并后的输出

grep -r "firebase_messaging_installation_id_enabled" app/build/intermediates/ --include=AndroidManifest.xml

grep 命中并不足够。请读取合并后的 android:value。只有当该值为布尔值 true 时，FID 注册才会启用。没有 meta-data 条目，或合并后的值为 false，表示您处于旧版令牌路径。若要在依赖项将其设为 true 时强制将值设为 false，请参阅停用 FID 注册。

注册失败时，错误中会包含清单值、是否找到默认 FirebaseApp，以及 register() 是否可用。注册成功时不会记录这三项，因此在正常设备上，详细日志不会显示它们。请使用合并后的清单来确认该设置。

已知会启用此设置的 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 注册需要满足以下所有条件。缺少任何一项，注册都会失败，并显示故障排除中的某个状态。

OneSignal Android SDK 5.11.0 或更高版本，或包含它的封装 SDK 版本。请参阅最低 OneSignal SDK 版本
由您的应用声明的 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
设备上的 Google Play 服务版本 261200000 或更高
您自己的 Firebase 项目的默认 FirebaseApp。 请参阅第 1 步：将 google-services.json 添加到您的应用
匹配的 Firebase 项目。 您的 google-services.json 中的项目必须与上传到 OneSignal 的 FCM 服务账户属于同一项目。请参阅匹配您的 Firebase 项目

最低 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。将文件添加到您的应用，并应用 Google Services Gradle 插件。文件的位置取决于您的应用。具体步骤请参阅添加您的 Firebase 配置文件。您可能已经完成了这一步。

第 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 文件中：

implementation("com.google.firebase:firebase-messaging:[25.1.2, 25.99.99]")

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 或更高版本

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

./gradlew :app:dependencies --configuration releaseRuntimeClasspath | grep firebase-messaging

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

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

AndroidManifest.xml

<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。

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

停用 FID 注册 \

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

由您添加
由依赖项添加

从您的 AndroidManifest.xml 中删除 <meta-data> 元素，然后重新构建。

如果该设置是通过清单合并引入的，删除您自己的条目不会有任何作用，因为根本没有这样的条目。请改为覆盖合并后的值。带有 tools:replace 的 false 值会在合并中胜出，因此依赖项中的 true 永远不会生效：

AndroidManifest.xml

<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。

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

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

故障排除 \

在 Dashboard > Audience > Subscriptions 中找到该 Subscription 并检查其状态。下面每个状态都对应一个原因和一个修复方法。在您修正配置并发布新构建后，同一个 Subscription 会在之后的会话中恢复。无需重新安装，也不会创建新的 Subscription。

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

-32：没有默认 Firebase 应用 \

FID 注册需要您应用自己的默认 FirebaseApp。OneSignal 的共享 Firebase 项目无法生成 installation ID。最常见的原因（按顺序）：

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

如果您本来就不打算使用 FID 注册，请改为停用它。

-33：register API 不可用 \

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

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

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

./gradlew :app:dependencies --configuration releaseRuntimeClasspath | grep firebase-messaging

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

-34：FID 注册失败 \

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

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

-6：Sender ID 不匹配 \

在控制台中显示为 Invalid Google Project Number。您应用的 Firebase 项目与上传到 OneSignal 的 FCM 服务账户不是同一个项目。只有在启用 FID 注册时，项目不匹配才会导致此状态。在旧版令牌路径上，同样的不匹配不会失败，SDK 会改为通过 OneSignal 的共享 Firebase 项目注册。这就是为什么即使之前推送正常，-6 也可能在您启用 FID 注册后立即出现。使用匹配您的 Firebase 项目比较这两个项目。如果值不同，请上传正确 Firebase 项目的服务账户，或在应用中附带与您所上传服务账户同一项目的 google-services.json。

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

常见问题

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

目前没有它推送也能工作，但您应该添加它。添加该文件不会开启清单设置。请参阅如果跳过 google-services.json 会怎样？

我现有的 Subscription 会丢失吗？ \

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

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

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

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

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

Android Firebase 凭据

上传您的 FCM 服务账户私钥，并将 google-services.json 添加到您的应用。

Android SDK 设置

安装并初始化 OneSignal Android SDK。

Subscriptions

查看 Subscription 状态，包括 -6 和 FID 状态 -32 至 -34。

捕获调试日志

收集详细的 SDK 日志以查看注册错误。

开发者文档

移动SDK

网络 SDK

实时活动

桌面和手表设置

您应该启用它吗？ \

启用之前 \

您的应用是否已启用？ \

启用 FID 注册 \

要求 \

最低 OneSignal SDK 版本 \

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

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

使用 firebase-messaging 26.x \

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

第 4 步：验证 FID 注册 \

停用 FID 注册 \

故障排除 \

-32：没有默认 Firebase 应用 \

-33：register API 不可用 \

-34：FID 注册失败 \

-6：Sender ID 不匹配 \

常见问题

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

我现有的 Subscription 会丢失吗？ \

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

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

相关页面

Android Firebase 凭据

Android SDK 设置

Subscriptions

捕获调试日志

​您应该启用它吗？ \

​启用之前 \

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

​启用 FID 注册 \

​要求 \

​最低 OneSignal SDK 版本 \

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

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

​使用 firebase-messaging 26.x \

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

​第 4 步：验证 FID 注册 \

​停用 FID 注册 \

​故障排除 \

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

​-33：register API 不可用 \

​-34：FID 注册失败 \

​-6：Sender ID 不匹配 \

​常见问题

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

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

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

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

​相关页面

Android Firebase 凭据

Android SDK 设置

Subscriptions

捕获调试日志

您应该启用它吗？ \

启用之前 \

您的应用是否已启用？ \

启用 FID 注册 \

要求 \

最低 OneSignal SDK 版本 \

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

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

使用 firebase-messaging 26.x \

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

第 4 步：验证 FID 注册 \

停用 FID 注册 \

故障排除 \

-32：没有默认 Firebase 应用 \

-33：register API 不可用 \

-34：FID 注册失败 \

-6：Sender ID 不匹配 \

常见问题

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

我现有的 Subscription 会丢失吗？ \

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

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

相关页面