feat: add Partial Custom Tabs support for Android by utkrishtsahu · Pull Request #846 · auth0/auth0-flutter

utkrishtsahu · 2026-05-26T05:16:11Z

All new/changed/fixed functionality is covered by tests (or N/A)
I have added documentation for all new/changed functionality (or N/A)

📋 Changes

Adds support for Partial Custom Tabs in auth0-flutter, allowing the authentication page to be displayed as a bottom sheet or side sheet on Android instead of a full-screen browser tab.

New types:

CustomTabsOptions — Dart class mirroring the iOS SafariViewController pattern, with properties: initialHeight, resizable, toolbarCornerRadius, initialWidth, sideSheetBreakpoint, backgroundInteractionEnabled, allowedBrowsers

Modified methods:

WebAuthentication.login() — added optional customTabsOptions parameter
WebAuthentication.logout() — added optional customTabsOptions parameter

Deprecated:

Top-level allowedBrowsers parameter on login() and logout() — replaced by CustomTabsOptions.allowedBrowsers

Native (Kotlin):

LoginWebAuthRequestHandler and LogoutWebAuthRequestHandler parse the new customTabsOptions map and build CustomTabsOptions via the Auth0.Android SDK builder
Bumped com.auth0.android:auth0 from 3.12.0 to 3.16.0

Backward compatibility: Fully non-breaking. The new parameter defaults to null. The deprecated allowedBrowsers continues to work as a fallback when customTabsOptions is absent.

Usage:

await auth0.webAuthentication().login( customTabsOptions: const CustomTabsOptions( initialHeight: 700, toolbarCornerRadius: 16, backgroundInteractionEnabled: true, ), );

📎 References

SDK-8720

🎯 Testing

Unit tests added:

5 Dart tests in web_authentication_test.dart — verifies customTabsOptions is serialized correctly for login/logout, defaults to null, and side sheet options pass through
5 Kotlin tests in LoginWebAuthRequestHandlerTest.kt — verifies partial tabs parsing with initialHeight, all options, absence, priority over top-level allowedBrowsers, and fallback behavior
5 Kotlin tests in LogoutWebAuthRequestHandlerTest.kt — same coverage as login handler

Not tested:

No iOS changes; customTabsOptions is Android-only and ignored on other platforms

…st NPE

pmathew92 · 2026-05-26T05:52:26Z

+            (customTabsOptionsMap["allowedBrowsers"] as? List<*>)?.filterIsInstance<String>().orEmpty()
+        } else {
+            (args["allowedBrowsers"] as? List<*>)?.filterIsInstance<String>().orEmpty()
+        }


Should we handle the edge scenario where user can send both customTabsOptions and allowedBrowsers ?

Yes, this is already handled! When both are provided, customTabsOptions.allowedBrowsers wins and the top-level one is ignored. I've now extracted this into a shared utility with a KDoc comment that makes the precedence explicit. There's also a test specifically for this case (uses allowedBrowsers from customTabsOptions when both are provided).

pmathew92 · 2026-05-26T06:00:32Z

