Feat: sdk v11 hooks

README.md

@@ -21,121 +21,261 @@ Checkout the official [Web3Auth Documentation](https://web3auth.io/docs) and [SD
 
 ## ⏪ Requirements
 
-- For iOS, only iOS 12+ supported since we requires ASWebAuthenticationSession.
-
+- Node.js 22+
+- npm 10+
+- For iOS, only iOS 12+ is supported since we require `ASWebAuthenticationSession`.
 - For Android, Custom Tab support is required.
 
 ## Selecting your Workflow
 
 In React Native, you have the choice to use one of the following workflows:
 
 - **Bare Workflow**: Your React Native app is entirely built on your own machine. You can customize your app with Swift/Kotlin native modules.
-- **Expo Managed Workflow**: Your React Native Expo app is built on your Expo's cloud, so you don't have control over the native modules used in the app.
+- **Expo Managed Workflow**: Your React Native Expo app is built on Expo's cloud, so you don't have control over the native modules used in the app.
 
 ## ⚡ Installation
 
 ```sh
 npm install @web3auth/react-native-sdk
 ```
 
+Install the workflow-specific browser and secure storage packages next.
+
+### Bare workflow dependencies
+
+```sh
+npm install @toruslabs/react-native-web-browser react-native-encrypted-storage
+npm install --save-optional react-native-quick-crypto
+```
+
+### Expo managed workflow dependencies
+
+```sh
+npx expo install expo-web-browser expo-secure-store expo-linking expo-constants
+npm install --save-optional react-native-quick-crypto
+```
+
+`react-native-quick-crypto` is optional but recommended. Without it, Metro falls back to `crypto-browserify`.
+
+## 🛠️ Metro & Entry Setup
+
+Web3Auth requires Metro polyfills and a setup import before any other app code.
+
+### Metro configuration
+
+Wrap your Metro config with `withWeb3Auth`:
+
+**Bare**
+
+```js
+const { getDefaultConfig } = require("@react-native/metro-config");
+const { withWeb3Auth } = require("@web3auth/react-native-sdk/metro-config");
+
+const config = getDefaultConfig(__dirname);
+
+module.exports = withWeb3Auth(config);
+```
+
+**Expo**
+
+```js
+const { getDefaultConfig } = require("expo/metro-config");
+const { withWeb3Auth } = require("@web3auth/react-native-sdk/metro-config");
+
+const config = getDefaultConfig(__dirname);
+
+module.exports = withWeb3Auth(config);
+```
+
+### Entry point setup
+
+Import the setup module first in your root entry file (`index.js` / `index.ts`):
+
+```js
+import "@web3auth/react-native-sdk/setup";
+
+// ... rest of your app entry
+```
+
 ## 🌟 Configuration
 
 ### Configure your Web3Auth project
 
-Hop on to the [Web3Auth Dashboard](https://dashboard.web3auth.io/) and create a new project. Use the Client ID of the project to start your integration.
+Hop on to the [Web3Auth Dashboard](https://dashboard.web3auth.io/) and create a new project. Use the **Client ID** of the project to start your integration.
 
 ![Web3Auth Dashboard](https://web3auth.io/docs/assets/images/project_plug_n_play-89c39ec42ad993107bb2485b1ce64b89.png)
 
-- Add `{YOUR_APP_PACKAGE_NAME}://auth` to **Whitelist URLs**.
+- Choose a custom URL scheme for your app (for example `web3authrnexample`). This does **not** have to match your Android package name or iOS bundle identifier.
+- Add the exact `redirectUrl` you will pass to the SDK (for example `web3authrnexample://auth`) to **Whitelist URLs**.
+- Copy the **Client ID** for usage later.
 
-- Copy the Project ID for usage later.
+### Bare workflow — Android intent-filter
 
-### Expo Managed Workflow
+The scheme portion of `redirectUrl` must be registered in `AndroidManifest.xml` so the auth browser can return to your app.
 
-When using our SDK with a Expo-based React Native app (aka managed workflow, you have to install the `expo-web-browser` package as a `WebBrowser` implementation.)
+Inside your `MainActivity`, add a browsable deep-link intent filter:
 
-```sh
-expo install expo-web-browser
+```xml
+<activity
+  android:name=".MainActivity"
+  android:launchMode="singleTask"
+  android:exported="true">
+  <!-- existing MAIN/LAUNCHER intent-filter -->
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="web3authrnexample" />
+  </intent-filter>
+</activity>
 ```
 
-To allow the SDK to work with exported Expo Android apps, you need to place a designated scheme into `app.json`, like below:
+Replace `web3authrnexample` with the scheme used in your `redirectUrl`.
 
-```js
+### Bare workflow — iOS CFBundleURLTypes
+
+Register the same scheme in your iOS `Info.plist` via `CFBundleURLTypes`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLName</key>
+    <string>web3authrnexample</string>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>web3authrnexample</string>
+    </array>
+  </dict>
+</array>
+```
+
+### Expo managed workflow — scheme & redirectUrl
+
+When using Expo, install the Expo browser/storage packages (see Installation) and declare a scheme in `app.json`:
+
+```json
 {
   "expo": {
-    "scheme": "web3authexposample"
+    "scheme": "web3authexpoexample"
   }
 }
 ```
 
-### Bare workflow Configuration
+Derive `redirectUrl` with `expo-linking`. Expo Go and standalone/dev-client builds produce different URLs — whitelist **both** in the dashboard:
 
-When using our SDK with a bare workflow React Native app, you have to install a `WebBrowser` implementation made by us.
+```js
+import Constants, { AppOwnership } from "expo-constants";
+import * as Linking from "expo-linking";
 
-```sh
-npm install --save @toruslabs/react-native-web-browser
+const redirectUrl =
+  Constants.appOwnership === AppOwnership.Expo || Constants.appOwnership === AppOwnership.Guest
+    ? Linking.createURL("web3auth", {})
+    : Linking.createURL("web3auth", { scheme: "web3authexpoexample" });
 ```
 
-#### Android
+Standalone builds resolve to a URL like `web3authexpoexample://web3auth`. Expo Go resolves to an `exp://…/--/web3auth` URL for your current session.
 
-- The `scheme` parameter in the `redirectUrl` is specificable, and has to be added into the `AndroidManifest.xml`.
+### Register the redirect URL in the dashboard
 
-```xml
-<data android:scheme="web3authrnexample" />
-```
+Whitelist the **literal** `redirectUrl` string your app passes to the SDK:
 
-#### iOS
+| Workflow                     | Example `redirectUrl`                         |
+| ---------------------------- | --------------------------------------------- |
+| Bare                         | `web3authrnexample://auth`                    |
+| Expo standalone / dev client | `web3authexpoexample://web3auth`              |
+| Expo Go                      | output of `Linking.createURL("web3auth", {})` |
 
-- The `scheme` parameter in the `redirectUrl` is specificable here as well, however, it does not need to be added as a iOS Custom URL Scheme. You may add the `scheme` to your iOS `Info.plist`, but it is not required.
+## 📊 Analytics
 
-#### Register the URL scheme you intended to use for redirection
+The SDK sends anonymous usage events to Segment so Web3Auth can improve reliability and feature coverage.
 
-- In the Web3Auth Developer Dashboard, add the URL scheme you intended to use for redirection to the **Whitelist URLs** section.
+**What is tracked (SDK-observable events):**
 
-For example, the scheme mentioned is `web3authrnexample` and the `redirectUrl` mentioned is `${scheme}://openlogin`, we will whitelist:
+- SDK initialization (completed / failed / keystore corrupted)
+- Connection, logout, MFA enablement/management, identity token
+- Wallet UI open and wallet `request()` flows
+- Initialization properties include chain metadata (CAIP ids, display names, RPC hostnames), whitelabel flags, account abstraction config, and wallet services config
 
+**Not tracked from React Native today:**
+
+- Hosted auth/wallet UI interactions such as user consent accept/decline and Terms of Service / Privacy Policy clicks. Those live inside the auth/wallet webviews and will only be trackable if a redirect/event contract is added later.
+
+**Defaults and controls:**
+
+| Option                       | Default | Behavior                                                                        |
+| ---------------------------- | ------- | ------------------------------------------------------------------------------- |
+| _(none)_                     | —       | Analytics **enabled** in release builds; **skipped** in `__DEV__`               |
+| `enableAnalyticsInDev: true` | `false` | Opt in for QA while developing; uses the development Segment write key          |
+| `disableAnalytics: true`     | `false` | Suppress all identify/track calls (**always wins** over `enableAnalyticsInDev`) |
+
+```js
+const web3auth = new Web3Auth(WebBrowser, EncryptedStorage, {
+  clientId,
+  network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
+  redirectUrl: "web3authrnexample://auth",
+  // enableAnalyticsInDev: true, // QA only
+  // disableAnalytics: true,     // full opt-out
+});
 ```
-web3authrnexample://openlogin
-```
+
+When using `Web3AuthProvider`, `integration_type` is set to `"React Hooks"`. Direct `new Web3Auth(...)` usage reports `"Native SDK"`.
 
 ## 💥 Initialization & Usage
 
-In your sign-in activity', create an `Web3Auth` instance with your Web3Auth project's configurations and
-configure it like this:
+Create a `Web3Auth` instance with your browser adapter, secure storage adapter, and project options. Call `init()` before `connectTo()`.
 
-### Expo Managed Workflow
+### Bare Workflow
 
 ```js
-import * as WebBrowser from "expo-web-browser";
-import Web3Auth, { AUTH_CONNECTION, OPENLOGIN_NETWORK } from "@web3auth/react-native-sdk";
+import "@web3auth/react-native-sdk/setup";
 
-const web3auth = new Web3Auth(WebBrowser, {
+import * as WebBrowser from "@toruslabs/react-native-web-browser";
+import Web3Auth, { AUTH_CONNECTION, WEB3AUTH_NETWORK } from "@web3auth/react-native-sdk";
+import EncryptedStorage from "react-native-encrypted-storage";
+
+const scheme = "web3authrnexample";
+const redirectUrl = `${scheme}://auth`;
+
+const web3auth = new Web3Auth(WebBrowser, EncryptedStorage, {
   clientId,
-  network: OPENLOGIN_NETWORK.TESTNET, // or other networks
-  redirectUrl: resolvedRedirectUrl,
+  network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
+  redirectUrl,
 });
-const info = await web3auth.login({
+
+await web3auth.init();
+
+await web3auth.connectTo({
   authConnection: AUTH_CONNECTION.GOOGLE,
-  mfaLevel: "mandatory", // optional
-  curve: "secp256k1", // optional
 });
 ```
 
-### Bare Workflow
+### Expo Managed Workflow
 
 ```js
-import * as WebBrowser from "@toruslabs/react-native-web-browser";
-import Web3Auth, { AUTH_CONNECTION, OPENLOGIN_NETWORK } from "@web3auth/react-native-sdk";
+import "@web3auth/react-native-sdk/setup";
 
-const web3auth = new Web3Auth(WebBrowser, {
+import Web3Auth, { AUTH_CONNECTION, WEB3AUTH_NETWORK } from "@web3auth/react-native-sdk";
+import Constants, { AppOwnership } from "expo-constants";
+import * as Linking from "expo-linking";
+import * as SecureStore from "expo-secure-store";
+import * as WebBrowser from "expo-web-browser";
+
+const redirectUrl =
+  Constants.appOwnership === AppOwnership.Expo || Constants.appOwnership === AppOwnership.Guest
+    ? Linking.createURL("web3auth", {})
+    : Linking.createURL("web3auth", { scheme: "web3authexpoexample" });
+
+const web3auth = new Web3Auth(WebBrowser, SecureStore, {
   clientId,
-  network: OPENLOGIN_NETWORK.TESTNET, // or other networks
-  redirectUrl: resolvedRedirectUrl,
+  network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
+  redirectUrl,
 });
-const info = await web3auth.login({
+
+await web3auth.init();
+
+await web3auth.connectTo({
   authConnection: AUTH_CONNECTION.GOOGLE,
-  mfaLevel: "mandatory", // optional
-  curve: "secp256k1", // optional
 });
 ```
 
@@ -147,10 +287,10 @@ Checkout the examples for your preferred blockchain and platform in our [example
 
 Checkout the [Web3Auth Demo](https://demo-app.web3auth.io/) to see how Web3Auth can be used in an application.
 
-Further checkout the [example folder](https://github.com/Web3Auth/web3auth-react-native-sdk/tree/master/example) within this repository, which contains a sample app.
+Further checkout the [demo folder](https://github.com/Web3Auth/web3auth-react-native-sdk/tree/master/demo) within this repository, which contains sample bare and Expo apps.
 
 ## 💬 Troubleshooting and Support
 
-- Have a look at our [Community Portal](https://community.web3auth.io/) to see if anyone has any questions or issues you might be having. Feel free to reate new topics and we'll help you out as soon as possible.
+- Have a look at our [Community Portal](https://community.web3auth.io/) to see if anyone has any questions or issues you might be having. Feel free to create new topics and we'll help you out as soon as possible.
 - Checkout our [Troubleshooting Documentation Page](https://web3auth.io/docs/troubleshooting) to know the common issues and solutions.
 - For Priority Support, please have a look at our [Pricing Page](https://web3auth.io/pricing.html) for the plan that suits your needs.

demo/rn-bare-hooks-example/App.tsx

@@ -1,11 +1,15 @@
+// Web3Auth setup - must be imported first before any other imports
+import "@web3auth/react-native-sdk/setup";
 import "@ethersproject/shims";
 
 import * as WebBrowser from "@toruslabs/react-native-web-browser";
 import {
   AUTH_CONNECTION,
+  useAccessToken,
+  useAuthTokenInfo,
   useEnableMFA,
-  useIdentityToken,
   useManageMFA,
+  useRefreshSession,
   useSignatureRequest,
   useWalletUI,
   useWeb3Auth,
@@ -28,13 +32,15 @@ interface HomeScreenProps {
 
 // IMP START - SDK Initialization
 function HomeScreen({ useAccountAbstraction, onToggleAA }: HomeScreenProps) {
-  const { isConnected, isInitializing, provider } = useWeb3Auth();
+  const { isConnected, isAuthorized, accessToken, isInitializing, provider } = useWeb3Auth();
   const { connectTo, loading: connectLoading } = useWeb3AuthConnect();
   const { disconnect } = useWeb3AuthDisconnect();
   const { userInfo } = useWeb3AuthUser();
   const { showWalletUI } = useWalletUI();
   const { request } = useSignatureRequest();
-  const { getIdentityToken } = useIdentityToken();
+  const { getAccessToken } = useAccessToken();
+  const { getAuthTokenInfo } = useAuthTokenInfo();
+  const { refreshSession } = useRefreshSession();
   const { enableMFA } = useEnableMFA();
   const { manageMFA } = useManageMFA();
   // IMP END - SDK Initialization
@@ -94,11 +100,16 @@ function HomeScreen({ useAccountAbstraction, onToggleAA }: HomeScreenProps) {
   return (
     <View style={styles.container}>
       <View style={styles.buttonArea}>
-        <Button title="Get User Info" onPress={() => uiConsole(userInfo)} />
+        <Button title="Get User Info" onPress={() => uiConsole({ userInfo, isAuthorized, accessToken })} />
         <Button title="Get Accounts" onPress={getAccounts} />
         <Button title="Get Balance" onPress={getBalance} />
         <Button title="Sign Message" onPress={signMessage} />
-        <Button title="Get Identity Token" onPress={() => getIdentityToken().then(uiConsole)} />
+        <Button title="Get Access Token" onPress={() => getAccessToken().then(uiConsole)} />
+        <Button title="Get Auth Token Info" onPress={() => getAuthTokenInfo().then(uiConsole)} />
+        <Button
+          title="Refresh Session"
+          onPress={() => refreshSession().then((ok) => uiConsole(ok ? "session refreshed" : "session refresh failed"))}
+        />
         <Button title="Show Wallet UI" onPress={() => showWalletUI()} />
         <Button title="Request Signature" onPress={() => request("personal_sign", ["Hello World", "0x"]).then(uiConsole)} />
         <Button title="Enable MFA" onPress={enableMFA} />