feat: add useTrustedWebActivity option for Android Web Auth

[subhankarmaiti]

Adds a useTrustedWebActivity option to authorize and clearSession. On Android, this launches the login/logout flow as a Trusted Web Activity (full-screen, no address bar) instead of a Custom Tab, falling back to a Custom Tab if Digital Asset Links verification fails. No-op on iOS and Web.

Requires registering the app's SHA-256 fingerprint and package name in the Auth0 Dashboard (see EXAMPLES.md).

Usage

await authorize({}, { useTrustedWebActivity: true });

Summary by CodeRabbit

• New Features

  • Added optional Trusted Web Activity support for Android web login and logout flows.
  • Users can now enable a full-screen authentication experience, with fallback to Custom Tabs when verification is unavailable.

• Documentation

  • Added setup guidance and usage examples for enabling Trusted Web Activity.
  • Clarified Android-only behavior and when the option is ignored on iOS and web.

• Tests

  • Updated coverage to reflect the new authentication option and its behavior in native flows.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 874e7db4-fb18-4bdf-bebe-08b7aed4dd30

📥 Commits

Reviewing files that changed from the base of the PR and between 72a9e81 and 7120caf.

⛔ Files ignored due to path filters (1)

• example/ios/Podfile.lock is excluded by !**/*.lock

📒 Files selected for processing (10)

• EXAMPLES.md
• android/src/main/java/com/auth0/react/A0Auth0Module.kt
• android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt
• example/src/screens/class-based/ClassLogin.tsx
• example/src/screens/hooks/Home.tsx
• ios/A0Auth0.mm
• src/platforms/native/bridge/NativeBridgeManager.ts
• src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts
• src/specs/NativeA0Auth0.ts
• src/types/platform-specific.ts

---

📝 Walkthrough

Walkthrough

This PR adds an optional useTrustedWebActivity boolean setting for Android web authentication, plumbed from TypeScript option types through the native bridge manager to Android and iOS native module method signatures, with corresponding example app UI toggles, test updates, and documentation.

Changes

Trusted Web Activity option for Android web auth

Layer / File(s)	Summary
TypeScript option types and spec src/types/platform-specific.ts, src/specs/NativeA0Auth0.ts	Adds useTrustedWebActivity?: boolean to NativeAuthorizeOptions, NativeClearSessionOptions, and the native Spec interface for webAuth/webAuthLogout.
Native bridge manager wiring and tests src/platforms/native/bridge/NativeBridgeManager.ts, src/platforms/native/bridge/__tests__/NativeBridgeManager.spec.ts	authorize and clearSession forward options.useTrustedWebActivity to native webAuth/webAuthLogout calls; tests updated and extended to verify forwarding.
Android native module and spec android/src/main/java/com/auth0/react/A0Auth0Module.kt, android/src/main/oldarch/com/auth0/react/A0Auth0Spec.kt	webAuth/webAuthLogout accept useTrustedWebActivity and conditionally call withTrustedWebActivity() on the login/logout builders; bridge spec signature updated to match.
iOS native module signature ios/A0Auth0.mm	Exported webAuth and webAuthLogout methods extended with a useTrustedWebActivity parameter before the resolve/reject callbacks.
Example app UI and documentation example/src/screens/hooks/Home.tsx, example/src/screens/class-based/ClassLogin.tsx, EXAMPLES.md	Example login screens add state and a toggle to enable Trusted Web Activity passed to authorize; documentation describes the option, required Digital Asset Links setup, and usage examples.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ExampleApp
  participant NativeBridgeManager
  participant AndroidModule

  ExampleApp->>NativeBridgeManager: authorize({ useTrustedWebActivity: true })
  NativeBridgeManager->>AndroidModule: webAuth(..., allowedBrowserPackages, useTrustedWebActivity)
  AndroidModule->>AndroidModule: withTrustedWebActivity() on login builder
  ExampleApp->>NativeBridgeManager: clearSession({ useTrustedWebActivity: true })
  NativeBridgeManager->>AndroidModule: webAuthLogout(..., allowedBrowserPackages, useTrustedWebActivity)
  AndroidModule->>AndroidModule: withTrustedWebActivity() on logout builder

Loading

Suggested reviewers: pmathew92, sanchitmehtagit

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding the useTrustedWebActivity option for Android web authentication.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/trusted-web-activity-android

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}