+            }
+
+            if (customTabsOptionsMap != null) {
+                val initialHeight = customTabsOptionsMap["initialHeight"] as? Int


Pbly extract all these checks to a Util method to be reused for both login and logout ?

Created buildCustomTabsOptions() in the utils package. Both handlers now just do:

buildCustomTabsOptions(args)?.let { builder.withCustomTabsOptions(it) }
Much cleaner and keeps them in sync.

pmathew92 · 2026-05-26T06:01:48Z

+        )
+
+        runRequestHandler(args) { _, builder ->
+            verify(builder).withCustomTabsOptions(any())


This is validating any property being passed. Not the exact property as mentioned in the title

Fair point. The issue is that CustomTabsOptions has all private fields with no public getters, so we can't directly assert on the built object from the handler level. I've added a dedicated CustomTabsOptionsBuilderTest that tests our utility function and uses reflection to verify the exact values (initialHeight=700, cornerRadius=16, etc.). The handler tests now just verify the routing — that withCustomTabsOptions gets called or not based on the input.

pmathew92 · 2026-05-26T06:01:59Z

+        )
+
+        runRequestHandler(args) { _, builder ->
+            verify(builder).withCustomTabsOptions(any())


Same as above

Addressed — same approach as above. Value-level assertions live in CustomTabsOptionsBuilderTest.

pmathew92 · 2026-05-26T06:02:47Z

+        )
+
+        runRequestHandler(args) { _, builder ->
+            verify(builder).withCustomTabsOptions(any())


Validation is vague here ?

Fixed in the new utility test. For example, the precedence test asserts that the packages list is exactly ["com.android.chrome"] (from customTabsOptions) and not ["org.mozilla.firefox"] (from top-level). Same for the fallback test — it asserts the exact list passed via top-level allowedBrowsers.

pmathew92 · 2026-05-26T06:03:24Z

+        )
+
+        runRequestHandler(args) { _, builder ->
+            verify(builder).withCustomTabsOptions(any())


Same as above

Fixed in the new utility test. For example, the precedence test asserts that the packages list is exactly ["com.android.chrome"] (from customTabsOptions) and not ["org.mozilla.firefox"] (from top-level). Same for the fallback test — it asserts the exact list passed via top-level allowedBrowsers.

…e tests

…m-tabs

pmathew92 · 2026-05-26T18:13:09Z

+        (customTabsOptionsMap["allowedBrowsers"] as? List<*>)?.filterIsInstance<String>().orEmpty()
+    } else {
+        (args["allowedBrowsers"] as? List<*>)?.filterIsInstance<String>().orEmpty()
+    }


There is still a edge-case where if user passes customTabsOptionsMap !=null but doesn't contain allowed browser list and args["allowedBrowsers"] is passed with a valid list. In this scenario, we would completely skip extracting the allowedBrowsers. Not a hard requirement . Skip if you think this won't happen or chance are very low

feat: add Partial Custom Tabs support for Android

ebc154e

utkrishtsahu requested a review from a team as a code owner May 26, 2026 05:16

utkrishtsahu temporarily deployed to internal May 26, 2026 05:16 — with GitHub Actions Inactive

utkrishtsahu had a problem deploying to internal May 26, 2026 05:16 — with GitHub Actions Error

utkrishtsahu temporarily deployed to internal May 26, 2026 05:16 — with GitHub Actions Inactive

utkrishtsahu had a problem deploying to internal May 26, 2026 05:16 — with GitHub Actions Failure

fix: resolve CI failures from deprecated_consistency lint and DPoP te…

b8708ed

…st NPE

utkrishtsahu temporarily deployed to internal May 26, 2026 05:44 — with GitHub Actions Inactive

pmathew92 reviewed May 26, 2026

View reviewed changes

refactor: extract shared CustomTabsOptions builder utility and improv…

9221626

…e tests

utkrishtsahu temporarily deployed to internal May 26, 2026 09:27 — with GitHub Actions Inactive

utkrishtsahu deployed to internal May 26, 2026 09:27 — with GitHub Actions Active

utkrishtsahu temporarily deployed to internal May 26, 2026 09:27 — with GitHub Actions Inactive

utkrishtsahu had a problem deploying to internal May 26, 2026 09:27 — with GitHub Actions Failure

utkrishtsahu added 2 commits May 26, 2026 16:34

refactor: extract CustomTabsOptions parsing into shared utility

ec7c56c

Merge remote-tracking branch 'origin/main' into feature/partial-custo…

7adb381

…m-tabs

pmathew92 reviewed May 26, 2026

View reviewed changes

pmathew92 approved these changes May 28, 2026

View reviewed changes

Conversation

utkrishtsahu commented May 26, 2026

📋 Changes

📎 References

🎯 Testing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants