fix: [SDK-5171] improve Firebase Installation ID configuration errors

[fadi-george]

Description

One Line Summary

Improves Firebase Installation ID configuration diagnostics, tests, and integration documentation.

Details

Motivation

Firebase Installation ID setup failures were reduced to a generic FCM error, leaving developers without actionable remediation and an empty push token.

Scope

• Adds typed FID failure reasons and actionable runtime messages for missing Firebase configuration, unavailable register(), sender mismatch, minification, and registration failures.
• Includes safe detected state in diagnostics.
• Matches Firebase boolean manifest parsing and preserves existing retries for transient FID IO failures.
• Documents Firebase Messaging, minSdk, Google Services, ProGuard, and manifest-merge requirements.
• Updates the demo-only manifest override for transitively enabled FID registration.
• Keeps existing backend notification status compatibility.

Testing

Unit testing

Added coverage for missing default FirebaseApp, unavailable register API, sender mismatch, registration and Installation ID retrieval failures, Firebase manifest-flag semantics, preserved IOExceptions, remediation messages, and push registration status handling.

Manual testing

Validated the demo merged manifest. Device testing was not performed.

Affected code checklist

• Notifications
  • Display
  • Open
  • Push Processing
  • Confirm Deliveries
• Outcomes
• Sessions
• In-App Messaging
• REST API requests
• Public API changes

Checklist

Overview

• I have filled out all REQUIRED sections above
• PR does one thing
• Any Public API changes are explained in the PR details and conform to existing APIs

Testing

• I have included test coverage for these changes, or explained why they are not needed
• All automated tests pass, or I explained why that is not possible
• I have personally tested this on my device, or explained why that is not possible

Final pass

• Code is as readable as possible.
• I have reviewed this PR myself, ensuring it meets each checklist item

[cursor]

Multi-model review (Claude Opus 5, GPT 5.6 Sol, Cursor Grok 4.6) of the net diff vs main (16 files, +1006/−56). Typed FID diagnostics and the ProGuard register() keep are useful; the two follow-ups called out in the PR body are still present.

Act on

• FID IOExceptions are wrapped as FCMInstallationIdException and mapped to retryable -12 (FIREBASE_FCM_ERROR_MISC_EXCEPTION). attemptRegistration returns on the first attempt, so the existing 5-attempt backoff and SERVICE_NOT_AVAILABLE / AUTHENTICATION_FAILED statuses never run on the FID path (3/3).

Consider

• Control flow treats any raw manifest value whose string form is "true" as enabled. Firebase 25.1 and FidEnv use Bundle.getBoolean(), which is false for a String "true" (2/3; Opus treated the raw read as the fix).
• NO_DEFAULT_FIREBASE_APP / REGISTER_API_UNAVAILABLE are permanent config misses but also become retryable -12, so they will not replace a prior success the way sender mismatch does.
• shouldUpdateErrorStatus overwrites a healthy token for every non-retryable status (-7 GMS disabled, -4 missing FCM lib, HMS config errors), not just INVALID_FCM_SENDER_ID.
• Docs require firebase-messaging 25.1.0; the module require range is still [23.0.8, 24.0.99]. The new comment that require is non-strict is incorrect (prefer is the soft constraint).

Noted

• Carry-forwards from #2734/#2735: no onRegistered() FID-rotation bridge; Play Services below 261200000 can make register() a V1 fallback; blank/"null" dashboard sender skips host fallback.
• Mutex around token retrieve is reasonable; pair it with a Tasks.await timeout if registration can stall.

Dismissed

• Demo firebase_messaging_installation_id_enabled=false + tools:replace is the documented override, not a sample of the new path.

  

_{Sent by Cursor Automation: PR Reviews}

[github-actions]

📊 Diff Coverage Report

Diff Coverage Report (Changed Lines Only)

Gate: aggregate coverage on changed executable lines must be ≥ 80% (JaCoCo line data for lines touched in the diff).

Changed Files Coverage

• PushTokenManager.kt: 9/10 touched executable lines (90.0%) (12 touched lines in diff)
• IPushRegistrator.kt: 5/5 touched executable lines (100.0%) (5 touched lines in diff)
• PushRegistratorAbstractGoogle.kt: 8/8 touched executable lines (100.0%) (13 touched lines in diff)
• PushRegistratorFCM.kt: 65/67 touched executable lines (97.0%) (111 touched lines in diff)

Overall (aggregate gate)

87/90 touched executable lines covered (96.7% — requires ≥ 80%)

📥 View workflow run

[nan-li]

LGTM. Traced the three Cursor fixes through the final code and they hold: FID IOExceptions reach the existing retry loop, the flag is read the way Firebase reads it, and a healthy token now survives everything except a sender mismatch.

One nit, not blocking: the string "true" case only tests the provider with a prebuilt InstallationIdFlag, not installationIdFlag() itself. A PushRegistratorFCMTests case that puts a String "true" into the manifest Bundle and asserts the legacy token path would cover the real Bundle.getBoolean behavior Cursor flagged.

[abdulraqeeb33]

Nits only.

1. The -6 wipe also covers the missing-sender early return, not just a detected mismatch.
2. Log exception.message on sender mismatch, same as the FID error helper.

[fadi-george]

Addressed the remaining review nits in 312c9a8: token invalidation now requires a confirmed sender mismatch, mismatch logging uses the actionable exception message, and the string-valued manifest flag is covered through PushRegistratorFCM with a real Bundle.