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.

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. OneSignal fully supports the legacy FCM token path, and it remains the default. With the setting absent or false, the SDK registers legacy FCM tokens exactly as it always has, and no action is needed.

Enable the manifest setting if:

• Another SDK already requires it, or has enabled it through manifest merging
• You want Firebase’s installation-id registration

Leave the setting off if:

• Push is already working and nothing else in the app requires it
• You cannot require Google Play services 261200000 or later across your install base
• Your app manages its own FCM token lifecycle

Using your own Firebase project without the setting

You do not need FID registration to move OneSignal’s push registration onto your own Firebase project. On OneSignal Android SDK 5.11.0 or later, add google-services.json for the same project as the FCM Service Account uploaded to OneSignal, as described in Add your Firebase configuration file.

The legacy token is then created with your default FirebaseApp instead of OneSignal’s shared app, as long as the default app’s sender ID and the project number in its applicationId both match the sender configured in OneSignal. Adding the file does not turn the manifest setting on.

---

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

   ./gradlew :app:processDebugManifest
   
2. Search the merged output

   grep -r "firebase_messaging_installation_id_enabled" app/build/intermediates/merged_manifests/
   

   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.

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 will not show them on a healthy device. Use the merged manifest to confirm the setting.

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.

---

What changes when it is enabled

	Legacy token path	FID path
Firebase API used	FirebaseMessaging.getToken()	FirebaseMessaging.register()
Firebase app	Your default FirebaseApp, when its sender ID and the project number in its applicationId both match the OneSignal sender. Otherwise OneSignal’s shared Firebase app.	Your default FirebaseApp only. OneSignal’s shared app cannot be used.
google-services.json required	No	Yes
Example value	dN8Ya5MTR2OO-0BXdqimCI:APA91bFw...	cXp9fY-TRFCLSy9kVTqorZ

Message delivery is unaffected when your app is configured correctly. OneSignal continues to send through your FCM Service Account.

With the setting on, Firebase disables deleteToken() the same way it disables getToken(). The call that drops the registration is FirebaseMessaging.getInstance().unregister(). If your app calls unregister() (on logout, for example), it drops the OneSignal push registration too, until the SDK re-registers.

OneSignal.User.pushSubscription.token returns a Firebase Installation ID on this path, not an FCM registration token. The property type does not change, so nothing fails at compile time.

If your own code sends this value to Firebase Cloud Messaging directly, stores it as an FCM token, or validates its format, it will break silently. The same applies to values delivered through IPushSubscriptionObserver.

If your app has its own FirebaseMessagingService: with the setting on, FirebaseMessaging.register() delivers the installation id to FirebaseMessagingService.onRegistered(String). Firebase does not call onNewToken(). If your own service reads the token in onNewToken(), move that work to onRegistered(). OneSignal does not need that callback.

---

Requirements

FID registration requires all of the following. If any is missing, registration fails with one of the statuses in Troubleshooting.

• OneSignal Android SDK 5.11.0 or later
• com.google.firebase:firebase-messaging 25.1.2 or later, declared by your app
• Android API 23+ (firebase-messaging 25.0.0 raised the minimum from 21 to 23)
• Google Play services version 261200000 or later on the device
• A default FirebaseApp for your own Firebase project — either google-services.json plus the com.google.gms.google-services Gradle plugin, as described in Android Firebase credentials, or programmatic initialization
• Matching Firebase projects — the project in your google-services.json must be the same project as the FCM Service Account uploaded to OneSignal. See Verify your Firebase project matches

OneSignal compiles against firebase-messaging 24.x. Adding google-services.json does not upgrade it. Declare com.google.firebase:firebase-messaging:[25.1.2, 25.99.99] in the app module yourself. FirebaseMessaging.register() comes from that version.

Why 25.1.2 and not 25.1.0? register() first appeared in 25.1.0, but two later patches matter: 25.1.1 fixed re-registration when the Firebase installation ID changes, and 25.1.2 fixed registration failures caused by FID_ALREADY_USED, which occurs after a backup restore or when app data is cloned.

Turning FID registration on or off is build-time configuration embedded in the APK. Both enabling it and rolling it back require a new app build and store release — there is no server-side switch, from OneSignal or from Firebase.

---

Enable FID registration

1. Provide a default FirebaseApp

   Your app needs a default FirebaseApp for your own Firebase project. Either follow Add your Firebase configuration file to add google-services.json and apply the Google Services Gradle plugin, or use programmatic initialization.

2. Declare firebase-messaging 25.1.2 or later

   app/build.gradle.kts

   implementation("com.google.firebase:firebase-messaging:[25.1.2, 25.99.99]")
   
3. Add the Firebase manifest setting

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

   AndroidManifest.xml

   <meta-data
       android:name="firebase_messaging_installation_id_enabled"
       android:value="true" />
   
4. Verify

   Build and run on a device, then check the Subscription in Dashboard > Audience > Subscriptions. The status should be Subscribed, and the push token should look like cXp9fY-TRFCLSy9kVTqorZ rather than a longer token containing a colon.

---

Programmatic initialization

If you cannot use the Gradle plugin — or you gate Firebase behind user consent — initialize the default app yourself before OneSignal initializes. Every value must belong to the same Firebase project:

val options = FirebaseOptions.Builder()
    .setProjectId("customer-firebase-project")
    .setApplicationId("1:123456789012:android:abcdef123456")
    .setApiKey("AIza...")
    .setGcmSenderId("123456789012")
    .build()

FirebaseApp.initializeApp(context, options)

A storage bucket is not required for FCM or FID registration. This approach needs neither google-services.json nor the Gradle plugin. If initialization has not completed by the time OneSignal registers, registration fails with -32 and retries on a later session.

---

Verify your Firebase project matches

The Firebase project your app registers against must be the same project as the FCM Service Account uploaded to OneSignal. If they differ, registration fails with -6 and existing Subscriptions are marked invalid.

This applies on the legacy token path too, so the values to compare live with the rest of the google-services.json guidance: Verify your Firebase project matches.

---

Disable FID registration

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

You added it

Remove the <meta-data> element from your AndroidManifest.xml, then rebuild.

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:

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>

Rebuild and re-check the merged manifest to confirm the value is now false.

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
-33	FID registration is enabled, but FirebaseMessaging.register() is unavailable	Upgrade firebase-messaging
-34	FID registration failed, or Google Play services is out of date	Update Google Play services
-6	Sender ID mismatch between your app and OneSignal	Match your Firebase projects

-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 under Project settings > Your apps, and place it in your app/ directory.
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.
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 Programmatic initialization.

If you did not intend to use FID registration at all, disable it 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.

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

   ./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 silently discards the registration, so 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.

Follow Verify your Firebase project matches. 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.

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?

It is not required for push to work. It is recommended for new integrations. On OneSignal Android SDK 5.11.0+, when the default app’s sender ID and the project number in its applicationId both match the OneSignal sender, the legacy token is created with your FirebaseApp instead of OneSignal’s shared app. Adding the file does not turn the manifest setting on. See Add your Firebase configuration file.

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.

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?

Because your app is now registering with a Firebase Installation ID. See What changes when it is enabled.