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

> Understand Firebase Installation ID (FID) registration on Android, how to tell whether it is enabled in your app, and what OneSignal requires.

Firebase Installation ID (FID) registration is a **Firebase** feature, introduced in `firebase-messaging` 25.1.x, that replaces the legacy FCM registration token with a Firebase Installation ID.

It is controlled by a manifest setting named `firebase_messaging_installation_id_enabled`. **This is a Firebase setting, not a OneSignal setting.** OneSignal reads it to decide how to register for push, but does not define it, cannot change it, and cannot apply it to only OneSignal.

> [!WARNING]
>
> `firebase_messaging_installation_id_enabled` applies to your **entire app**. When it is `true`, Firebase disables `getToken()` for every SDK in your process: OneSignal, any other vendor SDK, and your own Firebase code.
>
> Because Android merges manifests from your dependencies, **another SDK can enable it for you.** You may be on this path without having chosen it.

***

## Should you enable it?

FID registration is optional but **recommended**. Google has [deprecated FCM registration tokens](https://firebase.google.com/docs/cloud-messaging/android/client#access-fcm-registration-token) in favor of Firebase Installation IDs, so every app will need to move eventually. Switching keeps your existing users subscribed and receiving messages, and OneSignal keeps sending through your FCM Service Account. Each device will replace the legacy FCM registration token with the new push token value (FID) on its next launch.

### Before you turn it on

Review these before you enable FID registration:

* **Older devices.** FID registration requires Google Play services `261200000` or later. Devices that are already subscribed keep their current push token. New installs on older Android devices, or on devices that don't receive Google Play services updates, can't receive push until Google Play services updates. They show notification\_type status [`-34`](#34-fid-registration-failed).
* **Other push SDKs.** The setting applies to your whole app and disables `getToken()` and `deleteToken()` for every SDK. This mostly affects other SDKs that send push notifications. Check that each one supports Firebase Installation IDs.
* **Push token format.** `OneSignal.User.pushSubscription.token` and `IPushSubscriptionObserver` return a Firebase Installation ID instead of an FCM registration token. The property type does not change, so nothing fails at compile time. Any code that stores, validates, or sends that value as an FCM token breaks without an error.
* **Custom Firebase integrations.** If your app has its own `FirebaseMessagingService`, Firebase calls `onRegistered()` instead of `onNewToken()`. Move your token handling to `onRegistered()`. If your app calls `deleteToken()` (on logout, for example), switch to `unregister()`. OneSignal does not need either callback. See Firebase's [registration via Firebase Installation ID](https://firebase.google.com/docs/cloud-messaging/android/client#enable-registration-via-firebase-installation-id) guide, and [Firebase Messaging SDK conflict](https://documentation.onesignal.com/docs/en/notifications-show-successful-but-are-not-being-shown.md#firebase-messaging-sdk-conflict) for running it alongside OneSignal.
* **Build requirements.** Your app must declare `firebase-messaging` 25.1.2 or later and use `minSdk` 23 or higher. On `firebase-messaging` 26.x, your app needs `minSdk` 24 or higher and Kotlin 2.0.0 or later. See [Requirements](#requirements).
* **Rollback needs a new release.** The setting is part of your app build. Turning it on or off requires a new app build and store release. There is no server-side switch.

***

## Is it enabled in your app?

Check the **merged** manifest, not just your own `AndroidManifest.xml`. A dependency can add this setting without it appearing in your source.

**1. Build the merged manifest**

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

**2. Search the merged output**

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

A grep hit is not enough. Read the merged `android:value`. FID registration is enabled only when that value is boolean `true`.

No `meta-data` entry, or a merged value of `false`, means you are on the legacy token path. To force the value to `false` when a dependency sets it to `true`, see [Disable FID registration](#disable-fid-registration).

When registration fails, the error includes the manifest value, whether a default `FirebaseApp` was found, and whether `register()` is available. A successful registration does not log those three, so [verbose logging](https://documentation.onesignal.com/docs/en/capturing-a-debug-log.md) will not show them on a healthy device. Use the merged manifest to confirm the setting.

> [!NOTE]
>
> **Known SDKs that enable this setting.** Braze Android SDK 43.0.0 and later add `firebase_messaging_installation_id_enabled="true"` through manifest merging. If your app includes Braze 43+, FID registration is enabled whether or not you added the setting yourself.

***

## Enable FID registration

To enable FID registration, give your app its own Firebase configuration, require `firebase-messaging` 25.1.2 or later, and turn on the manifest setting. Then confirm that devices register with a Firebase Installation ID.

### Requirements

FID registration requires all of the following. If any is missing, registration fails with one of the statuses in [Troubleshooting](#troubleshooting).

* **OneSignal Android SDK** `5.11.0` or later, or a wrapper SDK version that includes it. See [Minimum OneSignal SDK versions](#minimum-onesignal-sdk-versions)
* **`com.google.firebase:firebase-messaging`** `25.1.2` or later, declared by your app. Earlier 25.1.x versions have registration bugs, including failures after a backup restore or when app data is cloned
* **Android API 23+** (`firebase-messaging` 25.0.0 raised the minimum from 21 to 23). On `firebase-messaging` 26.x, API 24+ and Kotlin 2.0.0 or later. See [Using firebase-messaging 26.x](#using-firebase-messaging-26-x)
* **Google Play services** version `261200000` or later on the device
* **A default `FirebaseApp` for your own Firebase project.** See [Step 1: Add google-services.json to your app](#step-1-add-google-services-json-to-your-app)
* **Matching Firebase projects.** The project in your `google-services.json` must be the same project as the FCM Service Account uploaded to OneSignal. See [Match your Firebase projects](https://documentation.onesignal.com/docs/en/android-firebase-credentials.md#match-your-firebase-projects)

#### Minimum OneSignal SDK versions

FID registration support shipped in OneSignal Android SDK `5.11.0`. Each wrapper SDK below is the first version that includes it. Older versions only use the legacy token path, so with the setting on, push registration fails on those versions.

| SDK | Minimum version | Notes |
| - | - | - |
| Android (native) | `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` adds the `enableFirebaseInstallationId` prop, which writes the manifest setting for you. Requires a development build. Expo Go is not supported |
| Cordova | `5.6.2` | |
| Capacitor | `1.2.2` | |
| Unity | `5.4.2` | |
| .NET / MAUI | `6.4.2` | |

### Step 1: Add google-services.json to your app

FID registration needs your Firebase project details client side. Download `google-services.json` from the same Firebase project as the FCM Service Account uploaded to OneSignal. If the projects don't match, registration fails with [`-6`](#6-sender-id-mismatch). Add the file to your app, and apply the Google Services Gradle plugin. Where the file goes depends on your app. See [Add your Firebase configuration file](https://documentation.onesignal.com/docs/en/android-firebase-credentials.md#add-your-firebase-configuration-file) for steps. You may already have this.

### Step 2: Declare firebase-messaging 25.1.2 or later

OneSignal compiles against `firebase-messaging` 24.x, which uses `FirebaseMessaging.getToken()` for legacy FCM registration tokens.

FID registration uses `FirebaseMessaging.register()`, which needs `firebase-messaging` 25.1.2 or later.

To upgrade `firebase-messaging`, add this to your app module's Gradle file:

```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]'
```

#### Using firebase-messaging 26.x

The `[25.1.2, 25.99.99]` range keeps your app on 25.x, which has no extra requirements. If your app or another dependency brings in `firebase-messaging` 26.x, Gradle resolves to 26.x, and your app also needs:

* `minSdk` 24 or higher
* Kotlin 2.0.0 or later

Check which version your app resolves:

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

### Step 3: Add the Firebase manifest setting

Add this inside the `<application>` tag of your `AndroidManifest.xml`:

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

On Expo, set `enableFirebaseInstallationId: true` in the `onesignal-expo-plugin` config (version `2.8.0` or later) instead, then run `expo prebuild`.

### Step 4: Verify FID registration

Build and run on a device, then check the **Push Token** in the log or in **Dashboard > Audience > Subscriptions**.

> [!TIP]
>
> Your OneSignal Subscription should be **Subscribed** and the push token should be a short Firebase Installation ID like `cXp9fY-TRFCLSy9kVTqorZ`, not a longer legacy FCM token containing a colon like `dN8Ya5MTR2OO-0BXdqimCI:APA91bFw...`. If the status is negative, see [Troubleshooting](#troubleshooting).

***

## Disable FID registration

Which approach you need depends on where the setting comes from.

> [tab] You added it
>
> Remove the `<meta-data>` element from your `AndroidManifest.xml`, then rebuild.

> [tab] A dependency added it
>
> If the setting arrives through manifest merging, removing your own entry does nothing, because there isn't one. Override the merged value instead. A `false` value with `tools:replace` wins the merge, so a `true` from a dependency never takes effect:
>
> ```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>
> ```
>
> Rebuild and re-check the merged manifest to confirm the value is now `false`.

> [!WARNING]
>
> Disabling FID registration affects every SDK in your app, not just OneSignal. If another SDK depends on FID registration, check its documentation before turning the setting off.

Devices re-register on the next app launch. Existing Subscriptions are preserved and receive a new token value.

***

## Troubleshooting

Find the Subscription in **Dashboard > Audience > Subscriptions** and check its status. Each status below has one cause and one fix.

After you correct the configuration and release a new build, the **same Subscription recovers on a later session**. No reinstall, and no new Subscription is created.

| Status | Meaning | Fix |
| - | - | - |
| `-32` | FID registration is enabled, but your app has no default `FirebaseApp` | [Add Firebase configuration](#32-no-default-firebase-app) |
| `-33` | FID registration is enabled, but `FirebaseMessaging.register()` is unavailable | [Upgrade firebase-messaging](#33-register-api-unavailable) |
| `-34` | FID registration failed, or Google Play services is out of date | [Update Google Play services](#34-fid-registration-failed) |
| `-6` | Sender ID mismatch between your app and OneSignal | [Match your Firebase projects](#6-sender-id-mismatch) |

### -32: No default Firebase app

FID registration requires your app's own default `FirebaseApp`. OneSignal's shared Firebase project cannot produce an installation ID.

Most common causes, in order:

1. **`google-services.json` is missing.** Download it from your [Firebase console](https://console.firebase.google.com/) under **Project settings > Your apps**, and add it to your app. Native Android apps use the `app/` directory. Other platforms use different paths. See [Add your Firebase configuration file](https://documentation.onesignal.com/docs/en/android-firebase-credentials.md#add-your-firebase-configuration-file).
2. **The Google Services Gradle plugin is not applied.** The file alone does nothing. The plugin converts it into the resources Firebase reads at runtime. See [Add your Firebase configuration file](https://documentation.onesignal.com/docs/en/android-firebase-credentials.md#add-your-firebase-configuration-file).
3. **The plugin is applied in the wrong Gradle file.** The `apply` must be in your **app module's** `build.gradle`, not the project-level file.
4. **Programmatic initialization ran too late, or not at all.** If you initialize the default app yourself (for example, because you gate Firebase behind user consent), it must complete before OneSignal initializes. See [Set up Firebase without google-services.json](https://documentation.onesignal.com/docs/en/android-firebase-credentials.md#set-up-firebase-without-google-services-json).

If you did not intend to use FID registration at all, [disable it](#disable-fid-registration) instead.

### -33: register API unavailable

The `FirebaseMessaging.register()` API does not exist in the version of `firebase-messaging` your app resolved, or it was removed from your release build.

1. **Declare `firebase-messaging` 25.1.2 or later.** `register()` first appeared in 25.1.0, and OneSignal compiles against 24.x, so your app has to bring the newer library. Use 25.1.2 or later rather than 25.1.0 or 25.1.1. See [Requirements](#requirements).

2. **Check your resolved version.** Another dependency may be pinning an older one:

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

3. **If this only happens in release builds,** R8 removed or renamed the method. Confirm OneSignal's consumer ProGuard rules are applied and that you have not disabled them.

### -34: FID registration failed

This status is retryable. The SDK tries again on a later session.

1. **Google Play services is out of date.** FID registration requires version `261200000` or later. Below that version, Firebase requests a legacy token instead of registering the installation ID, and that token is never available to your app. The SDK fails rather than reporting a Subscription that cannot receive push. Update Google Play services on the device through the Play Store.
2. **A transient Firebase failure.** No action needed. Registration recovers on a later app launch.

### -6: Sender ID mismatch

Shown in the dashboard as `Invalid Google Project Number`. Your app's Firebase project and the FCM Service Account uploaded to OneSignal are not the same project.

A project mismatch only causes this status with FID registration on. On the legacy token path, the same mismatch does not fail, and the SDK registers through OneSignal's shared Firebase project instead. That is why `-6` can appear right after you enable FID registration, even though push worked before.

Compare the two projects with [Match your Firebase projects](https://documentation.onesignal.com/docs/en/android-firebase-credentials.md#match-your-firebase-projects). If the values differ, either upload the Service Account from the correct Firebase project, or ship the `google-services.json` for the project whose Service Account you uploaded.

> [!WARNING]
>
> Unlike the other statuses, `-6` marks existing Subscriptions invalid. Correct the configuration and release an updated build; devices re-register and return to **Subscribed** on the next launch.

***

## FAQ

### Do I need `google-services.json` even if I don't use FID?

Push works without it today, but you should add it. Adding the file does not turn the manifest setting on. See [What happens if I skip google-services.json?](https://documentation.onesignal.com/docs/en/android-firebase-credentials.md#what-happens-if-i-skip-google-services-json)

### Will my existing Subscriptions be lost?

No. Devices re-register on the next app launch and keep the same Subscription, with a new push token value. This applies in both directions, enabling and disabling. The exception is a Firebase project mismatch, which marks existing Subscriptions invalid until you ship a fix. See [`-6`](#6-sender-id-mismatch).

### Can I enable FID registration for OneSignal only?

No. The setting applies to the whole process and disables `getToken()` for every SDK. Installation ID registration can only use your default `FirebaseApp`. OneSignal's shared app cannot produce that ID.

### Why did my push token change format?

Your app is now registering with a Firebase Installation ID. Installation IDs are short with no colon, like `cXp9fY-TRFCLSy9kVTqorZ`. Legacy FCM tokens are longer and contain a colon, like `dN8Ya5MTR2OO-0BXdqimCI:APA91bFw...`.

***

## Related pages

> [card] [Android Firebase credentials](https://documentation.onesignal.com/docs/en/android-firebase-credentials.md)
>
> Upload your FCM Service Account private key and add `google-services.json` to your app.

> [card] [Android SDK setup](https://documentation.onesignal.com/docs/en/android-sdk-setup.md)
>
> Install and initialize the OneSignal Android SDK.

> [card] [Subscriptions](https://documentation.onesignal.com/docs/en/subscriptions.md)
>
> Look up Subscription statuses, including `-6` and the FID statuses `-32` to `-34`.

> [card] [Capture a debug log](https://documentation.onesignal.com/docs/en/capturing-a-debug-log.md)
>
> Collect verbose SDK logs to see registration errors.


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