firebase_phone_auth_handler 2.0.1

An easy-to-use firebase phone authentication package to easily send and verify OTP's with auto-fetch OTP support via SMS. Supports web out of the box.

2.0.1 - 2026-08-08

• Maintenance release; no user-facing changes.

2.0.0 - 2026-08-08

• BREAKING: Updated firebase_auth to ^6.5.6. This package re-exports firebase_auth, so its breaking changes apply here too.
• BREAKING: Raised the minimum SDK to Dart 3.8 / Flutter 3.32, as required by firebase_auth 6.
• BREAKING: iOS apps now need a minimum deployment target of 15.0. firebase_auth 6 pulls in Firebase 12, whose firebase-auth and firebase-core packages require iOS 15. Raise IPHONEOS_DEPLOYMENT_TARGET (and the platform :ios line in your Podfile, if you still use CocoaPods) or the build fails with a "Target Integrity" error.
• BREAKING: Added controller.otpSendStatus, an OtpSendStatus enum (idle, sending, sent, failed), as the single source of truth for the send operation. codeSent and isSendingCode remain as convenience shorthands, now derived from it. The one break is that codeSent is a getter rather than a settable field, so any code assigning to it will no longer compile — assigning to it always desynced the controller from reality.
• BREAKING: Fixed isSendingCode reporting true for a controller that had never sent anything. It was defined as !codeSent, so two booleans could not express "idle" or "failed" — a UI gated on it showed a "sending OTP" loader that never cleared when sendOtpOnInitialize was false or when a send failed. Switch on otpSendStatus to tell those states apart.
• BREAKING: Removed FirebasePhoneAuthProvider. FirebasePhoneAuthHandler creates and owns its own controller, so delete the widget from your tree — usually it wrapped MaterialApp. Each handler now gets a fresh controller that is disposed when the handler unmounts, so a verification session can no longer leak into the next screen and two handlers mounted at once can no longer overwrite each other's state. The one capability removed is reading the controller from a widget that is not inside a handler, since there is no app-wide instance any more; use the controller passed to builder, or context.watch<FirebasePhoneAuthController>() from within it.
• BREAKING: Removed controller.clear(). It existed only to reset the shared app-wide controller between handlers, which no longer happens — disposal now handles teardown. Calling it left the controller without a phone number and therefore unusable, so it was a footgun rather than a useful reset.
• BREAKING: FirebasePhoneAuthHandler.signOut() no longer takes a BuildContext. It resolved the controller through the provider only to reach FirebaseAuth.instance.signOut(). Drop the argument, or pass auth: when using a secondary Firebase app.
• Added an auth parameter to FirebasePhoneAuthHandler, so you can authenticate against a secondary FirebaseApp rather than the default one. It also gives tests a seam to inject a fake instead of reaching the real SDK. The instance is resolved lazily, so constructing a controller still never requires Firebase.initializeApp.
• Exported OnLoginSuccess, OnLoginFailed and OnError. They appear in the public API but were not reachable, so callers could not name them.
• Added a codeSendTimeout argument to sendOTP, defaulting to 60 seconds. Firebase does not guarantee that it calls back at all — when device verification cannot complete (for example on Android with no SHA-1 registered and no reCAPTCHA site key configured for the project) neither codeSent nor verificationFailed ever fires, and the controller previously stayed in "sending" forever behind a loader that never cleared. On timeout otpSendStatus becomes failed, onError receives a TimeoutException explaining the likely cause, and sendOTP returns false. Pass null to wait indefinitely.
• Updated provider to ^6.1.5+1.
• Fixed onLoginFailed being called twice for a single failure when phone number verification failed and sendOTP was awaiting the code send.
• Fixed autoRetrievalTimeOutDuration and otpExpirationDuration leaking between handlers. They were held in static fields, so mounting a second handler overwrote the first one's durations.
• Fixed the OTP expiration and auto-retrieval timers not being cancelled when a new OTP was requested. The previous timers kept firing for the lifetime of the app and each resend added another pair.
• Fixed an unhandled asynchronous error when verification failed and sendOTP was called with shouldAwaitCodeSend set to false.
• Fixed instant verification being reported as a failure. When firebase resolves a number without sending an SMS, verificationCompleted fires but codeSent may not, so the code-send timeout kept running and would later flip a successful login to failed — and an awaiting sendOTP would hang until it did.
• Fixed otpSendStatus not rebuilding listeners when it changed to sent — three of the four places that set it were assigning the field directly instead of going through the notifying setter, so a widget switching on otpSendStatus could miss the transition out of sending.
• The controller now cancels its timers when it is disposed, and no longer notifies listeners after disposal.
• Controller teardown now happens in the handler's dispose rather than deactivate, so a live verification session is no longer wiped when the widget is merely moved within the tree.
• linkWithExistingUser now reports a descriptive error when no user is signed in, instead of a bare null check failure.
• Added a test suite covering controller state and widget wiring.
• Added Android and iOS setup sections to the README. Android covers the SHA-1/SHA-256 certificate fingerprints that phone auth requires (including the Play App Signing key, which is easy to miss and breaks phone auth only once the app is live) and what the missing-fingerprint failure looks like. iOS covers the custom URL scheme that phone auth requires, the deep-linking interaction that otherwise pushes a bogus /link?deep_link_id=... route over your OTP screen, the iOS 15 deployment target, and how to test on the simulator.
• Updated the example app for current Flutter APIs (DialogThemeData, AppBarTheme.backgroundColor) and bumped its dependencies.
• Modernised the example's Android build (Gradle 8.14.5, AGP 8.13.0, Kotlin 2.3.20, Java 11) and removed a hand-pinned 2022 Firebase BoM that conflicted with the version firebase_auth 6 resolves. If your own project is still on an older Gradle or AGP, expect to make the same move — Flutter 3.32+ requires Gradle 8.7 or newer, and warns below 8.14.
• Added a screenshot to the package listing, so pub.dev now shows a thumbnail in search results and a gallery on the package page.
• README: the screenshots are now served from this repository instead of GitHub's attachment CDN, which was outside the repo's control and could have gone stale.
• Consolidated the screenshot assets into one screenshots/ folder — screenshots/published/ (ships, referenced by pubspec's screenshots:) and screenshots/unpublished/ (README-only, excluded via a .pubignore covering the whole folder rather than naming files, so a future addition there is excluded by default instead of shipping if someone forgets to list it). They previously lived split across pub_screenshots/ and .github/assets/. Verified with pub publish --dry-run that the published folder is archived and the unpublished one is not.
• README: dropped the popularity badge, which had stopped rendering, and the code size one, which wasn't telling anyone much; added monthly downloads, and portfolio/publisher badges linking to the author's other work.
• README: replaced the Collaborators table, inaccurate for a solo package, with an Author section.
• CI: the release workflow now re-resolves and commits example/pubspec.lock after bumping the version, so the example's lockfile — which records this package's version since it depends on it by path — no longer goes stale until the next local build rewrites it.
• CI: renamed the publish workflow to "Publish to pub.dev (auto-run by Release)" so the Actions sidebar makes the handoff from Release obvious, rather than it looking like a second entry point.
• CI: bumped actions/checkout to v7. v4 ran on Node 20, which GitHub deprecated, so every release run carried a force-run-on-Node-24 warning.
• sendOTP now throws a StateError instead of silently returning false when called on a controller with no phone number configured. This is only reachable by constructing FirebasePhoneAuthController directly and bypassing FirebasePhoneAuthHandler — but in that exact case, _setData never ran either, so onError/onLoginFailed are unset too, and a false return previously failed with no signal anywhere.
• recaptchaVerifierForWebProvider is now only invoked on web. It was previously called on every platform (with the result simply discarded on non-web), which risked constructing a RecaptchaVerifier where the underlying platform channel doesn't exist.

1.1.2 - 2026-07-28

• Maintenance release; no user-facing changes.

1.1.1 - 2026-07-28

• Added GitHub Actions CI to automate version bumps, changelog updates, tagging and pub.dev publishing.

1.1.0+1 - 2025-01-25

• Fix dart static analysis warnings

1.1.0 - 2024-10-07

• Updated README.md
• Updated dependencies
• Updated example app

1.0.8 - 2023-01-20

• Added sendOtpOnInitialize parameter to the handler
• Fixed OTP resend issue if the OTP expiration timer is still active
• Fixed #15
• Added shouldAwaitCodeSend to the sendOTP fn to give more control over the function
• Updated dependencies

1.0.7 - 2022-10-24

• Stacktrace in onLoginFailed is now non-nullable
• Updated a dependency to the latest release
• Updated example app

1.0.6 - 2022-07-16

• BREAKING: Added stack trace to onLoginFailed and onError callbacks
• Added a boolean linkWithExistingUser to link the new credentials with an existing signed-in user, instead of creating a new one.
• Added onError callback for general purpose errors by the library
• Updated example app
• Updated dependencies

1.0.5+1 - 2022-07-11

• Fixed files formatting
• Updated example app

1.0.5 - 2022-07-10

• BREAKING: Renamed flag timeOutDuration to autoRetrievalTimeOutDuration
• BREAKING: Renamed verifyOTP to verifyOtp
• BREAKING: Updated verifyOtp function signature to not take a named argument, and accept otp as a positional argument
• Added a new otpExpirationDuration flag, as autoRetrievalTimeOutDuration is a completely different parameter.
• Added callback onCodeSent and flag signOutOnSuccessfulVerification
• Added isSendingCode flag to controller
• Optimized code to reduce number of rebuilds
• Updated example app
• Updated dependencies
• Refactored code

1.0.4 - 2022-06-07

• Updated example app
• Updated dependencies
• Fixed linter warnings

1.0.3 - 2022-05-03

• Updated example app
• Updated README.md

1.0.2 - 2022-04-30

• Renamed auth_service to auth_controller
• Updated dependencies
• Minor bug fixes
• Updated example app
• Updated README.md

1.0.1 - 2022-01-26

• Updated license
• Updated README.md

1.0.0 - 2022-01-26

• Added linter and updated code accordingly
• Updated example app
• Updated dependencies
• Updated README.md

0.0.8 - 2021-10-28

• Updated dependencies
• Updated example app

0.0.7 - 2021-05-22

• Renamed FirebasePhoneAuthSupporter to FirebasePhoneAuthProvider.
• Supports sending OTP on web out of the box.
• Updated dependencies
• Updated README.md
• Updated package description.

0.0.6 - 2021-05-12

• Added key parameter
• Fixed README.md
• Updated dependencies

0.0.5 - 2021-04-23

• Added boolean in onLoginSuccess to provide info whether OTP was auto fetched or verified manually
• Updated example app
• Updated README.md

0.0.4 - 2021-04-21

• Updated example app
• Updated README.md

0.0.3 - 2021-04-21

• Updated screenshots
• Updated package description

0.0.2 - 2021-04-21

• Added FirebasePhoneAuthSupporter which has to be wrapped above the MaterialApp in order for the app to support phone authentication.
• Fixed sign out function
• Updated README.md

0.0.1 - 2021-04-20

• An easy to use firebase phone authentication library to easily send and verify OTP's.