Feat: sdk v11 hooks by tuna1207 · Pull Request #139 · Web3Auth/web3auth-react-native-sdk

tuna1207 · 2026-07-15T12:31:50Z

Motivation and Context

This PR brings the React Hooks integration in line with Web3Auth SDK v11 session/auth APIs and dashboard-driven project configuration. Hooks consumers need clearer separation between connected (wallet/session keys) and authorized (citadel access token), plus hooks for token info and session refresh. It also aligns analytics, account abstraction (including EIP-7702), and setup docs with the rest of the v11 SDK surface.

Jira Link: https://consensyssoftware.atlassian.net/browse/EMBED-399

Description

React Hooks

Extend Web3AuthProvider / useWeb3Auth() with isAuthorized and accessToken, distinguishing citadel-authorized sessions from SFA-connected sessions.
Add syncSessionState() to rehydrate provider, MFA flag, and access token after init, connect, MFA, or refresh.
Add useAuthTokenInfo and useRefreshSession hooks.
Update useAccessToken to read/write shared context state (accessToken; token kept as deprecated alias).
Deprecate useIdentityToken / getIdentityToken() in favor of useAuthTokenInfo / getAuthTokenInfo().
Update useEnableMFA and useManageMFA to sync session state after redirect flows.
Default loginSource to "web3auth-react-native" in useWeb3AuthConnect.
Tag hooks usage with integration_type: "React Hooks" in analytics.

Core SDK

Refactor analytics: structured error_code / error_message, richer initialization properties (CAIP chain IDs, RPC hostnames, AA/wallet-services config), and connection failure tracking.
Add disableAnalytics and enableAnalyticsInDev init options.
Load sessionTime from dashboard project config (fallback: 86400).
Pass aa_provider when fetching project config; support externalWalletAuth in auth payloads.
Account abstraction: EIP-7702 smart account validation, skip ERC-4337 provider wrapping for 7702, derive useAAWithExternalWallet from dashboard walletScope.
Extract clearLocalSessionState() for logout and failed session refresh.
Add wallet UI option enableDefiPositionsDisplay and defaultPortfolio: "defi".
Fix MFA management analytics (MFA_MANAGEMENT_SELECTED / MFA_MANAGEMENT_COMPLETED).

Metro & docs

Add MessageEvent polyfill in global-shim.js for Hermes (@web3auth/auth postMessageStream).
Major README update: Node 22+ / npm 10+, Metro withWeb3Auth setup, entry setup import, bare/Expo redirect URL configuration, and analytics documentation.
Update bare and Expo hooks demo apps to exercise the new APIs.

How has this been tested?

Screenshots (if appropriate):

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

My code follows the code style of this project. (run lint)
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have added tests to cover my changes.
All new and existing tests passed.
My code requires a db migration.

Note

Low Risk
Changes are limited to README, a sample app, and lockfile updates with no production SDK logic in this diff.

Overview
Documentation is expanded to match the v11 React Native integration: Node/npm requirements, separate Bare vs Expo dependency installs, Metro withWeb3Auth, mandatory @web3auth/react-native-sdk/setup as the first import, and clearer redirect URL / whitelist guidance (including Expo Go vs standalone). Usage examples now use EncryptedStorage / SecureStore, WEB3AUTH_NETWORK, init() + connectTo() instead of login(), and a new analytics section (disableAnalytics, enableAnalyticsInDev). The sample apps link points at demo/ instead of example/.

The bare hooks demo (demo/rn-bare-hooks-example) is updated to import setup first and exercise v11 session APIs: isAuthorized / accessToken, useAccessToken, useAuthTokenInfo, and useRefreshSession (replacing useIdentityToken). iOS Podfile.lock adds RNCAsyncStorage and refreshes several pod checksums.

^{Reviewed by Cursor Bugbot for commit 2c9b246. Bugbot is set up for automated code reviews on this repo. Configure here.}

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 21f83dd. Configure here.}

lwin-kyaw · 2026-07-16T08:27:04Z

  }

  private isSkipped() {
-    // const dappOrigin = window.location.origin;


Should we revert these lines?

i don't think we should, there is no window in react native

Then can we remove the irrelevant codes please?

do you mean this part ?

// const dappOrigin = window.location.origin;

it's already removed

lwin-kyaw · 2026-07-16T08:32:58Z

-      const accessToken = await web3Auth.getAccessToken();
-      setToken(accessToken);
-      return accessToken;
+      const nextAccessToken = await web3Auth.getAccessToken();


Should we have guards here? Asserting connector statuses might be helpful I think.

I think no need because RN’s core only has connected and connected / disconnected - no status machine to sync.

lwin-kyaw · 2026-07-16T08:33:39Z

  const [isMFAEnabled, setIsMFAEnabled] = useState<boolean>(false);
  const [isConnected, setIsConnected] = useState<boolean>(false);
+  const [isAuthorized, setIsAuthorized] = useState<boolean>(false);
+  const [accessToken, setAccessToken] = useState<string | null>(null);


Should we add connector statuses state too?

lwin-kyaw · 2026-07-16T08:41:22Z

+        setIsMFAEnabled(true);
+      }
+      // Refresh rotated citadel tokens / MFA flags into the provider snapshot.
+      await syncSessionState();


Please correct me if I'm wrong. Do we really need this?

Under the hood, it just looks like updating the local state for the web3AuthInnerContext.
If I understand it correct, web3AuthInnerContext has already handled this in useEffect.

enableMFA() does not emit connected. It rotates tokens via setTokens, then refreshSession(), and returns. The user was already connected, so that listener never fires.

Without the explicit sync, React context stays stale for:

accessToken / isAuthorized — citadel tokens were rotated

isMFAEnabled — updated on the SDK instance, not pushed into context automatically

We did refreshSession here though.

refreshSession under the hood update the Web3Auth instance state.

React.effect watches the web3Auth instance, triggered the useEffect again due to the state change.
From the implementation, it should trigger.

refreshSession mutates fields on that same object (updateState, session data, etc.). That does not change the web3Auth reference, so the effect should not re-run for that reason alone.
(the web3Auth instance in react hook dependency is a shallow compare)

lwin-kyaw · 2026-07-16T08:42:14Z

    try {
      await web3Auth.manageMFA();
+      // Redirect may rotate citadel tokens; resync MFA + authorization snapshot.
+      await syncSessionState();


Same as above.

same as #139 (comment)

lwin-kyaw · 2026-07-16T08:44:37Z

+   * Ignored when {@link disableAnalytics} is true. Production/release builds
+   * already send analytics by default.
+   */
+  enableAnalyticsInDev?: boolean;


Is this only for our debug/local purpose?

yes, only for dev analytics purpose

tuna1207 added 7 commits July 15, 2026 12:03

feat: update demo hooks

fab5c72

feat: handle project config and aa

d1f6ea3

feat: analytics refactor

508ef6a

feat: update messageevent shim

efc2f72

feat: update expo examples

58eef88

feat: update rn bare hooks example

4b80786

feat: update readme

21f83dd

cursor Bot reviewed Jul 15, 2026

View reviewed changes

Comment thread demo/rn-bare-hooks-example/App.tsx Outdated

fix: refresh token failure

169912e

lwin-kyaw reviewed Jul 16, 2026

View reviewed changes

feat: use getCaipChainId from package

2c9b246

Uh oh!

Conversation

tuna1207 commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Description

How has this been tested?

Screenshots (if appropriate):

Types of changes

Checklist:

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

tuna1207 Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tuna1207 commented Jul 15, 2026 •

edited

Loading

tuna1207 Jul 16, 2026 •

edited

Loading