From c3e90e65abf42546eb6ee182c0b8517c93cc0174 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Wed, 10 Sep 2025 23:27:05 +0400 Subject: [PATCH 01/12] Update android SDK --- .../custom-connections/auth0.mdx | 2 +- .../custom-connections/firebase.mdx | 2 +- embedded-wallets/sdk/android/README.mdx | 54 ++- .../sdk/android/advanced/README.mdx | 53 ++- .../advanced/custom-authentication.mdx | 304 ++++++------- .../sdk/android/advanced/dapp-share.mdx | 22 +- embedded-wallets/sdk/android/advanced/mfa.mdx | 19 +- .../sdk/android/advanced/whitelabel.mdx | 12 +- .../migration-guides/android-v9-to-v10.mdx | 414 ++++++++++++++++++ embedded-wallets/sdk/android/usage/README.mdx | 20 +- .../sdk/android/usage/connect-to.mdx | 350 +++++++++++++++ .../android/usage/get-ed25519-private-key.mdx | 6 +- .../sdk/android/usage/get-private-key.mdx | 6 +- .../android/usage/launch-wallet-services.mdx | 71 +-- embedded-wallets/sdk/android/usage/login.mdx | 331 -------------- .../sdk/android/usage/request.mdx | 18 +- ew-sidebar.js | 2 +- .../android/stepContent/signin.mdx | 2 +- src/pages/tutorials/android-wallet.mdx | 4 +- src/utils/w3a-sdk-map.js | 41 +- vercel.json | 25 ++ 21 files changed, 1084 insertions(+), 674 deletions(-) create mode 100644 embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx create mode 100644 embedded-wallets/sdk/android/usage/connect-to.mdx delete mode 100644 embedded-wallets/sdk/android/usage/login.mdx diff --git a/embedded-wallets/authentication/custom-connections/auth0.mdx b/embedded-wallets/authentication/custom-connections/auth0.mdx index a1ee80fcd91..dee8ff4d046 100644 --- a/embedded-wallets/authentication/custom-connections/auth0.mdx +++ b/embedded-wallets/authentication/custom-connections/auth0.mdx @@ -164,7 +164,7 @@ private fun signIn() { } ``` -When connecting, the `login` function takes the LoginParams arguments for the login. See the [LoginParams](/embedded-wallets/sdk/android/usage/login#parameters) for more details. +When connecting, the `connectTo` function takes the `LoginParams` arguments for the login. See the [LoginParams](/embedded-wallets/sdk/android/usage/connect-to#parameters) for more details. ### Flutter diff --git a/embedded-wallets/authentication/custom-connections/firebase.mdx b/embedded-wallets/authentication/custom-connections/firebase.mdx index 55dcf953f66..9220a701484 100644 --- a/embedded-wallets/authentication/custom-connections/firebase.mdx +++ b/embedded-wallets/authentication/custom-connections/firebase.mdx @@ -187,7 +187,7 @@ private fun signIn() { } ``` -When connecting, the `login` function takes the LoginParams arguments for the login. See the [LoginParams](/embedded-wallets/sdk/android/usage/login#parameters) for more details. +When connecting, the `connectTo` function takes the `LoginParams` arguments for the login. See the [LoginParams](/embedded-wallets/sdk/android/usage/connect-to#parameters) for more details. ### Flutter diff --git a/embedded-wallets/sdk/android/README.mdx b/embedded-wallets/sdk/android/README.mdx index 2e16eaba064..1e87dc1ab44 100644 --- a/embedded-wallets/sdk/android/README.mdx +++ b/embedded-wallets/sdk/android/README.mdx @@ -55,7 +55,7 @@ Then, in your app-level `build.gradle` dependencies section, add the following: dependencies { // ... // focus-next-line - implementation 'com.github.web3auth:web3auth-android-sdk:9.1.2' + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' } ``` @@ -154,14 +154,15 @@ Create an Embedded Wallets instance and configure it with your project settings: ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork // focus-start var web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) // focus-end @@ -187,7 +188,7 @@ override fun onNewIntent(intent: Intent?) { After instantiating Embedded Wallets, the next step is to initialize it using the `initialize` method. This method is essential for setting up the SDK, checking for any active sessions, and fetching the whitelabel configuration from your dashboard. -Once the `initialize` method executes successfully, you can use the `getPrivKey` or `getEd25519PrivKey` methods to verify if an active session exists. If there is no active session, these methods will return an empty string; otherwise, they will return the respective private key. +Once the `initialize` method executes successfully, you can use the `getPrivateKey` or `getEd25519PrivateKey` methods to verify if an active session exists. If there is no active session, these methods will return an empty string; otherwise, they will return the respective private key. :::note @@ -200,7 +201,7 @@ val initializeCF: CompletableFuture = web3Auth.initialize() initializeCF.whenComplete { _, error -> if (error == null) { // Check for the active session - if(web3Auth.getPrivKey()isNotEmpty()) { + if(web3Auth.getPrivateKey().isNotEmpty()) { // Active session found } // No active session is not present @@ -240,8 +241,8 @@ See the [advanced configuration sections](./advanced/) to learn more about each val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.SAPPHIRE_MAINNET, // or Network.SAPPHIRE_DEVNET + clientId = "YOUR_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET redirectUrl = "YOUR_APP_SCHEME://auth" ) ) @@ -255,12 +256,12 @@ val web3Auth = Web3Auth( val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.SAPPHIRE_MAINNET, // or Network.SAPPHIRE_DEVNET + clientId = "YOUR_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET redirectUrl = "YOUR_APP_SCHEME://auth" - loginConfig = hashMapOf("google" to LoginConfigItem( - verifier = "verifier-name", // Get it from MetaMask Developer Dashboard - typeOfLogin = TypeOfLogin.GOOGLE, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection = AuthConnection.GOOGLE, clientId = getString(R.string.google_client_id) // Google's client id )), mfaSettings = MfaSettings( @@ -279,13 +280,30 @@ val web3Auth = Web3Auth( -## Blockchain integration +## Single Factor Auth (SFA) Support + +Web3Auth Android SDK includes built-in support for Single Factor Auth (SFA), allowing for seamless authentication when you already have a JWT token from your authentication system. When MFA is disabled, users won't even notice Web3Auth's presence - they'll be automatically authenticated using just your JWT token, making the login experience completely frictionless. + +```kotlin +// SFA login with custom JWT +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_verifier_id", + idToken = "your_jwt_token" + ) +) +``` + +SFA mode is automatically activated when you provide an `idToken` parameter. This enables direct authentication without additional social login steps, perfect for applications that already have their own authentication system. + +## Blockchain Integration Embedded Wallets is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Embedded Wallets offers robust support for both **Solana** and **Ethereum**. ### Ethereum integration -For Ethereum integration, you can get the private key using the `getPrivKey` method and use it with web3j or other Ethereum libraries: +For Ethereum integration, you can get the private key using the `getPrivateKey` method and use it with web3j or other Ethereum libraries: ```kotlin import org.web3j.crypto.Credentials @@ -294,7 +312,7 @@ import org.web3j.protocol.Web3j import org.web3j.protocol.http.HttpService // Use your Web3Auth instance to get the private key -val privateKey = web3Auth.getPrivKey() +val privateKey = web3Auth.getPrivateKey() // Generate the Credentials val credentials = Credentials.create(privateKey) @@ -314,7 +332,7 @@ val ethBalance = BigDecimal.valueOf(balanceResponse.balance.toDouble()).divide(B ### Solana integration -For Solana integration, you can get the Ed25519 private key using the `getEd25519PrivKey` method and use it with sol4k or any other Solana libraries: +For Solana integration, you can get the Ed25519 private key using the `getEd25519PrivateKey` method and use it with sol4k or any other Solana libraries: ```kotlin import org.sol4k.Connection @@ -323,7 +341,7 @@ import org.sol4k.Keypair val connection = Connection(RpcUrl.DEVNET) // Use your Web3Auth instance to get the private key -val ed25519PrivateKey = web3Auth.getEd25519PrivKey() +val ed25519PrivateKey = web3Auth.getEd25519PrivateKey() // Generate the Solana KeyPair val solanaKeyPair = Keypair.fromSecretKey(ed25519PrivateKey.hexToByteArray()) diff --git a/embedded-wallets/sdk/android/advanced/README.mdx b/embedded-wallets/sdk/android/advanced/README.mdx index 0bee077b845..2b1dda7b8ea 100644 --- a/embedded-wallets/sdk/android/advanced/README.mdx +++ b/embedded-wallets/sdk/android/advanced/README.mdx @@ -16,14 +16,15 @@ When setting up Embedded Wallets, you'll pass in the options to the constructor. ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork // focus-start var web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) // focus-end @@ -50,21 +51,22 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `context` | Android context to launch web-based authentication, usually is the current activity. It's a mandatory field, and accepts `android.content.Context` as a value. | | `clientId` | Your Embedded Wallets Client ID. You can get it from Embedded Wallets [dashboard](https://developer.metamask.io/) under project details. It's a mandatory field of type `String` | -| `network` | Defines the Embedded Wallets Network. It's a mandatory field of type Network. | -| `redirectUrl` | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type `Uri`. | -| `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is 86400 seconds which is 1 day. `sessionTime` can be max 30 days. | -| `useCoreKitKey?` | Use CoreKit (or SFA) key to get core kit key given by SFA SDKs. It's an optional field with default value as `false`. Useful for Wallet Pregeneration. | -| `chainNamespace?` | Chain Namespace [`EIP155` and `SOLANA`]. It takes `ChainNamespace` as a value. | +| `web3AuthNetwork` | Defines the Embedded Wallets Network. It's a mandatory field of type `Web3AuthNetwork`. | +| `redirectUrl` | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type `String`. | +| `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is 86400 seconds which is 1 day. `sessionTime` can be max 30 days. | +| `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for wallet pregeneration and SFA mode. | +| `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. | -| Parameter | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `whiteLabel?` | Whitelabel options for Embedded Wallets. It helps you define custom UI, branding, and translations for your brand app. It takes `WhiteLabelData` as a value. | -| `loginConfig?` | Login config for the custom verifiers. It takes `HashMap` as a value. | -| `mfaSettings?` | Allows developers to configure the MFA settings for authentication. It takes `MfaSettings` as a value. | +| Parameter | Description | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `whiteLabel?` | WhiteLabel options for web3auth. It helps you define custom UI, branding, and translations for your brand app. It takes `WhiteLabelData` as a value. | +| `authConnectionConfig?` | Auth connection config for the custom auth connections. It takes `List` as a value. | +| `mfaSettings?` | Allows developers to configure the MFA settings for authentication. It takes `MfaSettings` as a value. | +| `walletServicesConfig?` | Configuration for wallet services including whitelabel options. It takes `WalletServicesConfig` as a value. | @@ -74,16 +76,19 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. data class Web3AuthOptions( var context: Context, val clientId: String, - val network: Network, - var buildEnv: BuildEnv? = BuildEnv.PRODUCTION, - @Transient var redirectUrl: Uri, - var sdkUrl: String = getSdkUrl(buildEnv), + val web3AuthNetwork: Web3AuthNetwork, + var authBuildEnv: BuildEnv? = BuildEnv.PRODUCTION, + var redirectUrl: String, + var sdkUrl: String = getSdkUrl(authBuildEnv), val whiteLabel: WhiteLabelData? = null, - val loginConfig: HashMap? = null, - val useCoreKitKey: Boolean? = false, - val chainNamespace: ChainNamespace? = ChainNamespace.EIP155, + val authConnectionConfig: List? = null, + val useSFAKey: Boolean? = false, + val chains: Chains? = null, val mfaSettings: MfaSettings? = null, - val sessionTime: Int? = 86400 + val sessionTime: Int = 86400, + val walletServicesConfig: WalletServicesConfig? = null, + val defaultChainId: String? = null, + val enableLogging: Boolean? = false ) ``` @@ -105,10 +110,10 @@ Control how long users stay authenticated and how sessions persist. The session var web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, sessionTime = 86400 * 7, // 7 days (in seconds) - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) ``` diff --git a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx index 9059ffc2efe..6dabd09cde2 100644 --- a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx @@ -32,7 +32,7 @@ Learn more about the [auth provider setup](/embedded-wallets/authentication) and ## Configuration -:::warning +To use custom authentication (Using Social providers or Login providers like Auth0, AWS Cognito, Firebase etc. or even your own custom JWT login) you can add the configuration using `authConnectionConfig` parameter during the initialization. **"Auth Connection"** is called **"Verifier"** in the Android SDK. It is the older terminology which we will be updating in the upcoming releases. @@ -40,11 +40,9 @@ Consequentially, you will see the terms **"Verifier ID"** and **"Aggregate Verif ::: -To use custom authentication (using supported Social providers or Login providers like Auth0, AWS Cognito, Firebase, or your own custom JWT login), you can add the configuration using `loginConfig` parameter during the initialization. +The `authConnectionConfig` parameter is a list of `AuthConnectionConfig` instances, each defining a specific authentication connection. -The `loginConfig` parameter is a key value map. The key should be one of the `Web3AuthProvider` in its string form, and the value should be a `LoginConfigItem` instance. - -After creating the verifier, you can use the following parameters in the `LoginConfigItem`. +After creating the auth connection from the [Web3Auth Dashboard](https://dashboard.web3auth.io), you can use the following parameters in the `AuthConnectionConfig`. -| Parameter | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `verifier` | The name of the verifier that you have registered on the Embedded Wallets dashboard. It's a mandatory field, and it accepts a string value. | -| `typeOfLogin` | Type of login of this verifier, this value will affect the login flow that is adapted. For example, if you choose `google`, a Google sign-in flow will be used. If you choose `jwt`, you should be providing your own JWT token, no sign-in flow will be presented. It's a mandatory field, and accepts `TypeOfLogin` as a value. | -| `clientId` | Client ID provided by your login provider used for custom verifier. for example, Google's Client ID or Web3Auth's client ID if using JWT as` TypeOfLogin`. It's a mandatory field, and it accepts a string value. | -| `name?` | Display name for the verifier. If null, the default name is used. It accepts a string value. | -| `description?` | Description for the button. If provided, it renders as a full length button. else, icon button. It accepts a string value. | -| `verifierSubIdentifier?` | The field in JWT token which maps to verifier ID. Please make sure you selected correct JWT verifier ID in the developer dashboard. It accepts a string value. | -| `logoHover?` | Logo to be shown on mouse hover. It accepts a string value. | -| `logoLight?` | Light logo for dark background. It accepts a string value. | -| `logoDark?` | Dark logo for light background. It accepts a string value. | -| `mainOption?` | Show login button on the main list. Is a boolean value. Default value is false. | -| `showOnModal?` | Whether to show the login button on modal or not. Default value is true. | -| `showOnDesktop?` | Whether to show the login button on desktop. Default value is true. | -| `showOnMobile?` | Whether to show the login button on mobile. Default value is true. | +| Parameter | Description | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `authConnectionId` | The name of the auth connection that you have registered on the Web3Auth Dashboard. It's a mandatory field, and accepts `String` as a value. | +| `authConnection` | Type of login of this auth connection, this value will affect the login flow that is adapted. For example, if you choose `google`, a Google sign-in flow will be used. If you choose `custom`, you should be providing your own JWT token, no sign-in flow will be presented. It's a mandatory field, and accepts `AuthConnection` as a value. | +| `clientId` | Client id provided by your login provider used for custom auth connection. e.g. Google's Client ID or Web3Auth's client Id if using 'custom' as AuthConnection. It's a mandatory field, and accepts `String` as a value. | +| `name?` | Display name for the auth connection. If null, the default name is used. It accepts `String` as a value. | +| `description?` | Description for the button. If provided, it renders as a full length button. else, icon button. It accepts `String` as a value. | +| `groupedAuthConnectionId?` | The field in JWT token which maps to grouped auth connection id. Please make sure you selected correct JWT auth connection id in the developer dashboard. It accepts `String` as a value. | +| `logoHover?` | Logo to be shown on mouse hover. It accepts `String` as a value. | +| `logoLight?` | Light logo for dark background. It accepts `String` as a value. | +| `logoDark?` | Dark logo for light background. It accepts `String` as a value. | +| `mainOption?` | Show login button on the main list. It accepts `Boolean` as a value. Default value is false. | +| `showOnModal?` | Whether to show the login button on modal or not. Default value is true. | +| `showOnDesktop?` | Whether to show the login button on desktop. Default value is true. | +| `showOnMobile?` | Whether to show the login button on mobile. Default value is true. | ```kotlin -data class LoginConfigItem( - var verifier: String, - private var typeOfLogin: TypeOfLogin, +data class AuthConnectionConfig( + var authConnectionId: String, + private var authConnection: AuthConnection, private var name: String? = null, private var description: String? = null, private var clientId: String, - private var verifierSubIdentifier: String? = null, + private var groupedAuthConnectionId: String? = null, private var logoHover: String? = null, private var logoLight: String? = null, private var logoDark: String? = null, @@ -93,7 +91,7 @@ data class LoginConfigItem( private var showOnMobile: Boolean? = true, ) -enum class TypeOfLogin { +enum class AuthConnection { @SerializedName("google") GOOGLE, @SerializedName("facebook") @@ -122,10 +120,12 @@ enum class TypeOfLogin { WECHAT, @SerializedName("email_passwordless") EMAIL_PASSWORDLESS, - @SerializedName("email_password") - EMAIL_PASSWORD, - @SerializedName("jwt") - JWT + @SerializedName("custom") + CUSTOM, // for jwt + @SerializedName("sms_passwordless") + SMS_PASSWORDLESS, + @SerializedName("farcaster") + FARCASTER } ``` @@ -149,17 +149,18 @@ enum class TypeOfLogin { ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf("google" to LoginConfigItem( - verifier = "verifier-name", // Get it from MetaMask Developer Dashboard - typeOfLogin = TypeOfLogin.GOOGLE, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection = AuthConnection.GOOGLE, clientId = getString(R.string.google_client_id) // Google's client id )) // focus-end @@ -167,8 +168,8 @@ val web3Auth = Web3Auth( ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.GOOGLE) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) ) // focus-end ``` @@ -180,18 +181,19 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf( - "facebook" to LoginConfigItem( - verifier = "verifier-name", // Get it from MetaMask Developer Dashboard - typeOfLogin = TypeOfLogin.FACEBOOK, + authConnectionConfig = listOf( + AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection = AuthConnection.FACEBOOK, clientId = getString(R.string.facebook_client_id) // Facebook's client id ) ) @@ -200,8 +202,8 @@ val web3Auth = Web3Auth( ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.Facebook) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.FACEBOOK) ) // focus-end @@ -214,17 +216,18 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // Get it from MetaMask Developer Dashboard - typeOfLogin = TypeOfLogin.JWT, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection = AuthConnection.CUSTOM, clientId = getString (R.string.auth0_project_id) // Auth0's client id )) // focus-end @@ -232,8 +235,8 @@ val web3Auth = Web3Auth( ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.JWT) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.CUSTOM) ) // focus-end ``` @@ -245,18 +248,19 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf( - "jwt" to LoginConfigItem( - verifier = "verifier-name", // Get it from MetaMask Developer Dashboard - typeOfLogin = TypeOfLogin.JWT, + authConnectionConfig = listOf( + AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection = AuthConnection.CUSTOM, ) ) // focus-end @@ -264,8 +268,8 @@ val web3Auth = Web3Auth( ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.JWT) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.CUSTOM) ) // focus-end @@ -290,29 +294,29 @@ Additional to the `LoginConfig` you can pass extra options to the `login` functi -| Parameter | Description | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `additionalParams?` | Additional params in `HashMap` format for OAuth login, use id_token(JWT) to authenticate with web3auth. | -| `domain?` | Your custom authentication domain in string format. For example, if you are using Auth0, it can be example.au.auth0.com. | -| `client_id?` | Client ID in string format, provided by your login provider used for custom verifier. | -| `leeway?` | The value used to account for clock skew in JWT expirations. The value is in the seconds, and ideally should no more than 60 seconds or 120 seconds at max. It accepts a string value. | -| `verifierIdField?` | The field in JWT token which maps to verifier ID. Please make sure you selected correct JWT verifier ID in the developer dashboard. It accepts a string value. | -| `isVerifierIdCaseSensitive?` | Boolean to confirm whether the verifier ID field is case sensitive or not. | -| `display?` | Allows developers the configure the display of UI. It takes `Display` as a value. | -| `prompt?` | Prompt shown to the user during authentication process. It takes `Prompt` as a value. | -| `max_age?` | Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It accepts a string value. | -| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | -| `id_token_hint?` | It denotes the previously issued ID token. It accepts a string value. | -| `id_token?` | JWT (ID token) to be passed for login. | -| `login_hint?` | Used to specify the user's email address or phone number for email/SMS passwordless login flows. It accepts a string value. For the SMS, the format should be: `+{country_code}-{phone_number}` (for example `+1-1234567890`) | -| `acr_values?` | acc_values | -| `scope?` | The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It accepts a string value. | -| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It accepts a string value. | -| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 login page and show the login widget. It accepts a string value. | -| `state?` | State | -| `response_type?` | Defines which grant to execute for the authorization server. It accepts a string value. | -| `nonce?` | nonce | -| `redirect_uri?` | It can be used to specify the default URL, where your custom JWT verifier can redirect your browser to with the result. If you are using Auth0, it must be allowlisted in the allowed callback URLs in your Auth0's application. | +| Parameter | Description | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `additionalParams?` | Additional params in `HashMap` format for OAuth login, use id_token(JWT) to authenticate with web3auth. | +| `domain?` | Your custom authentication domain in `String` format. For example, if you are using Auth0, it can be example.au.auth0.com. | +| `client_id?` | Client id in `String` format, provided by your login provider used for custom verifier. | +| `leeway?` | The value used to account for clock skew in JWT expirations. The value is in the seconds, and ideally should no more than 60 seconds or 120 seconds at max. It takes `String` as a value. | +| `userIdField?` | The field in JWT token which maps to user id. Please make sure you selected correct JWT user id in the developer dashboard. It takes `String` as a value. | +| `isUserIdCaseSensitive?` | Boolean to confirm Whether the user id field is case sensitive or not. | +| `display?` | Allows developers the configure the display of UI. It takes `Display` as a value. | +| `prompt?` | Prompt shown to the user during authentication process. It takes `Prompt` as a value. | +| `max_age?` | Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It takes `String` as a value. | +| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | +| `id_token_hint?` | It denotes the previously issued ID token. It takes `String` as a value. | +| `id_token?` | JWT (ID Token) to be passed for login. | +| `login_hint?` | Used to specify the user's email address or phone number for Email/SMS Passwordless login flows. Takes a `String` value. For the SMS, the format should be: `+{country_code}-{phone_number}` (e.g. `+1-1234567890`) | +| `acr_values?` | acc_values | +| `scope?` | The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It takes `String` as a value. | +| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It takes `String` as a value. | +| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget. It takes `String` as a value. | +| `state?` | state | +| `response_type?` | Defines which grant to execute for the authorization server. It takes `String` as a value. | +| `nonce?` | nonce | +| `redirect_uri?` | It can be used to specify the default url, where your custom jwt verifier can redirect your browser to with the result. If you are using Auth0, it must be whitelisted in the Allowed Callback URLs in your Auth0's application. | @@ -324,8 +328,8 @@ data class ExtraLoginOptions( private var domain : String? = null, private var client_id : String? = null, private var leeway : String? = null, - private var verifierIdField : String? =null, - private var isVerifierIdCaseSensitive : Boolean? = null, + private var userIdField : String? = null, + private var isUserIdCaseSensitive : Boolean? = null, private var display : Display? = null, private var prompt : Prompt? = null, private var max_age : String? = null, @@ -366,30 +370,31 @@ Auth0 has a special login flow, called the SPA flow. This flow requires a `clien ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // Get it from MetaMask Developer Dashboard - typeOfLogin = TypeOfLogin.JWT, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection = AuthConnection.CUSTOM, clientId = getString (R.string.auth0_project_id) // Auth0's client id )) // focus-end ) ) -val loginCompletableFuture: CompletableFuture = web3Auth.login( +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - Provider.JWT, + AuthConnection.CUSTOM, // focus-start extraLoginOptions = ExtraLoginOptions( - domain: "https://username.us.auth0.com", // Domain of your Auth0 app - verifierIdField: "sub", // The field in jwt token which maps to verifier id. + domain = "https://username.us.auth0.com", // Domain of your Auth0 app + userIdField = "sub", // The field in jwt token which maps to user id. ) // focus-end ) @@ -400,36 +405,33 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login If you're using any other provider like Firebase/ AWS Cognito or deploying your own Custom JWT -server, you need to put the JWT token into the `id_token` field of the `extraLoginOptions`, -additionally, you need to pass over the `domain` field as well, which is mandatory. If you don't -have a domain, just passover a string in that field. +server, you need to put the jwt token into the `idToken` field of the `LoginParams`. For SFA (Single Factor Auth) mode, this enables direct authentication without additional login flows. ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // Get it from MetaMask Developer Dashboard - typeOfLogin = TypeOfLogin.JWT, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection = AuthConnection.CUSTOM, )) // focus-end ) ) -val loginCompletableFuture: CompletableFuture = web3Auth.login( +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - Provider.JWT, + AuthConnection.CUSTOM, // focus-start - extraLoginOptions = ExtraLoginOptions( - id_token: "", - ) + idToken = "Your JWT id token", // focus-end ) ) @@ -438,29 +440,29 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login -To use the email passwordless login, you need to put the email into the `login_hint` parameter of -the `ExtraLoginOptions`. By default, the login flow will be `code` flow, if you want to use the -`link` flow, you need to put `flow_type` into the `additionalParams` parameter of the -`ExtraLoginOptions`. +To use the Email Passwordless login, you need to put the email into the `loginHint` parameter of +the `LoginParams`. By default, the login flow will be `code` flow, if you want to use the +`link` flow, you need to put `flow_type` into the `extraLoginOptions` parameter. ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) -val loginCompletableFuture: CompletableFuture = web3Auth.login( +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - Provider.EMAIL_PASSWORDLESS, + AuthConnection.EMAIL_PASSWORDLESS, // focus-next-line - extraLoginOptions = ExtraLoginOptions(login_hint = "hello@web3auth.io") + loginHint = "hello@web3auth.io" ) ) ``` @@ -468,28 +470,29 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login -To use the SMS Passwordless login, send the phone number as the `login_hint` parameter of the -`ExtraLoginOptions`. Please ensure the phone number takes the format: -+\{country_code}-\{phone_number}, that is, (+91-09xx901xx1). +To use the SMS Passwordless login, send the phone number as the `loginHint` parameter of the +`LoginParams`. Please make sure the phone number is in the format of ++\{country_code}-\{phone_number}, i.e. (+91-09xx901xx1). ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - Provider.SMS_PASSWORDLESS, - extraLoginOptions = ExtraLoginOptions(login_hint = "+91-9911223344") + AuthConnection.SMS_PASSWORDLESS, + loginHint = "+91-9911223344" ) ) // focus-end @@ -499,33 +502,34 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login -### Aggregate verifier Usage +### Grouped Auth Connection Usage -You can use aggregate verifier to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and email passwordless login, or Google and GitHub via Auth0 to access the same address for your user. +You can use grouped auth connections to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and Email Passwordless login, or Google and GitHub via Auth0 to access the same address for your user. ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf( - "google" to LoginConfigItem( - verifier = "aggregate-sapphire", - verifierSubIdentifier= "w3a-google", - typeOfLogin = TypeOfLogin.GOOGLE, + authConnectionConfig = listOf( + AuthConnectionConfig( + authConnectionId = "aggregate-sapphire", + groupedAuthConnectionId = "w3a-google", + authConnection = AuthConnection.GOOGLE, name = "Aggregate Login", clientId = getString(R.string.web3auth_google_client_id) ), - "jwt" to LoginConfigItem( - verifier = "aggregate-sapphire", - verifierSubIdentifier= "w3a-a0-email-passwordless", - typeOfLogin = TypeOfLogin.JWT, + AuthConnectionConfig( + authConnectionId = "aggregate-sapphire", + groupedAuthConnectionId = "w3a-a0-email-passwordless", + authConnection = AuthConnection.CUSTOM, name = "Aggregate Login", clientId = getString(R.string.web3auth_auth0_client_id) ) @@ -536,17 +540,17 @@ val web3Auth = Web3Auth( // focus-start // Google Login -web3Auth.login(LoginParams(Provider.GOOGLE)) +web3Auth.connectTo(LoginParams(AuthConnection.GOOGLE)) // focus-end // focus-start // Auth0 Login -web3Auth.login(LoginParams( - Provider.JWT, +web3Auth.connectTo(LoginParams( + AuthConnection.CUSTOM, extraLoginOptions = ExtraLoginOptions( domain = "https://web3auth.au.auth0.com", - verifierIdField = "email", - isVerifierIdCaseSensitive = false + userIdField = "email", + isUserIdCaseSensitive = false ) )) // focus-end diff --git a/embedded-wallets/sdk/android/advanced/dapp-share.mdx b/embedded-wallets/sdk/android/advanced/dapp-share.mdx index 155f6500dbd..d9c077d7235 100644 --- a/embedded-wallets/sdk/android/advanced/dapp-share.mdx +++ b/embedded-wallets/sdk/android/advanced/dapp-share.mdx @@ -34,14 +34,14 @@ After a successful login from a user, the user details are returned as a respons "email": "w3a-heroes@web3auth.com", "name": "Web3Auth Heroes", "profileImage": "https://lh3.googleusercontent.com/a/Ajjjsdsmdjmnm...", - "verifier": "torus", - "verifierId": "w3a-heroes@web3auth.com", - "typeOfLogin": "google", - "aggregateVerifier": "w3a-google-sapphire", - "dappShare": "", // 24 words of seed phrase will be sent only incase of custom verifiers + "authConnectionId": "torus", + "userId": "w3a-heroes@web3auth.com", + "authConnection": "google", + "groupedAuthConnectionId": "w3a-google-sapphire", + "dappShare": "", // 24 words of seed phrase will be sent only incase of custom auth connections "idToken": "", - "oAuthIdToken": "", // will be sent only incase of custom verifiers - "oAuthAccessToken": "", // will be sent only incase of custom verifiers + "oAuthIdToken": "", // will be sent only incase of custom auth connections + "oAuthAccessToken": "", // will be sent only incase of custom auth connections "isMfaEnabled": false // Returns whether the user has enabled MFA or not } } @@ -53,12 +53,12 @@ Now, while logging in, the user can use their social accounts to obtain one shar :::note -One major thing to note here is that the `dappShare` is only available for custom verifiers and not the standard Web3Auth verifiers. This is done to make sure that an application only has access to the corresponding share to the private key of their application's user. Hence, to use dapp share, one has to use the custom authentication feature of Web3Auth. Also, the dapp share is only returned to users who have enabled 2FA to their account. +One major thing to note here is that the `dappShare` is only available for custom auth connections and not the standard web3auth auth connections. This is done to make sure that an application only has access to the corresponding share to the private key of their application's user. Hence, to use dApp Share, one has to use the custom authentication feature of Web3Auth. Also, the dApp Share is only returned to users who have enabled 2FA to their account. ::: ```kotlin -web3Auth.login(LoginParams(selectedLoginProvider, dappShare = "<24 words seed phrase>")) +web3Auth.connectTo(LoginParams(selectedLoginProvider, dappShare = "<24 words seed phrase>")) ``` ## Example @@ -73,10 +73,10 @@ class MainActivity : AppCompatActivity() { private lateinit var web3Auth: Web3Auth private fun signIn() { - val selectedLoginProvider = Provider.GOOGLE + val selectedLoginProvider = AuthConnection.GOOGLE // Can be GOOGLE, FACEBOOK, TWITCH etc. val loginCompletableFuture: CompletableFuture = - web3Auth.login(LoginParams(selectedLoginProvider, + web3Auth.connectTo(LoginParams(selectedLoginProvider, // focus-next-line dappShare = "<24 words seed phrase>")) loginCompletableFuture.whenComplete { loginResponse, error -> diff --git a/embedded-wallets/sdk/android/advanced/mfa.mdx b/embedded-wallets/sdk/android/advanced/mfa.mdx index 12b33de8e59..30b309ccbda 100644 --- a/embedded-wallets/sdk/android/advanced/mfa.mdx +++ b/embedded-wallets/sdk/android/advanced/mfa.mdx @@ -38,9 +38,9 @@ If you are using default verifiers, your users may have set up MFA on other dapp ### Usage ```kotlin -val loginResponse = web3Auth.login( +val loginResponse = web3Auth.connectTo( LoginParams( - Proider.GOOGLE, + AuthConnection.GOOGLE, // focus-next-line mfaLevel = MFALevel.MANDATORY ) @@ -108,8 +108,8 @@ class MainActivity : AppCompatActivity() { private lateinit var web3Auth: Web3Au private fun enableMFA() { val loginParams = LoginParams( - Provider.JWT, - extraLoginOptions = ExtraLoginOptions(id_token = "") + AuthConnection.CUSTOM, + idToken = "your_jwt_token" ) // focus-next-line @@ -237,13 +237,14 @@ data class MfaSetting( ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start mfaSettings = MfaSettings( deviceShareFactor = MfaSetting(true, 1, true), @@ -257,9 +258,9 @@ val web3Auth = Web3Auth( ) ) -val loginResponse = web3Auth.login( +val loginResponse = web3Auth.connectTo( LoginParams( - Proider.GOOGLE, + AuthConnection.GOOGLE, // focus-next-line mfaLevel = MFALevel.MANDATORY ) diff --git a/embedded-wallets/sdk/android/advanced/whitelabel.mdx b/embedded-wallets/sdk/android/advanced/whitelabel.mdx index 468eccd7710..6183d58f796 100644 --- a/embedded-wallets/sdk/android/advanced/whitelabel.mdx +++ b/embedded-wallets/sdk/android/advanced/whitelabel.mdx @@ -39,12 +39,12 @@ For defining custom UI, branding, and translations for your brand during Embedde | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appName?` | Display name for the app in the UI. | -| `logoLight?` | App logo to be used in dark mode. It accepts URL as a string. | -| `logoDark?` | App logo to be used in light mode. It accepts URL as a string. | +| `logoLight?` | App logo to be used in dark mode. It accepts url in `String` as a value. | +| `logoDark?` | App logo to be used in light mode. It accepts url in `String` as a value. | | `defaultLanguage?` | Language which will be used by Web3Auth, app will use browser language if not specified. Default language is `Language.EN`. Checkout `Language` for supported languages. | | `mode?` | Theme mode for the login modal. Choose between `ThemeModes.AUTO`, `ThemeModes.LIGHT` or `ThemeModes.DARK` background modes. Default value is `ThemeModes.AUTO`. | | `theme?` | Used to customize the theme of the login modal. It accepts `HashMap` as a value. | -| `appUrl?` | URL to be used in the modal. It accepts URL as a string. | +| `appUrl?` | Url to be used in the Modal. It accepts url in `String` as a value. | | `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are null, the default Web3Auth logo will be used for the loader. Default value is false. | @@ -76,8 +76,8 @@ web3Auth = Web3Auth ( Web3AuthOptions ( context = this, clientId = getString (R.string.web3auth_project_id), - network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // Optional whitelabel object // focus-start whiteLabel = WhiteLabelData ( @@ -86,7 +86,7 @@ web3Auth = Web3Auth ( logoLight = null, logoDark = null, defaultLanguage = Language.EN, // EN, DE, JA, KO, ZH, ES, FR, PT, NL - ThemeModes = ThemeModes.DARK, // LIGHT, DARK, AUTO + mode = ThemeModes.DARK, // LIGHT, DARK, AUTO useLogoLoader = true, theme = hashMapOf ( "primary" to "#229954" diff --git a/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx new file mode 100644 index 00000000000..d11daa7e0eb --- /dev/null +++ b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx @@ -0,0 +1,414 @@ +--- +title: Migrating from v9.x to v10.x +sidebar_label: v9.x to v10.x +description: 'Web3Auth Android SDK - Migrating from v9.x to v10.x | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +This migration guide provides a step-by-step walkthrough for upgrading your Web3Auth Android SDK implementation from v9.x to v10.x. This is a major release with significant API changes, new features, and improvements. + +## Overview of Changes + +Web3Auth Android SDK v10.x introduces several major changes: + +- **Combined PnP and SFA SDK**: Unified authentication flow supporting both Plug and Play (PnP) and Single Factor Auth (SFA) in one SDK +- **Updated Authentication API**: `login()` method replaced with `connectTo()` for better clarity and SFA support +- **Simplified Wallet Services**: Automatic chain configuration from dashboard settings +- **Enhanced Type Safety**: Updated enums and parameter structures +- **Analytics Integration**: Built-in analytics for better insights +- **Performance Improvements**: Optimized parameter handling and reduced configuration complexity + +## Breaking Changes + +### 1. Update Dependencies + +First, update your dependency to the latest version: + +```groovy +dependencies { + // Old + implementation 'com.github.web3auth:web3auth-android-sdk:9.1.2' + + // New + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' +} +``` + +### 2. Import Changes + +Add the new required import for Web3AuthNetwork: + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import com.web3auth.core.types.Network +import com.web3auth.core.types.Provider +import com.web3auth.core.types.LoginConfigItem +import com.web3auth.core.types.TypeOfLogin +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import com.web3auth.core.types.AuthConnection +import com.web3auth.core.types.AuthConnectionConfig +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork +``` + + + + +### 3. Enum Changes + +Several enums have been renamed for better clarity: + +| v9.x | v10.x | +| ----------------- | ----------------------- | +| `Provider` | `AuthConnection` | +| `TypeOfLogin` | `AuthConnection` | +| `Network` | `Web3AuthNetwork` | +| `LoginConfigItem` | `AuthConnectionConfig` | +| `Provider.JWT` | `AuthConnection.CUSTOM` | + +### 4. Web3AuthOptions Configuration + +The configuration object has been updated with new parameter names: + + + + + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_CLIENT_ID", + network = Network.SAPPHIRE_MAINNET, + redirectUrl = Uri.parse("your-app://auth"), + loginConfig = hashMapOf("google" to LoginConfigItem( + verifier = "verifier-name", + typeOfLogin = TypeOfLogin.GOOGLE, + clientId = "google-client-id" + )), + buildEnv = BuildEnv.PRODUCTION + ) +) +``` + + + + + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "your-app://auth", // Now a String instead of Uri + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "verifier-name", + authConnection = AuthConnection.GOOGLE, + clientId = "google-client-id" + )), + authBuildEnv = BuildEnv.PRODUCTION // Renamed from buildEnv + ) +) +``` + + + + +### 5. Authentication Method Changes + +The main authentication method has been renamed and enhanced: + + + + + +```kotlin +// Simple social login +val loginCompletableFuture = web3Auth.login( + LoginParams(Provider.GOOGLE) +) + +// Email passwordless +val loginCompletableFuture = web3Auth.login( + LoginParams( + Provider.EMAIL_PASSWORDLESS, + extraLoginOptions = ExtraLoginOptions(login_hint = "user@example.com") + ) +) + +// JWT login +val loginCompletableFuture = web3Auth.login( + LoginParams( + Provider.JWT, + extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token") + ) +) +``` + + + + + +```kotlin +// Simple social login (PnP mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) +) + +// Email passwordless (PnP mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.EMAIL_PASSWORDLESS, + loginHint = "user@example.com" // Simplified parameter + ) +) + +// JWT login (SFA mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_auth_connection_id", + idToken = "your_jwt_token" // Dedicated parameter for SFA + ) +) +``` + + + + +### 6. Private Key Method Names + +The private key retrieval methods have been renamed for clarity: + + + + + +```kotlin +val privateKey = web3Auth.getPrivKey() +val ed25519Key = web3Auth.getEd25519PrivKey() +``` + + + + + +```kotlin +val privateKey = web3Auth.getPrivateKey() +val ed25519Key = web3Auth.getEd25519PrivateKey() +``` + + + + +### 7. Wallet Services Simplification + +Wallet services methods have been simplified with automatic chain configuration: + + + + + +```kotlin +// Launch wallet services +val chainConfig = ChainConfig( + chainId = "0x1", + rpcTarget = "https://rpc.ethereum.org", + ticker = "ETH", + chainNamespace = ChainNamespace.EIP155 +) + +val launchWalletCF = web3Auth.launchWalletServices(chainConfig) + +// Request signing +val signCF = web3Auth.request( + chainConfig = chainConfig, + method = "personal_sign", + requestParams = params +) +``` + + + + + +```kotlin +// Launch wallet services (automatic chain config from dashboard) +val launchWalletCF = web3Auth.showWalletUI() + +// Request signing (automatic chain config from dashboard) +val signCF = web3Auth.request( + method = "personal_sign", + requestParams = params +) +``` + + + + +## New Features + +### 1. Single Factor Auth (SFA) Support + +v10.x introduces built-in SFA support. You can now use SFA by providing an `idToken`: + +```kotlin +// SFA login with custom JWT +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_verifier_id", + idToken = "your_jwt_token" + ) +) + +// SFA with aggregate verifier +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "aggregate_verifier_id", + groupedAuthConnectionId = "sub_verifier_id", + idToken = "your_jwt_token" + ) +) +``` + +### 2. Enhanced Parameter Handling + +v10.x provides better parameter organization: + +```kotlin +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + authConnection = AuthConnection.EMAIL_PASSWORDLESS, + loginHint = "user@example.com", // Direct parameter + dappUrl = "https://your-dapp.com", // For analytics + appState = "custom_state" // App state tracking + ) +) +``` + +### 3. Automatic Chain Configuration + +Chain configuration is now managed automatically from your Web3Auth Dashboard: + +1. Configure chains in your [Web3Auth Dashboard](https://dashboard.web3auth.io) +2. The SDK automatically uses these configurations +3. No need to manually pass `ChainConfig` to wallet services + +## Migration Steps + +### Step 1: Update Dependencies + +```groovy +// In your app-level build.gradle +dependencies { + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' +} +``` + +### Step 2: Update Imports + +Replace old imports with new ones as shown in the [Import Changes](#2-import-changes) section. + +### Step 3: Update Initialization + +1. Replace `network` with `web3AuthNetwork` +2. Replace `redirectUrl` Uri with String +3. Update `loginConfig` to `authConnectionConfig` +4. Replace `buildEnv` with `authBuildEnv` + +### Step 4: Update Authentication Calls + +1. Replace `login()` with `connectTo()` +2. Replace `Provider` with `AuthConnection` +3. Update parameter names in `LoginParams` + +### Step 5: Update Private Key Calls + +1. Replace `getPrivKey()` with `getPrivateKey()` +2. Replace `getEd25519PrivKey()` with `getEd25519PrivateKey()` + +### Step 6: Update Wallet Services + +1. Replace `launchWalletServices()` with `showWalletUI()` +2. Remove `ChainConfig` parameters from both `showWalletUI()` and `request()` + +### Step 7: Configure Dashboard + +Ensure your Web3Auth Dashboard has the necessary chain configurations since they're now automatically managed. + +## Troubleshooting + +### Common Issues + +1. **Chain Configuration Missing**: Ensure your Web3Auth Dashboard has the required chains configured +2. **Import Errors**: Make sure to import `Web3AuthNetwork` from the correct package +3. **Parameter Mismatch**: Double-check that you're using the new parameter names + +### Migration Checklist + +- [ ] Dependencies updated to v10.x +- [ ] Imports updated with new package references +- [ ] `Web3AuthOptions` configuration updated +- [ ] `login()` calls replaced with `connectTo()` +- [ ] Private key method names updated +- [ ] Wallet services methods updated +- [ ] Dashboard chain configuration verified +- [ ] Testing completed for all authentication flows + +## Support + +If you encounter any issues during migration, please: + +1. Check this migration guide thoroughly +2. Review the [updated documentation](/embedded-wallets/sdk/android) +3. Visit our [Support Forum](https://web3auth.io/community/c/help-pnp/pnp-sdk/android/16) +4. Check the [GitHub repository](https://github.com/Web3Auth/web3auth-android-sdk) for known issues + +The v10.x release provides a more robust, feature-rich, and developer-friendly experience while maintaining the core Web3Auth functionality you rely on. diff --git a/embedded-wallets/sdk/android/usage/README.mdx b/embedded-wallets/sdk/android/usage/README.mdx index 7d8724c5fcc..cac1926921d 100644 --- a/embedded-wallets/sdk/android/usage/README.mdx +++ b/embedded-wallets/sdk/android/usage/README.mdx @@ -16,10 +16,10 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Authentication functions -| Function Name | Description | -| -------------------------- | -------------------------------------------------- | -| [`login()`](./login.mdx) | Logs in the user with the selected login provider. | -| [`logout()`](./logout.mdx) | Logs out the user from the current session. | +| Function Name | Description | +| ------------------------------------ | --------------------------------------------------------------------------------------------------- | +| [`connectTo()`](./connect-to.mdx) | Logs in the user with the selected auth connection. Supports both PnP and SFA authentication modes. | +| [`logout()`](./logout.mdx) | Logs out the user from the current session. | ### User management functions @@ -31,8 +31,8 @@ For detailed usage, configuration options, and code examples, refer to the dedic | Function Name | Description | | ------------------------------------------------------ | ------------------------------------------------------------------------------- | -| [`getPrivKey()`](./get-private-key.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | -| [`getEd25519PrivKey()`](./get-ed25519-private-key.mdx) | Retrieve the user's ed25519 private key for chains like Solana, Near, Algorand. | +| [`getPrivateKey()`](./get-private-key.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | +| [`getEd25519PrivateKey()`](./get-ed25519-private-key.mdx) | Retrieve the user's ed25519 private key for chains like Solana, Near, Algorand. | ### Security functions @@ -43,7 +43,7 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Wallet Services functions -| Function Name | Description | -| -------------------------------------------------------- | ----------------------------------------------------------------- | -| [`launchWalletServices()`](./launch-wallet-services.mdx) | Launches the templated wallet UI in WebView. | -| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions. | +| Function Name | Description | +| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [`showWalletUI()`](./launch-wallet-services.mdx) | Launches the templated wallet UI in WebView with automatic chain configuration from dashboard. | +| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions with simplified parameters. | diff --git a/embedded-wallets/sdk/android/usage/connect-to.mdx b/embedded-wallets/sdk/android/usage/connect-to.mdx new file mode 100644 index 00000000000..14bcebc5130 --- /dev/null +++ b/embedded-wallets/sdk/android/usage/connect-to.mdx @@ -0,0 +1,350 @@ +--- +title: Logging in a user +sidebar_label: Sign in a user +description: 'Web3Auth Android SDK - connectTo Function | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +To sign in a user, use the `connectTo` method. +It triggers the login flow and opens a browser modal where the user can authenticate. +Pass supported auth connections to `connectTo` for specific social logins such as GOOGLE, APPLE, and FACEBOOK, or use whitelabel login. + +## Parameters + +The `connectTo` method takes `LoginParams` as a required input. + + + + + +| Parameter | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `authConnection` | It sets the OAuth login method to be used. You can use any of the supported values are `GOOGLE`, `FACEBOOK`, `REDDIT`, `DISCORD`, `TWITCH`, `APPLE`, `LINE`, `GITHUB`, `KAKAO`, `LINKEDIN`, `TWITTER`, `WEIBO`, `WECHAT`, `EMAIL_PASSWORDLESS`, `CUSTOM`, `SMS_PASSWORDLESS`, and `FARCASTER`. | +| `authConnectionId?` | The connection ID for custom authentication. This is optional for social logins but required for custom JWT-based authentication. | +| `groupedAuthConnectionId?` | Used for aggregate verifiers. When multiple auth connections are grouped under a single verifier, this specifies the aggregate verifier ID. | +| `loginHint?` | Provides a hint for the login process. For email passwordless, this should be the email address. For SMS passwordless, this should be the phone number. | +| `idToken?` | JWT token for SFA (Single Factor Auth) login. When provided, the login will use SFA mode. | +| `extraLoginOptions?` | It can be used to set the OAuth login options for corresponding `authConnection`. Default value for the field is `null`, and it accepts `ExtraLoginOptions` as a value. | +| `appState?` | It can be used to keep track of the app state when user will be redirected to app after login. Default is `null`, and accepts `String` as a value. | +| `mfaLevel?` | Customize the MFA screen shown to the user during OAuth authentication. Default value for field is `MFALevel.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | +| `dappShare?` | Custom verifier logins can get a dapp share returned to them post successful login. This is useful if the dapps want to use this share to allow users to login seamlessly. It accepts `String` as a value. | +| `curve?` | It will be used to determine the public key encoded in the jwt token which returned in `getUserInfo` function after user login. This parameter won't change format of private key returned by Web3Auth. Private key returned by `getPrivateKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivateKey` method. The default value is `Curve.SECP256K1`. | +| `dappUrl?` | URL of the dapp. This is used for analytics and debugging purposes. | + + + + + +```kotlin +data class LoginParams( + val authConnection: AuthConnection, + val authConnectionId: String? = null, + val groupedAuthConnectionId: String? = null, + val appState: String? = null, + val mfaLevel: MFALevel? = null, + val extraLoginOptions: ExtraLoginOptions? = null, + var dappShare: String? = null, + val curve: Curve? = Curve.SECP256K1, + var dappUrl: String? = null, + var loginHint: String? = null, + val idToken: String? = null, +) + +enum class AuthConnection { + @SerializedName("google") + GOOGLE, + @SerializedName("facebook") + FACEBOOK, + @SerializedName("reddit") + REDDIT, + @SerializedName("discord") + DISCORD, + @SerializedName("twitch") + TWITCH, + @SerializedName("apple") + APPLE, + @SerializedName("line") + LINE, + @SerializedName("github") + GITHUB, + @SerializedName("kakao") + KAKAO, + @SerializedName("linkedin") + LINKEDIN, + @SerializedName("twitter") + TWITTER, + @SerializedName("weibo") + WEIBO, + @SerializedName("wechat") + WECHAT, + @SerializedName("email_passwordless") + EMAIL_PASSWORDLESS, + @SerializedName("custom") + CUSTOM, //for jwt + @SerializedName("sms_passwordless") + SMS_PASSWORDLESS, + @SerializedName("farcaster") + FARCASTER +} +``` + + + + +## Usage + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) +) +// focus-end +``` + +## Examples + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.FACEBOOK) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.DISCORD) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.TWITCH) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.EMAIL_PASSWORDLESS, + loginHint = "hello@web3auth.io" + ) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.SMS_PASSWORDLESS, + loginHint = "+91-9911223344" + ) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.FARCASTER) +) +// focus-end +``` + + + + + +```kotlin title="Usage" +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_auth_connection_id", + idToken = "your_jwt_token" + ) +) +// focus-end +``` + + + diff --git a/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx b/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx index c29c182ad0b..f5d50c24714 100644 --- a/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx +++ b/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx @@ -1,15 +1,15 @@ --- title: Ed25519 private key sidebar_label: Get Ed25519 private key -description: 'Web3Auth Android SDK - getEd25519PrivKey Function | Embedded Wallets' +description: 'Web3Auth Android SDK - getEd25519PrivateKey Function | Embedded Wallets' --- -To retrieve the secp256k1 private key of the user., use `getEd25519PrivKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. +To retrieve the Ed25519 private key of the user, use `getEd25519PrivateKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. ## Usage ```kotlin -val privateKey = web3Auth.getEd25519PrivKey() +val privateKey = web3Auth.getEd25519PrivateKey() ``` :::note diff --git a/embedded-wallets/sdk/android/usage/get-private-key.mdx b/embedded-wallets/sdk/android/usage/get-private-key.mdx index 796be042d69..e440a294970 100644 --- a/embedded-wallets/sdk/android/usage/get-private-key.mdx +++ b/embedded-wallets/sdk/android/usage/get-private-key.mdx @@ -1,15 +1,15 @@ --- title: Secp256k1 private key sidebar_label: Get Secp256k1 private key -description: 'Web3Auth Android SDK - getPrivKey Function | Embedded Wallets' +description: 'Web3Auth Android SDK - getPrivateKey Function | Embedded Wallets' --- -To retrieve the secp256k1 private key of the user., use `getPrivkey` method. The method returns an EVM compatible private key which can be used to sign transactions on EVM compatible chains. +To retrieve the secp256k1 private key of the user, use `getPrivateKey` method. The method returns an EVM compatible private key which can be used to sign transactions on EVM compatible chains. ## Usage ```kotlin -val privateKey = web3Auth.getPrivKey() +val privateKey = web3Auth.getPrivateKey() ``` :::note diff --git a/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx b/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx index 1af48ba2bb0..2eaa7bda823 100644 --- a/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx +++ b/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx @@ -1,17 +1,21 @@ --- -title: Launch Wallet Services +title: Show wallet UI sidebar_label: Show wallet UI -description: 'Web3Auth Android SDK - launchWalletServices Function | Embedded Wallets' +description: 'Web3Auth Android SDK - showWalletUI Function | Embedded Wallets' --- import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The `launchWalletServices` method launches a WebView which allows you to use the templated wallet UI services. The method takes`ChainConfig` as the required input. Wallet Services is currently only available for EVM chains. +The `showWalletUI` method launches a WebView which allows you to use the templated wallet UI services. +The method automatically uses the chain configuration from your project settings and no longer requires a manual `ChainConfig` parameter. +Wallet Services is currently only available for EVM chains. :::note -Access to Wallet Services is gated. You can use this feature in `sapphire_devnet` for free. The minimum [pricing plan](https://web3auth.io/pricing.html) to use this feature in a production environment is the **Scale Plan**. +Access to Wallet Services is gated. +You can use this feature in `sapphire_devnet` for free. +The minimum [pricing plan](https://web3auth.io/pricing.html) to use this feature in a production environment is the **Scale Plan**. ::: @@ -21,64 +25,25 @@ Access to Wallet Services is gated. You can use this feature in `sapphire_devnet alt="Wallet Services" /> -## Parameters +:::warning - +The chain configuration is now automatically retrieved from your project settings in the Embedded Wallets dashboard. +Make sure your project has the appropriate chains configured in the dashboard. - - -| Parameter | Description | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `chainNamespace` | Custom configuration for your preferred blockchain. As of now only EVM supported. Default value is `ChainNamespace.EIP155`. | -| `decimals?` | Number of decimals for the currency ticker. Default value is 18, and accepts `Int` as value. | -| `blockExplorerUrl?` | Blockchain's explorer URL. (for example, `https://etherscan.io`) | -| `chainId` | The chain ID of the selected blockchain in hex `String`. | -| `displayName?` | Display Name for the chain. | -| `logo?` | Logo for the selected `chainNamespace` and `chainId`. | -| `rpcTarget` | RPC Target URL for the selected `chainNamespace` & `chainId`. | -| `ticker?` | Default currency ticker of the network (for example, `ETH`) | -| `tickerName?` | Name for currency ticker (for example, `Ethereum`) | - - +::: - +## Usage ```kotlin -data class ChainConfig( - val chainNamespace: ChainNamespace = ChainNamespace.EIP155, - val decimals: Int? = 18, - val blockExplorerUrl: String? = null, - val chainId: String, - val displayName: String? = null, - val logo: String? = null, - val rpcTarget: String, - val ticker: String?, - val tickerName: String? = null, -) +// focus-start +val completableFuture = web3Auth.showWalletUI() +// focus-end ``` - - - -## Usage +You can also specify a custom path: ```kotlin -val chainConfig = ChainConfig( - chainId = "0x1", - rpcTarget = "https://rpc.ethereum.org", - ticker = "ETH", - chainNamespace = ChainNamespace.EIP155 -) - // focus-start -val completableFuture = web3Auth.launchWalletServices( - chainConfig -) +val completableFuture = web3Auth.showWalletUI("custom-wallet-path") // focus-end ``` diff --git a/embedded-wallets/sdk/android/usage/login.mdx b/embedded-wallets/sdk/android/usage/login.mdx deleted file mode 100644 index e84b8ef2b78..00000000000 --- a/embedded-wallets/sdk/android/usage/login.mdx +++ /dev/null @@ -1,331 +0,0 @@ ---- -title: Logging in a user -sidebar_label: Sign in a user -description: 'Web3Auth Android SDK - Login Function | Embedded Wallets' ---- - -import TabItem from '@theme/TabItem' -import Tabs from '@theme/Tabs' - -To login in a user, you can use the `login` method. It will trigger login flow will navigate the user to a browser model allowing the user to login into the service. You can pass in the supported providers to the login method for specific social logins (such as GOOGLE, APPLE, FACEBOOK) and do whitelabel login. - -## Parameters - -The `login` method takes in `LoginParams` as a required input. - - - - - -| Parameter | Description | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `loginProvider` | It sets the OAuth login method to be used. You can use any of the supported values are `GOOGLE`, `FACEBOOK`, `REDDIT`, `DISCORD`, `TWITCH`, `APPLE`, `LINE`, `GITHUB`, `KAKAO`, `LINKEDIN`, `TWITTER`, `WEIBO`, `WECHAT`, `EMAIL_PASSWORDLESS`, `JWT`, `SMS_PASSWORDLESS`, and `FARCASTER`. | -| `extraLoginOptions?` | It can be used to set the OAuth login options for corresponding `loginProvider`. For instance, you'll need to pass user's email address as. Default value for the field is `null`, and it accepts `ExtraLoginOptions` as a value. | -| `redirectUrl?` | URL where user will be redirected after successfull login. By default user will be redirected to same page where login will be initiated. Default value for the field is `null`, and accepts `Uri` as a value. | -| `appState?` | It can be used to keep track of the app state when user will be redirected to app after login. Default is `null`, and accepts a string value. | -| `mfaLevel?` | Customize the MFA screen shown to the user during OAuth authentication. Default value for field is `MFALevel.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | -| `dappShare?` | Custom verifier logins can get a dapp share returned to them post successful login. This is useful if the dapps want to use this share to allow users to sign in without repeating the full flow. It accepts a string value. | -| `curve?` | It will be used to determine the public key encoded in the JWT token which returned in `getUserInfo` function after user login. This parameter won't change format of private key returned by We3Auth. Private key returned by `getPrivKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivKey` method. The default value is `Curve.SECP256K1`. | - - - - - -```kotlin -data class LoginParams( - val loginProvider: Provider, - var dappShare: String? = null, - val extraLoginOptions: ExtraLoginOptions? = null, - @Transient var redirectUrl: Uri? = null, - val appState: String? = null, - val mfaLevel: MFALevel? = null, - val curve: Curve? = Curve.SECP256K1 -) - -enum class Provider { - @SerializedName("google") - GOOGLE, - @SerializedName("facebook") - FACEBOOK, - @SerializedName("reddit") - REDDIT, - @SerializedName("discord") - DISCORD, - @SerializedName("twitch") - TWITCH, - @SerializedName("apple") - APPLE, - @SerializedName("line") - LINE, - @SerializedName("github") - GITHUB, - @SerializedName("kakao") - KAKAO, - @SerializedName("linkedin") - LINKEDIN, - @SerializedName("twitter") - TWITTER, - @SerializedName("weibo") - WEIBO, - @SerializedName("wechat") - WECHAT, - @SerializedName("email_passwordless") - EMAIL_PASSWORDLESS, - @SerializedName("jwt") - JWT, - @SerializedName("sms_passwordless") - SMS_PASSWORDLESS, - @SerializedName("farcaster") - FARCASTER -} -``` - - - - -## Usage - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.GOOGLE) -) -// focus-end -``` - -## Examples - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.GOOGLE) -) -// focus-end -``` - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.FACEBOOK) -) -// focus-end -``` - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.DISCORD) -) -// focus-end -``` - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.TWITCH) -) -// focus-end -``` - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams( - Provider.EMAIL_PASSWORDLESS, - extraLoginOptions = ExtraLoginOptions(login_hint = "hello@web3auth.io") - ) -) -// focus-end -``` - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( -Web3AuthOptions( -context = this, -clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable -network = Network.MAINNET, -redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), -) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( -LoginParams( -Provider.SMS_PASSWORDLESS, -extraLoginOptions = ExtraLoginOptions(login_hint = "+91-9911223344") -) -) -// focus-end - -``` - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.Farcaster) -) -// focus-end -``` - - - - - -```kotlin title="Usage" -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions - -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) -) - -// focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams( - Provider.JWT, - extraLoginOptions = ExtraLoginOptions(id_token = "") - ) -) -// focus-end -``` - - - diff --git a/embedded-wallets/sdk/android/usage/request.mdx b/embedded-wallets/sdk/android/usage/request.mdx index f09c6e1fe85..a8f140d0e05 100644 --- a/embedded-wallets/sdk/android/usage/request.mdx +++ b/embedded-wallets/sdk/android/usage/request.mdx @@ -18,9 +18,15 @@ Please check the list of [JSON RPC methods](https://docs.metamask.io/wallet/refe | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chainConifg` | Defines the chain to be used for signature request. | -| `method` | JSON RPC method name in `String`. Currently, the request method only supports the singing methods. | +| `method` | JSON RPC method name in `String`. Currently, the request method only supports the signing methods. | | `requestParams` | Parameters for the corresponding method. The parameters should be in the list and correct sequence. Take a look at [RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/) to know more. | +| `appState?` | It can be used to keep track of the app state. Default is `null`, and accepts `String` as a value. | + +:::warning + +The chain configuration is now automatically retrieved from your project settings in the Web3Auth Dashboard. The request will use the appropriate chain based on your project configuration. + +::: ## Usage @@ -32,16 +38,8 @@ val params = JsonArray().apply { add(address) } -val chainConfig = ChainConfig( - chainId = "0x1", - rpcTarget = "https://rpc.ethereum.org", - ticker = "ETH", - chainNamespace = ChainNamespace.EIP155 -) - // focus-start val signMsgCompletableFuture = web3Auth.request( - chainConfig = chainConfig, "personal_sign", requestParams = params ) diff --git a/ew-sidebar.js b/ew-sidebar.js index d6e38316270..91139e985e0 100644 --- a/ew-sidebar.js +++ b/ew-sidebar.js @@ -746,7 +746,7 @@ const sidebar = { label: 'Usage', items: [ 'sdk/android/usage/README', - 'sdk/android/usage/login', + 'sdk/android/usage/connect-to', 'sdk/android/usage/get-user-info', 'sdk/android/usage/get-private-key', 'sdk/android/usage/get-ed25519-private-key', diff --git a/src/pages/quickstart/builder/embedded-wallets/android/stepContent/signin.mdx b/src/pages/quickstart/builder/embedded-wallets/android/stepContent/signin.mdx index ff657c86806..ff34835cebc 100644 --- a/src/pages/quickstart/builder/embedded-wallets/android/stepContent/signin.mdx +++ b/src/pages/quickstart/builder/embedded-wallets/android/stepContent/signin.mdx @@ -1,6 +1,6 @@ ### Sign in the user -Use the [`login`](/embedded-wallets/sdk/android/usage/login) function to access +Use the [`connectTo`](/embedded-wallets/sdk/android/usage/connect-to) function to access the sign-in functionality. You can trigger this function from a button or other user action. diff --git a/src/pages/tutorials/android-wallet.mdx b/src/pages/tutorials/android-wallet.mdx index 288c978c6d1..cc5c7ef03af 100644 --- a/src/pages/tutorials/android-wallet.mdx +++ b/src/pages/tutorials/android-wallet.mdx @@ -71,7 +71,7 @@ dependencyResolutionManagement { dependencies { // ... // focus-next-line - implementation 'com.github.web3auth:web3auth-android-sdk:7.4.0' + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' } ``` @@ -250,7 +250,7 @@ blockchain. Along with that, we'll retrieve user info, and navigate them to `Hom :::note -Learn more about [Embedded Wallets' `LoginParams`](/embedded-wallets/sdk/android/usage/login#parameters). +Learn more about [Embedded Wallets' `LoginParams`](/embedded-wallets/sdk/android/usage/connect-to#parameters). ::: diff --git a/src/utils/w3a-sdk-map.js b/src/utils/w3a-sdk-map.js index 0148225dbb3..0116fd3f3f8 100644 --- a/src/utils/w3a-sdk-map.js +++ b/src/utils/w3a-sdk-map.js @@ -14,7 +14,7 @@ export const unity = 'Unity' export const unreal = 'Unreal Engine' export const pnpWebVersion = `11.0.x` -export const pnpAndroidVersion = `9.1.2` +export const pnpAndroidVersion = `10.0.x` export const pnpIOSVersion = `11.1.0` export const pnpRNVersion = `8.1.x` export const pnpNodeVersion = `5.0.x` @@ -22,18 +22,6 @@ export const pnpFlutterVersion = `6.1.2` export const pnpUnityVersion = `7.0.x` export const pnpUnrealVersion = `4.1.x` -export const sfaWebVersion = `9.2.x` -export const sfaAndroidVersion = `4.0.1` -export const sfaIOSVersion = `9.1.0` -export const sfaRNVersion = `2.0.x` -export const sfaFlutterVersion = `6.0.0` -export const sfaNodeJSVersion = `7.4.x` -export const tkeyJSVersion = `15.x.x` -export const tkeyAndroidVersion = `0.0.5` -export const tkeyIOSVersion = `0.0.4` -export const mpcCoreKitJSVersion = `3.4.x` -export const mpcCoreKitReactNativeVersion = `1.0.0` - export function getPnPVersion(platform) { if (platform === web) { return pnpWebVersion @@ -56,31 +44,4 @@ export function getPnPVersion(platform) { if (platform === unreal) { return pnpUnrealVersion } - if (platform === node) { - return pnpNodeVersion - } -} - -export function getSFAVersion(platform) { - if (platform === reactnative) { - return sfaRNVersion - } - if (platform === android) { - return sfaAndroidVersion - } - if (platform === ios) { - return sfaIOSVersion - } - if (platform === flutter) { - return sfaFlutterVersion - } -} - -export function getMPCCoreKitVersion(platform) { - if (platform === js) { - return mpcCoreKitJSVersion - } - if (platform === reactnative) { - return mpcCoreKitReactNativeVersion - } } diff --git a/vercel.json b/vercel.json index e07a3d87f83..6e473386a53 100644 --- a/vercel.json +++ b/vercel.json @@ -872,6 +872,31 @@ "destination": "/embedded-wallets/sdk/android/usage/manage-mfa/", "permanent": true }, + { + "source": "/embedded-wallets/sdk/android/usage/login/", + "destination": "/embedded-wallets/sdk/android/usage/connect-to/", + "permanent": true + }, + { + "source": "/embedded-wallets/sdk/android/usage/connectTo/", + "destination": "/embedded-wallets/sdk/android/usage/connect-to/", + "permanent": true + }, + { + "source": "/embedded-wallets/sdk/android/usage/getPrivateKey/", + "destination": "/embedded-wallets/sdk/android/usage/get-private-key/", + "permanent": true + }, + { + "source": "/embedded-wallets/sdk/android/usage/getEd25519PrivateKey/", + "destination": "/embedded-wallets/sdk/android/usage/get-ed25519-private-key/", + "permanent": true + }, + { + "source": "/embedded-wallets/sdk/android/usage/showWalletUI/", + "destination": "/embedded-wallets/sdk/android/usage/launch-wallet-services/", + "permanent": true + }, { "source": "/embedded-wallets/sdk/flutter/usage/enableMFA/", "destination": "/embedded-wallets/sdk/flutter/usage/enable-mfa/", From d524c501d9dd4a7c9203ba85fc8c34808d155c73 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Wed, 24 Sep 2025 23:21:11 +0400 Subject: [PATCH 02/12] Updates wrt comments in PR --- .../advanced/custom-authentication.mdx | 23 +- .../sdk/android/advanced/smart-accounts.mdx | 320 ++++++++++++++++++ .../android/usage/launch-wallet-services.mdx | 37 +- .../sdk/android/usage/request.mdx | 74 +++- ew-sidebar.js | 1 + 5 files changed, 449 insertions(+), 6 deletions(-) create mode 100644 embedded-wallets/sdk/android/advanced/smart-accounts.mdx diff --git a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx index 6dabd09cde2..0ef478f66a8 100644 --- a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx @@ -308,7 +308,8 @@ Additional to the `LoginConfig` you can pass extra options to the `login` functi | `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | | `id_token_hint?` | It denotes the previously issued ID token. It takes `String` as a value. | | `id_token?` | JWT (ID Token) to be passed for login. | -| `login_hint?` | Used to specify the user's email address or phone number for Email/SMS Passwordless login flows. Takes a `String` value. For the SMS, the format should be: `+{country_code}-{phone_number}` (e.g. `+1-1234567890`) | +| `access_token?` | Access token for OAuth flows. It takes `String` as a value. | +| `flow_type?` | Specifies the email passwordless flow type. It takes `EmailFlowType` as a value (`CODE` or `LINK`). | | `acr_values?` | acc_values | | `scope?` | The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It takes `String` as a value. | | `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It takes `String` as a value. | @@ -336,7 +337,8 @@ data class ExtraLoginOptions( private var ui_locales : String? = null, private var id_token : String? = null, private var id_token_hint : String? = null, - private var login_hint : String? = null, + private var access_token : String? = null, + private var flow_type : EmailFlowType? = null, private var acr_values : String? = null, private var scope : String? = null, private var audience : String? = null, @@ -346,6 +348,13 @@ data class ExtraLoginOptions( private var nonce : String? = null, private var redirect_uri : String? = null ) + +enum class EmailFlowType { + @SerializedName("code") + CODE, + @SerializedName("link") + LINK +} ``` @@ -440,6 +449,7 @@ val loginCompletableFuture: CompletableFuture = web3Auth.conne + To use the Email Passwordless login, you need to put the email into the `loginHint` parameter of the `LoginParams`. By default, the login flow will be `code` flow, if you want to use the `link` flow, you need to put `flow_type` into the `extraLoginOptions` parameter. @@ -461,8 +471,12 @@ val web3Auth = Web3Auth( val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( AuthConnection.EMAIL_PASSWORDLESS, - // focus-next-line - loginHint = "hello@web3auth.io" + // focus-start + loginHint = "hello@web3auth.io", + extraLoginOptions = ExtraLoginOptions( + flow_type = EmailFlowType.CODE // Use CODE for OTP flow or LINK for magic link flow + ) + // focus-end ) ) ``` @@ -470,6 +484,7 @@ val loginCompletableFuture: CompletableFuture = web3Auth.conne + To use the SMS Passwordless login, send the phone number as the `loginHint` parameter of the `LoginParams`. Please make sure the phone number is in the format of +\{country_code}-\{phone_number}, i.e. (+91-09xx901xx1). diff --git a/embedded-wallets/sdk/android/advanced/smart-accounts.mdx b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx new file mode 100644 index 00000000000..bbf2c8ed822 --- /dev/null +++ b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx @@ -0,0 +1,320 @@ +--- +title: Smart Accounts (Account Abstraction) +sidebar_label: Smart Accounts +description: 'Web3Auth Android SDK - Smart Accounts | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' +import GrowthPlanNote from '../../_common/_growth_plan_note.mdx' + +Effortlessly create and manage smart accounts for your users with Web3Auth's native Account Abstraction support. Smart accounts offer enhanced control and programmability, enabling powerful features that traditional wallets can't provide. + + + +## Overview + +Web3Auth Android SDK v10.x includes built-in support for ERC-4337 smart accounts. When enabled, your users automatically get smart contract wallets with advanced features like: + +- **Gas Sponsorship**: Cover transaction fees for your users +- **Batch Transactions**: Execute multiple operations in a single transaction +- **ERC-20 Token Gas Payments**: Let users pay gas fees with any ERC-20 token +- **Transaction Policies**: Set spending limits and automated rules +- **Account Recovery**: Enhanced security with social recovery options + +## Dashboard Configuration + +To enable smart accounts for your Android application: + +1. Navigate to your project in the [Web3Auth Dashboard](https://dashboard.web3auth.io) +2. Go to **Project Settings** → **Smart Accounts** +3. Enable smart accounts by toggling the switch +4. Configure your preferred providers: + - **Bundler**: Automatically configured (powered by Pimlico) + - **Paymaster**: Choose between sponsored transactions or ERC-20 payments + - **Smart Account Type**: Select your preferred implementation + +## Implementation + +### Checking Smart Account Status + +Once configured in the dashboard, smart accounts are automatically used when users authenticate: + +```kotlin +// After successful authentication +val userInfo = web3Auth.getUserInfo() +val isSmartAccount = userInfo?.isSmartAccountEnabled ?: false + +if (isSmartAccount) { + // User has a smart account + val smartAccountAddress = userInfo?.smartAccountAddress + Log.d("Smart Account", "Address: $smartAccountAddress") +} +``` + +### Getting Smart Account Address + +The smart account address is different from the EOA address: + +```kotlin +// Get EOA address (traditional wallet) +val eoaAddress = web3Auth.getAddress() + +// Get smart account address (from user info) +val userInfo = web3Auth.getUserInfo() +val smartAccountAddress = userInfo?.smartAccountAddress + +Log.d("Addresses", "EOA: $eoaAddress, Smart Account: $smartAccountAddress") +``` + +### Sending User Operations + +With smart accounts enabled, you can send user operations through the `request` method: + +```kotlin +// Prepare user operation +val userOp = JsonObject().apply { + addProperty("sender", smartAccountAddress) + addProperty("nonce", "0x0") + addProperty("initCode", "0x") + addProperty("callData", encodedCallData) + addProperty("callGasLimit", "0x5208") + addProperty("verificationGasLimit", "0x5208") + addProperty("preVerificationGas", "0x5208") + addProperty("maxFeePerGas", "0x3b9aca00") + addProperty("maxPriorityFeePerGas", "0x3b9aca00") + addProperty("paymasterAndData", "0x") // Auto-filled by dashboard config + addProperty("signature", "0x") +} + +val params = JsonArray().apply { + add(userOp) +} + +// Send user operation +val userOpResult = web3Auth.request( + "eth_sendUserOperation", + requestParams = params +) + +userOpResult.whenComplete { result, error -> + if (error == null) { + val userOpHash = result?.get("result")?.asString + Log.d("UserOp", "Hash: $userOpHash") + } else { + Log.e("UserOp", "Error: ${error.message}") + } +} +``` + +### Batch Transactions + +Execute multiple transactions in a single user operation: + +```kotlin +// Prepare multiple calls +val calls = JsonArray().apply { + // First call: Transfer ETH + add(JsonObject().apply { + addProperty("to", "0x...") + addProperty("value", "0x1") + addProperty("data", "0x") + }) + + // Second call: ERC20 transfer + add(JsonObject().apply { + addProperty("to", erc20Address) + addProperty("value", "0x0") + addProperty("data", encodedTransferData) + }) +} + +// Encode batch call +val batchCallData = encodeBatchCall(calls) + +// Send as user operation +val userOp = JsonObject().apply { + addProperty("sender", smartAccountAddress) + addProperty("callData", batchCallData) + // ... other fields +} +``` + +### Gas Sponsorship + +When configured in the dashboard, gas sponsorship is automatically handled: + +```kotlin +// Transaction with sponsored gas +val sponsoredTx = JsonObject().apply { + addProperty("to", recipientAddress) + addProperty("value", "0x1000") + addProperty("data", "0x") +} + +// The paymasterAndData field is automatically populated +val result = web3Auth.request( + "eth_sendTransaction", + requestParams = JsonArray().apply { add(sponsoredTx) } +) + +// User pays nothing for gas! +``` + +### ERC-20 Gas Payments + +Allow users to pay gas fees with ERC-20 tokens: + +```kotlin +// Configure ERC-20 paymaster in dashboard first +// Then transactions automatically use ERC-20 for gas + +val transaction = JsonObject().apply { + addProperty("to", recipientAddress) + addProperty("value", amount) + addProperty("data", "0x") + // Specify the token for gas payment (optional) + addProperty("paymasterData", JsonObject().apply { + addProperty("token", "USDC") + }) +} + +val result = web3Auth.request( + "eth_sendTransaction", + requestParams = JsonArray().apply { add(transaction) } +) +``` + +## Wallet UI Integration + +The `showWalletUI()` method automatically supports smart account features: + +```kotlin +// Launch wallet UI with smart account support +val walletResult = web3Auth.showWalletUI() + +walletResult.whenComplete { _, error -> + if (error == null) { + // Wallet UI will show: + // - Smart account address + // - Batch transaction options + // - Gas sponsorship status + // - ERC-20 gas payment options + } +} +``` + +## Best Practices + +### 1. Address Management + +Always distinguish between EOA and smart account addresses: + +```kotlin +class WalletManager(private val web3Auth: Web3Auth) { + + fun getActiveAddress(): String { + val userInfo = web3Auth.getUserInfo() + return if (userInfo?.isSmartAccountEnabled == true) { + userInfo.smartAccountAddress ?: getEOAAddress() + } else { + getEOAAddress() + } + } + + private fun getEOAAddress(): String { + return web3Auth.getAddress() + } +} +``` + +### 2. Error Handling + +Handle smart account-specific errors: + +```kotlin +web3Auth.request(method, params).whenComplete { result, error -> + when { + error?.message?.contains("insufficient paymaster funds") == true -> { + // Handle paymaster balance issues + showError("Transaction sponsorship unavailable") + } + error?.message?.contains("user operation") == true -> { + // Handle user operation errors + showError("Smart account operation failed") + } + error != null -> { + // Generic error handling + showError(error.message ?: "Transaction failed") + } + else -> { + // Success + handleSuccess(result) + } + } +} +``` + +### 3. Feature Detection + +Check for smart account features before using them: + +```kotlin +class SmartAccountFeatures(private val web3Auth: Web3Auth) { + + fun isAvailable(): Boolean { + val projectConfig = web3Auth.getProjectConfiguration() + return projectConfig?.smartAccounts?.enabled == true + } + + fun isGasSponsorshipEnabled(): Boolean { + val projectConfig = web3Auth.getProjectConfiguration() + return projectConfig?.smartAccounts?.sponsorshipEnabled == true + } + + fun supportsBatchTransactions(): Boolean { + return isAvailable() // All smart accounts support batching + } +} +``` + +## Migration from EOA + +If you're migrating from EOA to smart accounts: + +```kotlin +// Before (EOA) +val address = web3Auth.getAddress() +val privateKey = web3Auth.getPrivateKey() + +// After (Smart Account) +val userInfo = web3Auth.getUserInfo() +val address = userInfo?.smartAccountAddress ?: web3Auth.getAddress() +// Private key is managed by the smart account contract +``` + +## Troubleshooting + +### Common Issues + +1. **Smart account not created**: Ensure smart accounts are enabled in dashboard +2. **User operation failing**: Check bundler and paymaster configuration +3. **Gas sponsorship not working**: Verify paymaster balance and limits +4. **Wrong address used**: Always use `smartAccountAddress` for transactions + +### Debug Mode + +Enable verbose logging for smart account operations: + +```kotlin +val web3AuthOptions = Web3AuthOptions( + // ... other options + enableLogging = true +) +``` + +## Learn More + +- [Account Abstraction Overview](/embedded-wallets/features/smart-accounts) +- [ERC-4337 Specification](https://eips.ethereum.org/EIPS/eip-4337) +- [Web3Auth Dashboard Guide](https://dashboard.web3auth.io) diff --git a/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx b/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx index 2eaa7bda823..2c84778b752 100644 --- a/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx +++ b/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx @@ -9,7 +9,14 @@ import Tabs from '@theme/Tabs' The `showWalletUI` method launches a WebView which allows you to use the templated wallet UI services. The method automatically uses the chain configuration from your project settings and no longer requires a manual `ChainConfig` parameter. -Wallet Services is currently only available for EVM chains. + +### Supported features + +- **EVM chains**: Full support for all EVM-compatible chains +- **Account abstraction**: Built-in support for smart accounts (ERC-4337) +- **Gas sponsorship**: Cover transaction fees for your users +- **Batch transactions**: Execute multiple transactions in one go +- **Custom spending limits**: Set transaction limits for enhanced security :::note @@ -47,3 +54,31 @@ You can also specify a custom path: val completableFuture = web3Auth.showWalletUI("custom-wallet-path") // focus-end ``` + +## Smart accounts configuration + +When smart accounts are enabled in your Embedded Wallets dashboard, the wallet UI automatically provides account abstraction features. + +### Dashboard configuration + +1. Navigate to your project in the [Embedded Wallets dashboard](https://developer.metamask.io) +2. Enable Smart Accounts in your project settings +3. Configure your preferred bundler and paymaster providers + +### Features available + +Once configured, users can: + +- **Send gasless transactions**: Transactions can be sponsored by your paymaster +- **Batch operations**: Multiple transactions can be bundled and executed as one +- **ERC-20 token payments**: Users can pay gas fees using ERC-20 tokens instead of native tokens +- **Automated transaction policies**: Set up rules for automatic transaction execution + +### User experience + +When smart accounts are enabled: + +1. Users will see a smart account address instead of an EOA address +2. Transaction confirmation screens will show sponsorship details +3. Batch transaction options will be available in the wallet UI +4. Gas payment options will include ERC-20 tokens if configured diff --git a/embedded-wallets/sdk/android/usage/request.mdx b/embedded-wallets/sdk/android/usage/request.mdx index a8f140d0e05..935d0e25909 100644 --- a/embedded-wallets/sdk/android/usage/request.mdx +++ b/embedded-wallets/sdk/android/usage/request.mdx @@ -18,8 +18,9 @@ Please check the list of [JSON RPC methods](https://docs.metamask.io/wallet/refe | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `method` | JSON RPC method name in `String`. Currently, the request method only supports the signing methods. | +| `method` | JSON RPC method name in `String`. Supports signing methods and smart account operations (see supported methods below). | | `requestParams` | Parameters for the corresponding method. The parameters should be in the list and correct sequence. Take a look at [RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/) to know more. | +| `path?` | The path where the signing service is located. Default value is `"wallet/request"`. This is an internal routing path for the wallet services infrastructure. | | `appState?` | It can be used to keep track of the app state. Default is `null`, and accepts `String` as a value. | :::warning @@ -28,8 +29,28 @@ The chain configuration is now automatically retrieved from your project setting ::: +## Supported Methods + +### Standard Signing Methods + +- `personal_sign` - Sign a message +- `eth_sign` - Sign data +- `eth_signTypedData` - Sign typed structured data +- `eth_signTypedData_v4` - Sign typed structured data (v4) +- `eth_sendTransaction` - Send a transaction + +### Smart Account Operations + +When smart accounts are enabled in your dashboard, additional methods are available: + +- `eth_sendUserOperation` - Send a user operation for account abstraction +- `eth_estimateUserOperationGas` - Estimate gas for a user operation +- `wallet_showUserOperation` - Display user operation details in wallet UI + ## Usage +### Standard Transaction Signing + ```kotlin val params = JsonArray().apply { // Message to be signed @@ -56,6 +77,57 @@ signMsgCompletableFuture.whenComplete { signResult, error -> } ``` +### Smart Account User Operation + +When smart accounts are enabled, you can send user operations: + +```kotlin +// Build user operation parameters +val userOp = JsonObject().apply { + addProperty("sender", smartAccountAddress) + addProperty("nonce", "0x0") + addProperty("initCode", "0x") + addProperty("callData", encodedCallData) + addProperty("callGasLimit", "0x5208") + addProperty("verificationGasLimit", "0x5208") + addProperty("preVerificationGas", "0x5208") + addProperty("maxFeePerGas", "0x3b9aca00") + addProperty("maxPriorityFeePerGas", "0x3b9aca00") + addProperty("paymasterAndData", "0x") + addProperty("signature", "0x") +} + +val params = JsonArray().apply { + add(userOp) +} + +// focus-start +val userOpCompletableFuture = web3Auth.request( + "eth_sendUserOperation", + requestParams = params +) +// focus-end + +userOpCompletableFuture.whenComplete { result, error -> + if (error == null) { + // focus-next-line + Log.d("UserOp Hash", result.toString()) + } else { + Log.d("UserOp Error", error.message ?: "Failed to send user operation") + } +} +``` + +:::tip + +For smart account operations, the Web3Auth dashboard will automatically handle: + +- Bundler URL configuration +- Paymaster integration for sponsored transactions +- User operation validation + +::: + ## SignResponse | Name | Description | diff --git a/ew-sidebar.js b/ew-sidebar.js index 91139e985e0..3a40d65e16d 100644 --- a/ew-sidebar.js +++ b/ew-sidebar.js @@ -735,6 +735,7 @@ const sidebar = { label: 'Advanced', items: [ 'sdk/android/advanced/README', + 'sdk/android/advanced/smart-accounts', 'sdk/android/advanced/custom-authentication', 'sdk/android/advanced/whitelabel', 'sdk/android/advanced/mfa', From 7e8ed1d7a153ff25a2e1b860d1ab3cea281ee8c4 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Wed, 24 Sep 2025 23:22:21 +0400 Subject: [PATCH 03/12] Fix checklist --- .../migration-guides/android-v9-to-v10.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx index d11daa7e0eb..b8ea6c0af3c 100644 --- a/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx +++ b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx @@ -393,14 +393,14 @@ Ensure your Web3Auth Dashboard has the necessary chain configurations since they ### Migration Checklist -- [ ] Dependencies updated to v10.x -- [ ] Imports updated with new package references -- [ ] `Web3AuthOptions` configuration updated -- [ ] `login()` calls replaced with `connectTo()` -- [ ] Private key method names updated -- [ ] Wallet services methods updated -- [ ] Dashboard chain configuration verified -- [ ] Testing completed for all authentication flows +- Dependencies updated to v10.x +- Imports updated with new package references +- `Web3AuthOptions` configuration updated +- `login()` calls replaced with `connectTo()` +- Private key method names updated +- Wallet services methods updated +- Dashboard chain configuration verified +- Testing completed for all authentication flows ## Support From 188ef72a2e93e3c9b91db426c76d6cf9d33300df Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Wed, 24 Sep 2025 23:34:08 +0400 Subject: [PATCH 04/12] Add params for web3auth options --- embedded-wallets/sdk/android/advanced/README.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/embedded-wallets/sdk/android/advanced/README.mdx b/embedded-wallets/sdk/android/advanced/README.mdx index 2b1dda7b8ea..e41f6cfd716 100644 --- a/embedded-wallets/sdk/android/advanced/README.mdx +++ b/embedded-wallets/sdk/android/advanced/README.mdx @@ -56,6 +56,8 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. | `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is 86400 seconds which is 1 day. `sessionTime` can be max 30 days. | | `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for wallet pregeneration and SFA mode. | | `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. | +| `defaultChainId?` | Default chain ID to use. It's an optional field with default value as `null`. The first chain in the list will be used if not provided. | +| `enableLogging?` | Setting to true will enable logs. It's an optional field with default value as `false`. | From c65fb3ce1cbdc5665c47b41a3922925ae7a4a90e Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Wed, 1 Oct 2025 14:46:08 +0800 Subject: [PATCH 05/12] Delete smart-accounts.mdx --- .../sdk/android/advanced/smart-accounts.mdx | 320 ------------------ 1 file changed, 320 deletions(-) delete mode 100644 embedded-wallets/sdk/android/advanced/smart-accounts.mdx diff --git a/embedded-wallets/sdk/android/advanced/smart-accounts.mdx b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx deleted file mode 100644 index bbf2c8ed822..00000000000 --- a/embedded-wallets/sdk/android/advanced/smart-accounts.mdx +++ /dev/null @@ -1,320 +0,0 @@ ---- -title: Smart Accounts (Account Abstraction) -sidebar_label: Smart Accounts -description: 'Web3Auth Android SDK - Smart Accounts | Embedded Wallets' ---- - -import TabItem from '@theme/TabItem' -import Tabs from '@theme/Tabs' -import GrowthPlanNote from '../../_common/_growth_plan_note.mdx' - -Effortlessly create and manage smart accounts for your users with Web3Auth's native Account Abstraction support. Smart accounts offer enhanced control and programmability, enabling powerful features that traditional wallets can't provide. - - - -## Overview - -Web3Auth Android SDK v10.x includes built-in support for ERC-4337 smart accounts. When enabled, your users automatically get smart contract wallets with advanced features like: - -- **Gas Sponsorship**: Cover transaction fees for your users -- **Batch Transactions**: Execute multiple operations in a single transaction -- **ERC-20 Token Gas Payments**: Let users pay gas fees with any ERC-20 token -- **Transaction Policies**: Set spending limits and automated rules -- **Account Recovery**: Enhanced security with social recovery options - -## Dashboard Configuration - -To enable smart accounts for your Android application: - -1. Navigate to your project in the [Web3Auth Dashboard](https://dashboard.web3auth.io) -2. Go to **Project Settings** → **Smart Accounts** -3. Enable smart accounts by toggling the switch -4. Configure your preferred providers: - - **Bundler**: Automatically configured (powered by Pimlico) - - **Paymaster**: Choose between sponsored transactions or ERC-20 payments - - **Smart Account Type**: Select your preferred implementation - -## Implementation - -### Checking Smart Account Status - -Once configured in the dashboard, smart accounts are automatically used when users authenticate: - -```kotlin -// After successful authentication -val userInfo = web3Auth.getUserInfo() -val isSmartAccount = userInfo?.isSmartAccountEnabled ?: false - -if (isSmartAccount) { - // User has a smart account - val smartAccountAddress = userInfo?.smartAccountAddress - Log.d("Smart Account", "Address: $smartAccountAddress") -} -``` - -### Getting Smart Account Address - -The smart account address is different from the EOA address: - -```kotlin -// Get EOA address (traditional wallet) -val eoaAddress = web3Auth.getAddress() - -// Get smart account address (from user info) -val userInfo = web3Auth.getUserInfo() -val smartAccountAddress = userInfo?.smartAccountAddress - -Log.d("Addresses", "EOA: $eoaAddress, Smart Account: $smartAccountAddress") -``` - -### Sending User Operations - -With smart accounts enabled, you can send user operations through the `request` method: - -```kotlin -// Prepare user operation -val userOp = JsonObject().apply { - addProperty("sender", smartAccountAddress) - addProperty("nonce", "0x0") - addProperty("initCode", "0x") - addProperty("callData", encodedCallData) - addProperty("callGasLimit", "0x5208") - addProperty("verificationGasLimit", "0x5208") - addProperty("preVerificationGas", "0x5208") - addProperty("maxFeePerGas", "0x3b9aca00") - addProperty("maxPriorityFeePerGas", "0x3b9aca00") - addProperty("paymasterAndData", "0x") // Auto-filled by dashboard config - addProperty("signature", "0x") -} - -val params = JsonArray().apply { - add(userOp) -} - -// Send user operation -val userOpResult = web3Auth.request( - "eth_sendUserOperation", - requestParams = params -) - -userOpResult.whenComplete { result, error -> - if (error == null) { - val userOpHash = result?.get("result")?.asString - Log.d("UserOp", "Hash: $userOpHash") - } else { - Log.e("UserOp", "Error: ${error.message}") - } -} -``` - -### Batch Transactions - -Execute multiple transactions in a single user operation: - -```kotlin -// Prepare multiple calls -val calls = JsonArray().apply { - // First call: Transfer ETH - add(JsonObject().apply { - addProperty("to", "0x...") - addProperty("value", "0x1") - addProperty("data", "0x") - }) - - // Second call: ERC20 transfer - add(JsonObject().apply { - addProperty("to", erc20Address) - addProperty("value", "0x0") - addProperty("data", encodedTransferData) - }) -} - -// Encode batch call -val batchCallData = encodeBatchCall(calls) - -// Send as user operation -val userOp = JsonObject().apply { - addProperty("sender", smartAccountAddress) - addProperty("callData", batchCallData) - // ... other fields -} -``` - -### Gas Sponsorship - -When configured in the dashboard, gas sponsorship is automatically handled: - -```kotlin -// Transaction with sponsored gas -val sponsoredTx = JsonObject().apply { - addProperty("to", recipientAddress) - addProperty("value", "0x1000") - addProperty("data", "0x") -} - -// The paymasterAndData field is automatically populated -val result = web3Auth.request( - "eth_sendTransaction", - requestParams = JsonArray().apply { add(sponsoredTx) } -) - -// User pays nothing for gas! -``` - -### ERC-20 Gas Payments - -Allow users to pay gas fees with ERC-20 tokens: - -```kotlin -// Configure ERC-20 paymaster in dashboard first -// Then transactions automatically use ERC-20 for gas - -val transaction = JsonObject().apply { - addProperty("to", recipientAddress) - addProperty("value", amount) - addProperty("data", "0x") - // Specify the token for gas payment (optional) - addProperty("paymasterData", JsonObject().apply { - addProperty("token", "USDC") - }) -} - -val result = web3Auth.request( - "eth_sendTransaction", - requestParams = JsonArray().apply { add(transaction) } -) -``` - -## Wallet UI Integration - -The `showWalletUI()` method automatically supports smart account features: - -```kotlin -// Launch wallet UI with smart account support -val walletResult = web3Auth.showWalletUI() - -walletResult.whenComplete { _, error -> - if (error == null) { - // Wallet UI will show: - // - Smart account address - // - Batch transaction options - // - Gas sponsorship status - // - ERC-20 gas payment options - } -} -``` - -## Best Practices - -### 1. Address Management - -Always distinguish between EOA and smart account addresses: - -```kotlin -class WalletManager(private val web3Auth: Web3Auth) { - - fun getActiveAddress(): String { - val userInfo = web3Auth.getUserInfo() - return if (userInfo?.isSmartAccountEnabled == true) { - userInfo.smartAccountAddress ?: getEOAAddress() - } else { - getEOAAddress() - } - } - - private fun getEOAAddress(): String { - return web3Auth.getAddress() - } -} -``` - -### 2. Error Handling - -Handle smart account-specific errors: - -```kotlin -web3Auth.request(method, params).whenComplete { result, error -> - when { - error?.message?.contains("insufficient paymaster funds") == true -> { - // Handle paymaster balance issues - showError("Transaction sponsorship unavailable") - } - error?.message?.contains("user operation") == true -> { - // Handle user operation errors - showError("Smart account operation failed") - } - error != null -> { - // Generic error handling - showError(error.message ?: "Transaction failed") - } - else -> { - // Success - handleSuccess(result) - } - } -} -``` - -### 3. Feature Detection - -Check for smart account features before using them: - -```kotlin -class SmartAccountFeatures(private val web3Auth: Web3Auth) { - - fun isAvailable(): Boolean { - val projectConfig = web3Auth.getProjectConfiguration() - return projectConfig?.smartAccounts?.enabled == true - } - - fun isGasSponsorshipEnabled(): Boolean { - val projectConfig = web3Auth.getProjectConfiguration() - return projectConfig?.smartAccounts?.sponsorshipEnabled == true - } - - fun supportsBatchTransactions(): Boolean { - return isAvailable() // All smart accounts support batching - } -} -``` - -## Migration from EOA - -If you're migrating from EOA to smart accounts: - -```kotlin -// Before (EOA) -val address = web3Auth.getAddress() -val privateKey = web3Auth.getPrivateKey() - -// After (Smart Account) -val userInfo = web3Auth.getUserInfo() -val address = userInfo?.smartAccountAddress ?: web3Auth.getAddress() -// Private key is managed by the smart account contract -``` - -## Troubleshooting - -### Common Issues - -1. **Smart account not created**: Ensure smart accounts are enabled in dashboard -2. **User operation failing**: Check bundler and paymaster configuration -3. **Gas sponsorship not working**: Verify paymaster balance and limits -4. **Wrong address used**: Always use `smartAccountAddress` for transactions - -### Debug Mode - -Enable verbose logging for smart account operations: - -```kotlin -val web3AuthOptions = Web3AuthOptions( - // ... other options - enableLogging = true -) -``` - -## Learn More - -- [Account Abstraction Overview](/embedded-wallets/features/smart-accounts) -- [ERC-4337 Specification](https://eips.ethereum.org/EIPS/eip-4337) -- [Web3Auth Dashboard Guide](https://dashboard.web3auth.io) From 0edd88ba9273c99ba36921547406868cf9961ef3 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:27:26 +0530 Subject: [PATCH 06/12] temp --- .../_evm-installation.mdx | 2 +- embedded-wallets/sdk/android/README.mdx | 18 +-- .../sdk/android/advanced/README.mdx | 114 +++++++++++++--- .../advanced/custom-authentication.mdx | 40 +++--- embedded-wallets/sdk/android/advanced/mfa.mdx | 4 +- .../sdk/android/advanced/smart-accounts.mdx | 125 ++++++++++++++++++ .../sdk/android/advanced/whitelabel.mdx | 32 ++--- .../migration-guides/android-v9-to-v10.mdx | 4 +- embedded-wallets/sdk/android/usage/README.mdx | 23 +++- .../sdk/android/usage/connect-to.mdx | 54 +++++--- .../sdk/android/usage/enable-mfa.mdx | 19 ++- .../android/usage/get-ed25519-private-key.mdx | 19 ++- .../sdk/android/usage/get-private-key.mdx | 31 ++++- .../sdk/android/usage/get-user-info.mdx | 59 ++++++--- .../sdk/android/usage/manage-mfa.mdx | 11 +- 15 files changed, 421 insertions(+), 134 deletions(-) create mode 100644 embedded-wallets/sdk/android/advanced/smart-accounts.mdx diff --git a/embedded-wallets/connect-blockchain/_android-connect-blockchain/_evm-installation.mdx b/embedded-wallets/connect-blockchain/_android-connect-blockchain/_evm-installation.mdx index 1f8ef318054..fa2a5b5c31e 100644 --- a/embedded-wallets/connect-blockchain/_android-connect-blockchain/_evm-installation.mdx +++ b/embedded-wallets/connect-blockchain/_android-connect-blockchain/_evm-installation.mdx @@ -3,6 +3,6 @@ To interact with Ethereum in Android, you can use any [`EIP1193`](https://eips.e ```groovy dependencies { // ... - implementation 'org.web3j:core:4.8.7-android' + implementation 'org.web3j:core:4.8.8-android' } ``` diff --git a/embedded-wallets/sdk/android/README.mdx b/embedded-wallets/sdk/android/README.mdx index 1e87dc1ab44..d913edcd42b 100644 --- a/embedded-wallets/sdk/android/README.mdx +++ b/embedded-wallets/sdk/android/README.mdx @@ -13,7 +13,7 @@ MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play) provides authent ## Requirements -- Android API version `24` or newer +- Android API version `26` or newer - Android Compile and Target SDK: `34` - Basic knowledge of Java or Kotlin development @@ -159,11 +159,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork // focus-start var web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-end @@ -240,11 +240,11 @@ See the [advanced configuration sections](./advanced/) to learn more about each ```kotlin val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_CLIENT_ID", web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET redirectUrl = "YOUR_APP_SCHEME://auth" - ) + ), + this ) ``` @@ -255,10 +255,9 @@ val web3Auth = Web3Auth( ```kotlin val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_CLIENT_ID", web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET - redirectUrl = "YOUR_APP_SCHEME://auth" + redirectUrl = "YOUR_APP_SCHEME://auth", authConnectionConfig = listOf(AuthConnectionConfig( authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard authConnection = AuthConnection.GOOGLE, @@ -272,7 +271,8 @@ val web3Auth = Web3Auth( passkeysFactor = MfaSetting(true, 5, true), authenticatorFactor = MfaSetting(true, 6, true), ) - ) + ), + this ) ``` diff --git a/embedded-wallets/sdk/android/advanced/README.mdx b/embedded-wallets/sdk/android/advanced/README.mdx index e41f6cfd716..3b3fee37364 100644 --- a/embedded-wallets/sdk/android/advanced/README.mdx +++ b/embedded-wallets/sdk/android/advanced/README.mdx @@ -21,11 +21,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork // focus-start var web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-end @@ -53,10 +53,10 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. | `clientId` | Your Embedded Wallets Client ID. You can get it from Embedded Wallets [dashboard](https://developer.metamask.io/) under project details. It's a mandatory field of type `String` | | `web3AuthNetwork` | Defines the Embedded Wallets Network. It's a mandatory field of type `Web3AuthNetwork`. | | `redirectUrl` | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type `String`. | -| `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is 86400 seconds which is 1 day. `sessionTime` can be max 30 days. | +| `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is `86400 * 30` (30 days). `sessionTime` can be max 30 days. | | `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for wallet pregeneration and SFA mode. | -| `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. | -| `defaultChainId?` | Default chain ID to use. It's an optional field with default value as `null`. The first chain in the list will be used if not provided. | +| `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. See [Chains configuration](#chains-configuration) below. | +| `defaultChainId?` | Default chain ID to use. It's an optional field with a default value of `"0x1"` (Ethereum mainnet). The first chain from the project config will be used if the project has chains configured. | | `enableLogging?` | Setting to true will enable logs. It's an optional field with default value as `false`. | @@ -76,21 +76,19 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. ```kotlin data class Web3AuthOptions( - var context: Context, val clientId: String, - val web3AuthNetwork: Web3AuthNetwork, - var authBuildEnv: BuildEnv? = BuildEnv.PRODUCTION, var redirectUrl: String, - var sdkUrl: String = getSdkUrl(authBuildEnv), - val whiteLabel: WhiteLabelData? = null, - val authConnectionConfig: List? = null, + @SerializedName("network") val web3AuthNetwork: Web3AuthNetwork, + @SerializedName("buildEnv") var authBuildEnv: BuildEnv = BuildEnv.PRODUCTION, + var whiteLabel: WhiteLabelData? = null, + var authConnectionConfig: List? = emptyList(), val useSFAKey: Boolean? = false, - val chains: Chains? = null, - val mfaSettings: MfaSettings? = null, - val sessionTime: Int = 86400, + var chains: Chains? = null, + var mfaSettings: MfaSettings? = null, + val sessionTime: Int = 30 * 86400, val walletServicesConfig: WalletServicesConfig? = null, - val defaultChainId: String? = null, - val enableLogging: Boolean? = false + var defaultChainId: String? = "0x1", + var enableLogging: Boolean = false ) ``` @@ -106,17 +104,72 @@ Control how long users stay authenticated and how sessions persist. The session - `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to log in again. - Minimum: 1 second (`1`). - Maximum: 30 days (`86400 * 30`). - - Default: 7 days (`86400 * 7`). + - Default: 30 days (`86400 * 30`). ```kotlin var web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, sessionTime = 86400 * 7, // 7 days (in seconds) redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this +) +``` + +## Chains Configuration + +The `chains` parameter lets you specify a custom blockchain network for the SDK. When set, this chain is used by wallet services (`showWalletUI`, `request`) in addition to any chains configured in the project dashboard. + +### `Chains` Fields + +| Field | Type | Required | Description | +| ------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------- | +| `chainId` | `String` | Yes | Chain ID in hex format (e.g. `"0x1"` for Ethereum mainnet, `"0x89"` for Polygon). | +| `rpcTarget` | `String` | Yes | RPC endpoint URL for the chain. | +| `chainNamespace` | `ChainNamespace` | No | Namespace of the chain. Accepts `ChainNamespace.EIP155`, `SOLANA`, or `OTHER`. Default is `EIP155`. | +| `decimals` | `Int?` | No | Number of decimals for the native token. Default is `18`. | +| `blockExplorerUrl` | `String?` | No | URL of the block explorer for this chain. | +| `displayName` | `String?` | No | Human-readable name for the chain. | +| `logo` | `String?` | No | URL of the chain's logo image. | +| `ticker` | `String?` | No | Ticker symbol for the native token (e.g. `"ETH"`). | +| `tickerName` | `String?` | No | Full name of the native token (e.g. `"Ethereum"`). | + +### Interface + +```kotlin +data class Chains( + val chainNamespace: ChainNamespace = ChainNamespace.EIP155, + val decimals: Int? = 18, + val blockExplorerUrl: String? = null, + val chainId: String, + val displayName: String? = null, + val logo: String? = null, + val rpcTarget: String, + val ticker: String? = null, + val tickerName: String? = null, +) +``` + +### Example + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + clientId = "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "YOUR_APP_SCHEME://auth", + chains = Chains( + chainId = "0x89", + rpcTarget = "https://rpc.ankr.com/polygon", + displayName = "Polygon Mainnet", + ticker = "MATIC", + tickerName = "Matic", + blockExplorerUrl = "https://polygonscan.com" + ) + ), + this ) ``` @@ -136,3 +189,26 @@ Add additional security layers to protect user accounts with two-factor authenti - `mfaSettings` - Configure MFA settings for different authentication flows - `mfaLevel` - Control when users are prompted to set up MFA + +## Wallet Services Configuration + +The `walletServicesConfig` parameter in `Web3AuthOptions` allows you to customize the behavior of the wallet UI (`showWalletUI`) and request signing (`request`). For full configuration options, see the [Smart Accounts](./smart-accounts) section. + +| Parameter | Description | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy` enum. Default is `ConfirmationStrategy.DEFAULT`. | +| `whiteLabel?` | Whitelabel settings specific to the wallet services UI. When set, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as value. | + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + clientId = "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "YOUR_APP_SCHEME://auth", + walletServicesConfig = WalletServicesConfig( + confirmationStrategy = ConfirmationStrategy.MODAL + ) + ), + this +) +``` diff --git a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx index 0ef478f66a8..3759639e4fd 100644 --- a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx @@ -153,7 +153,6 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", @@ -164,7 +163,8 @@ val web3Auth = Web3Auth( clientId = getString(R.string.google_client_id) // Google's client id )) // focus-end - ) + ), + this ) // focus-start @@ -185,7 +185,6 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", @@ -198,7 +197,8 @@ val web3Auth = Web3Auth( ) ) // focus-end - ) + ), + this ) // focus-start @@ -220,7 +220,6 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", @@ -228,10 +227,11 @@ val web3Auth = Web3Auth( authConnectionConfig = listOf(AuthConnectionConfig( authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard authConnection = AuthConnection.CUSTOM, - clientId = getString (R.string.auth0_project_id) // Auth0's client id + clientId = getString(R.string.auth0_project_id) // Auth0's client id )) // focus-end - ) + ), + this ) // focus-start @@ -252,7 +252,6 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", @@ -264,7 +263,8 @@ val web3Auth = Web3Auth( ) ) // focus-end - ) + ), + this ) // focus-start @@ -383,7 +383,6 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", @@ -391,10 +390,11 @@ val web3Auth = Web3Auth( authConnectionConfig = listOf(AuthConnectionConfig( authConnectionId = "auth-connection-id", // Get it from MetaMask Developer Dashboard authConnection = AuthConnection.CUSTOM, - clientId = getString (R.string.auth0_project_id) // Auth0's client id + clientId = getString(R.string.auth0_project_id) // Auth0's client id )) // focus-end - ) + ), + this ) val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( @@ -423,7 +423,6 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", @@ -433,7 +432,8 @@ val web3Auth = Web3Auth( authConnection = AuthConnection.CUSTOM, )) // focus-end - ) + ), + this ) val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( @@ -461,11 +461,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( @@ -496,11 +496,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -528,7 +528,6 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", @@ -550,7 +549,8 @@ val web3Auth = Web3Auth( ) ) // focus-end - ) + ), + this ) // focus-start diff --git a/embedded-wallets/sdk/android/advanced/mfa.mdx b/embedded-wallets/sdk/android/advanced/mfa.mdx index 30b309ccbda..ba4a7291363 100644 --- a/embedded-wallets/sdk/android/advanced/mfa.mdx +++ b/embedded-wallets/sdk/android/advanced/mfa.mdx @@ -241,7 +241,6 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", @@ -255,7 +254,8 @@ val web3Auth = Web3Auth( authenticatorFactor = MfaSetting(true, 6, true), ) // focus-end - ) + ), + this ) val loginResponse = web3Auth.connectTo( diff --git a/embedded-wallets/sdk/android/advanced/smart-accounts.mdx b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx new file mode 100644 index 00000000000..f348dcf73af --- /dev/null +++ b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx @@ -0,0 +1,125 @@ +--- +title: Smart Accounts +sidebar_label: Smart Accounts +description: 'Web3Auth Android SDK - Smart Accounts (Account Abstraction) | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +Smart Accounts enable Account Abstraction (ERC-4337) for your users, allowing features like gas sponsorship (paymasters), batched transactions, and session keys. Smart account support is configured in your Web3Auth Dashboard and is automatically applied when you use `showWalletUI` or `request`. + +:::info + +Smart Account configuration is managed at the project level in the [Web3Auth Dashboard](https://dashboard.web3auth.io). The SDK automatically retrieves the configuration during `initialize()`. + +::: + +## Wallet Services Configuration + +You can customize the wallet UI behavior for smart account flows using `walletServicesConfig` in `Web3AuthOptions`. + +### `WalletServicesConfig` + +| Parameter | Description | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `confirmationStrategy?` | Controls how transaction confirmations are presented. Accepts `ConfirmationStrategy` as a value. Default is `ConfirmationStrategy.DEFAULT`. | +| `whiteLabel?` | Optional whitelabel configuration to apply specifically to the wallet services UI. Accepts `WhiteLabelData` as a value. When set, it is merged with the project-level whitelabel config. | + +### `ConfirmationStrategy` + +| Value | Description | +| -------------- | ------------------------------------------------------------------ | +| `POPUP` | Shows transaction confirmations in a popup window. | +| `MODAL` | Shows transaction confirmations in a modal overlay. | +| `AUTO_APPROVE` | Automatically approves transactions without showing a confirmation. | +| `DEFAULT` | Uses the platform default confirmation behavior. | + +### Interface + +```kotlin +data class WalletServicesConfig( + val confirmationStrategy: ConfirmationStrategy? = ConfirmationStrategy.DEFAULT, + var whiteLabel: WhiteLabelData? = null +) + +enum class ConfirmationStrategy { + @SerializedName("popup") + POPUP, + @SerializedName("modal") + MODAL, + @SerializedName("auto-approve") + AUTO_APPROVE, + @SerializedName("default") + DEFAULT +} +``` + +### Usage + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + clientId = "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "YOUR_APP_SCHEME://auth", + walletServicesConfig = WalletServicesConfig( + confirmationStrategy = ConfirmationStrategy.MODAL + ) + ), + this +) +``` + +## Using Smart Account Operations + +Once smart accounts are enabled in your dashboard, you can use the `request` method to send user operations. See the [request](../usage/request) page for full details and examples. + +### Supported Smart Account Methods + +| Method | Description | +| ------------------------------ | --------------------------------------------------- | +| `eth_sendUserOperation` | Send a user operation for account abstraction. | +| `eth_estimateUserOperationGas` | Estimate gas for a user operation. | +| `wallet_showUserOperation` | Display user operation details in the wallet UI. | + +### Example + +```kotlin +val userOp = JsonObject().apply { + addProperty("sender", smartAccountAddress) + addProperty("nonce", "0x0") + addProperty("initCode", "0x") + addProperty("callData", encodedCallData) + addProperty("callGasLimit", "0x5208") + addProperty("verificationGasLimit", "0x5208") + addProperty("preVerificationGas", "0x5208") + addProperty("maxFeePerGas", "0x3b9aca00") + addProperty("maxPriorityFeePerGas", "0x3b9aca00") + addProperty("paymasterAndData", "0x") + addProperty("signature", "0x") +} + +val params = JsonArray().apply { + add(userOp) +} + +val userOpCompletableFuture = web3Auth.request( + "eth_sendUserOperation", + requestParams = params +) + +userOpCompletableFuture.whenComplete { result, error -> + if (error == null) { + Log.d("UserOp Hash", result.toString()) + } else { + Log.d("UserOp Error", error.message ?: "Failed to send user operation") + } +} +``` + +:::tip + +The bundler and paymaster configuration is automatically handled by the Web3Auth Dashboard. You do not need to provide these URLs manually in your Android code. + +::: diff --git a/embedded-wallets/sdk/android/advanced/whitelabel.mdx b/embedded-wallets/sdk/android/advanced/whitelabel.mdx index 6183d58f796..cf691b544f3 100644 --- a/embedded-wallets/sdk/android/advanced/whitelabel.mdx +++ b/embedded-wallets/sdk/android/advanced/whitelabel.mdx @@ -53,14 +53,14 @@ For defining custom UI, branding, and translations for your brand during Embedde ```kotlin data class WhiteLabelData( - private var appName: String? = null, - private var appUrl: String? = null, - private var logoLight: String? = null, - private var logoDark: String? = null, - private var defaultLanguage: Language? = Language.EN, - private var mode: ThemeModes? = null, - private var useLogoLoader: Boolean? = false, - private var theme: HashMap? = null + var appName: String? = null, + var appUrl: String? = null, + var logoLight: String? = null, + var logoDark: String? = null, + var defaultLanguage: Language? = Language.EN, + var mode: ThemeModes? = null, + var useLogoLoader: Boolean? = false, + var theme: HashMap? = null ) ``` @@ -72,27 +72,27 @@ data class WhiteLabelData( ### Example ```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( - context = this, - clientId = getString (R.string.web3auth_project_id), +web3Auth = Web3Auth( + Web3AuthOptions( + clientId = getString(R.string.web3auth_project_id), web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // Optional whitelabel object // focus-start - whiteLabel = WhiteLabelData ( + whiteLabel = WhiteLabelData( appName = "Web3Auth Sample App", appUrl = null, logoLight = null, logoDark = null, - defaultLanguage = Language.EN, // EN, DE, JA, KO, ZH, ES, FR, PT, NL + defaultLanguage = Language.EN, // EN, DE, JA, KO, ZH, ES, FR, PT, NL, TR mode = ThemeModes.DARK, // LIGHT, DARK, AUTO useLogoLoader = true, - theme = hashMapOf ( + theme = hashMapOf( "primary" to "#229954" ) ) // focus-end - ) + ), + this ) ``` diff --git a/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx index b8ea6c0af3c..65055641b0e 100644 --- a/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx +++ b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx @@ -124,7 +124,6 @@ val web3Auth = Web3Auth( ```kotlin val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_CLIENT_ID", web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "your-app://auth", // Now a String instead of Uri @@ -134,7 +133,8 @@ val web3Auth = Web3Auth( clientId = "google-client-id" )), authBuildEnv = BuildEnv.PRODUCTION // Renamed from buildEnv - ) + ), + this ) ``` diff --git a/embedded-wallets/sdk/android/usage/README.mdx b/embedded-wallets/sdk/android/usage/README.mdx index cac1926921d..ffb6a0b305f 100644 --- a/embedded-wallets/sdk/android/usage/README.mdx +++ b/embedded-wallets/sdk/android/usage/README.mdx @@ -23,9 +23,10 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### User management functions -| Function Name | Description | -| -------------------------------------- | ----------------------------------------------- | -| [`getUserInfo()`](./get-user-info.mdx) | Retrieves the authenticated user's information. | +| Function Name | Description | +| -------------------------------------- | --------------------------------------------------------------------------------------------- | +| [`getUserInfo()`](./get-user-info.mdx) | Retrieves the authenticated user's information as a `UserInfo` object. | +| `getWeb3AuthResponse()` | Retrieves the full `Web3AuthResponse` from the current session, including keys and user info. | ### Private key functions @@ -47,3 +48,19 @@ For detailed usage, configuration options, and code examples, refer to the dedic | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | [`showWalletUI()`](./launch-wallet-services.mdx) | Launches the templated wallet UI in WebView with automatic chain configuration from dashboard. | | [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions with simplified parameters. | + +## `getWeb3AuthResponse()` + +The `getWeb3AuthResponse()` method returns the full `Web3AuthResponse` from the current session. This gives you direct access to all session data including keys, user info, signatures, and factor keys. + +```kotlin +val response = web3Auth.getWeb3AuthResponse() +``` + +:::warning + +`getWeb3AuthResponse()` throws an `Error` with code `NOUSERFOUND` when no active session exists. Check for an active session using `getPrivateKey().isNotEmpty()` before calling this method. + +::: + +For most use cases, prefer the typed accessors (`getPrivateKey()`, `getEd25519PrivateKey()`, `getUserInfo()`) which provide a more ergonomic API with clear error messages. diff --git a/embedded-wallets/sdk/android/usage/connect-to.mdx b/embedded-wallets/sdk/android/usage/connect-to.mdx index 14bcebc5130..c180d6335f7 100644 --- a/embedded-wallets/sdk/android/usage/connect-to.mdx +++ b/embedded-wallets/sdk/android/usage/connect-to.mdx @@ -99,6 +99,24 @@ enum class AuthConnection { +## Return Value: `Web3AuthResponse` + +`connectTo` returns a `CompletableFuture`. The response contains: + +| Field | Type | Description | +| ---------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------- | +| `privateKey` | `String?` | secp256k1 private key (EVM). Use `getPrivateKey()` for a safe accessor. | +| `ed25519PrivKey` | `String?` | Ed25519 private key (Solana, Near, etc.). Use `getEd25519PrivateKey()` for a safe accessor. | +| `userInfo` | `UserInfo?` | User profile information. See [getUserInfo](./getUserInfo) for field details. | +| `coreKitKey` | `String?` | SFA key returned when `useSFAKey = true`. | +| `coreKitEd25519PrivKey`| `String?` | SFA Ed25519 key returned when `useSFAKey = true`. | +| `factorKey` | `String?` | Factor key for MFA flows. | +| `sessionId` | `String?` | Current session identifier. | +| `signatures` | `List?` | Session token signatures for advanced use cases. | +| `error` | `String?` | Non-null when the session returned an error. | + +Prefer the typed accessors `getPrivateKey()` and `getEd25519PrivateKey()` over reading `privateKey` directly — they correctly handle the `useSFAKey` flag and throw `IllegalStateException` instead of returning null when no key is available. + ## Usage ```kotlin @@ -108,11 +126,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -147,11 +165,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -172,11 +190,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -197,11 +215,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -222,11 +240,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -247,11 +265,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -275,11 +293,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -303,11 +321,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start @@ -328,11 +346,11 @@ import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", - ) + ), + this ) // focus-start diff --git a/embedded-wallets/sdk/android/usage/enable-mfa.mdx b/embedded-wallets/sdk/android/usage/enable-mfa.mdx index 0ce1af8dc79..665e2b2ba70 100644 --- a/embedded-wallets/sdk/android/usage/enable-mfa.mdx +++ b/embedded-wallets/sdk/android/usage/enable-mfa.mdx @@ -59,23 +59,30 @@ class MainActivity : AppCompatActivity() { +:::warning + +`enableMFA` does **not** accept an `idToken` in `LoginParams`. Passing `idToken` will cause the SDK to throw an `ENABLE_MFA_NOT_ALLOWED` error. For custom JWT verifiers, pass an empty `LoginParams` with the `authConnection` only — the SDK automatically uses the session's auth connection to re-authenticate. + +::: + ```kotlin title="Usage" import android.widget.Button import com.web3auth.core.Web3Auth import android.os.Bundle -class MainActivity : AppCompatActivity() { private lateinit var web3Auth: Web3Auth +class MainActivity : AppCompatActivity() { + private lateinit var web3Auth: Web3Auth - private fun enableMFA() { + private fun enableMFA() { val loginParams = LoginParams( - Provider.JWT, - extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token") + AuthConnection.CUSTOM, + authConnectionId = "your_auth_connection_id" ) // focus-next-line val completableFuture = web3Auth.enableMFA(loginParams) - completableFuture.whenComplete{_, error -> + completableFuture.whenComplete { _, error -> if (error == null) { Log.d("MainActivity_Web3Auth", "Launched successfully") // Add your logic @@ -94,9 +101,7 @@ class MainActivity : AppCompatActivity() { private lateinit var web3Auth: Web3Au ... } ... - } - ``` diff --git a/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx b/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx index f5d50c24714..28ac6f67539 100644 --- a/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx +++ b/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx @@ -6,14 +6,21 @@ description: 'Web3Auth Android SDK - getEd25519PrivateKey Function | Embedded Wa To retrieve the Ed25519 private key of the user, use `getEd25519PrivateKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. -## Usage - -```kotlin -val privateKey = web3Auth.getEd25519PrivateKey() -``` - :::note Web3Auth supports two widely used cryptographic curves, Secp256k1 and Ed25519, making it chain-agnostic and compatible with multiple blockchain networks. [Learn more about how to connect different blockchains](/embedded-wallets/connect-blockchain). ::: + +:::info Session behavior + +- When no active session exists, `getEd25519PrivateKey()` throws `IllegalStateException`. Check for an active session first using `getPrivateKey().isNotEmpty()`. +- If `useSFAKey = true` in `Web3AuthOptions`, this method returns the SFA Ed25519 core kit key instead of the standard Ed25519 key. + +::: + +## Usage + +```kotlin +val ed25519PrivateKey = web3Auth.getEd25519PrivateKey() +``` diff --git a/embedded-wallets/sdk/android/usage/get-private-key.mdx b/embedded-wallets/sdk/android/usage/get-private-key.mdx index e440a294970..9dc24aabe11 100644 --- a/embedded-wallets/sdk/android/usage/get-private-key.mdx +++ b/embedded-wallets/sdk/android/usage/get-private-key.mdx @@ -6,14 +6,33 @@ description: 'Web3Auth Android SDK - getPrivateKey Function | Embedded Wallets' To retrieve the secp256k1 private key of the user, use `getPrivateKey` method. The method returns an EVM compatible private key which can be used to sign transactions on EVM compatible chains. -## Usage - -```kotlin -val privateKey = web3Auth.getPrivateKey() -``` - :::note Web3Auth supports two widely used cryptographic curves, Secp256k1 and Ed25519, making it chain-agnostic and compatible with multiple blockchain networks. [Learn more about how to connect different blockchains](/embedded-wallets/connect-blockchain). ::: + +:::info Session behavior + +- When `initialize()` completes and no active session exists, `getPrivateKey()` returns an **empty string** (`""`). Use this to check for an active session. +- After a successful `connectTo()`, `getPrivateKey()` returns the private key. +- If `useSFAKey = true` in `Web3AuthOptions`, this method returns the SFA core kit key instead of the standard secp256k1 key. +- `getPrivateKey()` throws `IllegalStateException` if the internal response is in an unexpected null state. + +::: + +## Usage + +```kotlin +val initializeCF = web3Auth.initialize() +initializeCF.whenComplete { _, error -> + if (error == null) { + val privateKey = web3Auth.getPrivateKey() + if (privateKey.isNotEmpty()) { + // Active session found, user is already logged in + } else { + // No active session, prompt user to log in + } + } +} +``` diff --git a/embedded-wallets/sdk/android/usage/get-user-info.mdx b/embedded-wallets/sdk/android/usage/get-user-info.mdx index 9b826cedccf..5d130ab330c 100644 --- a/embedded-wallets/sdk/android/usage/get-user-info.mdx +++ b/embedded-wallets/sdk/android/usage/get-user-info.mdx @@ -6,29 +6,50 @@ description: 'Web3Auth Android SDK - getUserInfo Function | Embedded Wallets' You can use the `getUserInfo` method to retrieve various details about the user, such as their login type, whether multi-factor authentication (MFA) is enabled, profile image, name, and other relevant information. +:::note + +`getUserInfo()` throws an `Error` with code `NOUSERFOUND` when no active session exists. Always call it after `initialize()` completes and only when `getPrivateKey()` returns a non-empty string. + +::: + ## Usage ```kotlin val userInfo = web3Auth.getUserInfo() ``` -## UserInfo response - -```json -{ - "userInfo": { - "email": "w3a-heroes@web3auth.com", - "name": "Web3Auth Heroes", - "profileImage": "https://lh3.googleusercontent.com/a/Ajjjsdsmdjmnm...", - "verifier": "torus", - "verifierId": "w3a-heroes@web3auth.com", - "typeOfLogin": "google", - "aggregateVerifier": "w3a-google-sapphire", - "dappShare": "", // 24 words of seed phrase will be sent only incase of custom verifiers - "idToken": "", - "oAuthIdToken": "", // will be sent only incase of custom verifiers - "oAuthAccessToken": "", // will be sent only incase of custom verifiers - "isMfaEnabled": false // Returns whether the user has enabled MFA or not - } -} +## `UserInfo` Fields + +| Field | Type | Description | +| ------------------------- | ---------- | ----------------------------------------------------------------------------------------------- | +| `email` | `String` | Email address of the user. Empty string if not available. | +| `name` | `String` | Display name of the user. Empty string if not available. | +| `profileImage` | `String` | URL of the user's profile image. Empty string if not available. | +| `authConnectionId` | `String` | The auth connection ID (verifier name) used to log in. | +| `groupedAuthConnectionId` | `String` | The grouped auth connection ID if aggregate verifiers are used. Empty string if not applicable. | +| `userId` | `String` | The user's unique ID within the auth connection (e.g. email for email-based, sub for OAuth). | +| `authConnection` | `String` | The auth connection type used (e.g. `"google"`, `"custom"`). | +| `dappShare` | `String` | DApp share for custom verifiers. Empty string for default verifiers. | +| `idToken` | `String` | JWT issued by Web3Auth after authentication. | +| `oAuthIdToken` | `String` | JWT issued by the OAuth provider. Only present for custom verifiers. | +| `oAuthAccessToken` | `String` | Access token issued by the OAuth provider. Only present for custom verifiers. | +| `isMfaEnabled` | `Boolean?` | Whether the user has MFA enabled. `null` if the information is not available in the session. | + +### Interface + +```kotlin +data class UserInfo( + var email: String = "", + var name: String = "", + var profileImage: String = "", + var groupedAuthConnectionId: String = "", + var authConnectionId: String = "", + var userId: String = "", + var authConnection: String = "", + var dappShare: String = "", + var idToken: String = "", + var oAuthIdToken: String = "", + var oAuthAccessToken: String = "", + var isMfaEnabled: Boolean? = null +) ``` diff --git a/embedded-wallets/sdk/android/usage/manage-mfa.mdx b/embedded-wallets/sdk/android/usage/manage-mfa.mdx index a452f1cb2cd..470f0003211 100644 --- a/embedded-wallets/sdk/android/usage/manage-mfa.mdx +++ b/embedded-wallets/sdk/android/usage/manage-mfa.mdx @@ -39,20 +39,19 @@ manageMFACF.whenComplete{_, error -> ```kotlin title="Usage" val loginParams = LoginParams( - Provider.JWT, - extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token") + AuthConnection.CUSTOM, + authConnectionId = "your_auth_connection_id" ) val manageMFACF = web3Auth.manageMFA(loginParams) -manageMFACF.whenComplete{_, error -> +manageMFACF.whenComplete { _, error -> if (error == null) { - // Handle success + // Handle success } else { - // Handle error + // Handle error } } - ``` From 684067ac521164927ddee1e260b6c77ca09b8ddd Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Wed, 15 Apr 2026 21:10:03 +0530 Subject: [PATCH 07/12] Update android-wallet.mdx --- src/pages/tutorials/android-wallet.mdx | 52 +++++++++++++------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/src/pages/tutorials/android-wallet.mdx b/src/pages/tutorials/android-wallet.mdx index cc5c7ef03af..9fafeb5f867 100644 --- a/src/pages/tutorials/android-wallet.mdx +++ b/src/pages/tutorials/android-wallet.mdx @@ -90,8 +90,8 @@ class Web3AuthHelperImpl( ): Web3AuthHelper { // Performs the login to authenticate the user with Web3Auth network. - override suspend fun login(loginParams: LoginParams): CompletableFuture { - return web3Auth.login(loginParams) + override suspend fun connectTo(loginParams: LoginParams): CompletableFuture { + return web3Auth.connectTo(loginParams) } // Logout of the current active session. @@ -101,7 +101,7 @@ class Web3AuthHelperImpl( // Returns the Ethereum compatible private key. override fun getPrivateKey(): String { - return web3Auth.getPrivkey() + return web3Auth.getPrivateKey() } // Returns the user information such as name, email, profile image, and etc. @@ -123,7 +123,7 @@ class Web3AuthHelperImpl( } override suspend fun isUserAuthenticated(): Boolean { - return web3Auth.getPrivkey().isNotEmpty() + return web3Auth.getPrivateKey().isNotEmpty() } } ``` @@ -148,10 +148,10 @@ private fun getWeb3AuthHelper(context: Context): Web3AuthHelper { val web3Auth = Web3Auth( Web3AuthOptions( clientId = "WEB3AUTH_CLIENT_ID", - context = context, - network = Network.SAPPHIRE_MAINNET, - redirectUrl = Uri.parse("w3a://com.example.android_playground/auth") - ) + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "w3a://com.example.android_playground/auth" + ), + context ) // focus-end @@ -167,7 +167,7 @@ Learn more about [Embedded Wallets initialization](/embedded-wallets/sdk/android ### 2.3 Session management -To check whether the user is authenticated, you can use the `getPrivateKey` or `getEd25519PrivKey` method. +To check whether the user is authenticated, you can use the `getPrivateKey` or `getEd25519PrivateKey` method. For an authenticated user, the result would be a non-empty string. You can navigate to different views based on the result. If the user is already authenticated, we'll generate and prepare the `Credentials`, required to interact with the blockchain. Along with that, we'll retrieve user info, and navigate them @@ -261,14 +261,14 @@ class MainViewModel(private val web3AuthHelper: Web3AuthHelper) : ViewModel() { fun login(email: String) { // focus-start val loginParams = LoginParams( - loginProvider = Provider.EMAIL_PASSWORDLESS, - extraLoginOptions = ExtraLoginOptions(login_hint = email) + AuthConnection.EMAIL_PASSWORDLESS, + loginHint = email ) // focus-end viewModelScope.launch { try { // focus-next-line - web3AuthHelper.login(loginParams = loginParams).await() + web3AuthHelper.connectTo(loginParams = loginParams).await() // Functions from Session Management code snippets prepareCredentials() prepareUserInfo() @@ -499,20 +499,6 @@ class EthereumUseCaseImpl( } ``` -Once we have the created `EthereumUseCaseImpl`, next is to initialize the `EthereumUseCaseImpl` instance in the Kotlin -module. - -```kotlin -val appModule = module { - // Additional code - - // focus-next-line - factory { EthereumUseCaseImpl(Web3j.build(HttpService(chainConfigList.first().rpcTarget))) } - - // Additional code -} -``` - ## Step 4: Set up supported chains Next, we must define the supported chains. To keep things simple, we'll create a new file `ChainConfigList` with an @@ -553,6 +539,20 @@ var chainConfigList = arrayOf( ) ``` +Once we have the created `EthereumUseCaseImpl`, next is to initialize the `EthereumUseCaseImpl` instance in the Kotlin +module. + +```kotlin +val appModule = module { + // Additional code + + // focus-next-line + factory { EthereumUseCaseImpl(Web3j.build(HttpService(chainConfigList.first().rpcTarget))) } + + // Additional code +} +``` + ## Step 5: Wallet implementation Next, we need to integrate and plug the `EthereumUseCase` and supported chains into the wallet. Since we have From c1b52773efe7ae27f149a661e4ce15e5a3c3cfab Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Wed, 15 Apr 2026 21:26:41 +0530 Subject: [PATCH 08/12] Update README.mdx --- embedded-wallets/sdk/android/README.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/embedded-wallets/sdk/android/README.mdx b/embedded-wallets/sdk/android/README.mdx index d913edcd42b..9df67aba3b8 100644 --- a/embedded-wallets/sdk/android/README.mdx +++ b/embedded-wallets/sdk/android/README.mdx @@ -192,7 +192,13 @@ Once the `initialize` method executes successfully, you can use the `getPrivateK :::note -If the API call to fetch the project configuration fails, the method will throw an error. +The `initialize` method may throw an error in the following situations: + +- No active session exists for the user. +- A network error occurs while fetching the project configuration from the dashboard. +- Session validation fails (for example, the stored session token is invalid or expired). + +Wrap the call in a `whenComplete` handler and treat any non-null error as a failed initialization rather than an absent session. ::: From ce5902dcdda5cbfca879a60596784067a18d294c Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo Date: Wed, 15 Apr 2026 11:36:28 -0700 Subject: [PATCH 09/12] fixes --- .../custom-connections/auth0.mdx | 4 +-- .../custom-connections/firebase.mdx | 4 +-- .../sdk/android/advanced/README.mdx | 24 +++++++-------- .../sdk/android/advanced/smart-accounts.mdx | 30 +++++++++---------- .../sdk/android/usage/connect-to.mdx | 22 +++++++------- 5 files changed, 42 insertions(+), 42 deletions(-) diff --git a/embedded-wallets/authentication/custom-connections/auth0.mdx b/embedded-wallets/authentication/custom-connections/auth0.mdx index dee8ff4d046..2b13c4fb63b 100644 --- a/embedded-wallets/authentication/custom-connections/auth0.mdx +++ b/embedded-wallets/authentication/custom-connections/auth0.mdx @@ -145,12 +145,12 @@ web3Auth.setResultUrl(intent?.data) ##### Logging in -Once initialized, you can use the `web3Auth.login(LoginParams("{selectedLoginProvider}"))` function to authenticate the user when they click the login button. +Once initialized, you can use the `web3Auth.connectTo(LoginParams("{selectedLoginProvider}"))` function to authenticate the user when they click the login button. ```kotlin private fun signIn() { val selectedLoginProvider = Provider.JWT // For Auth0, we use JWT - val loginCompletableFuture: CompletableFuture = web3Auth.login( + val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( // focus-start LoginParams( selectedLoginProvider, diff --git a/embedded-wallets/authentication/custom-connections/firebase.mdx b/embedded-wallets/authentication/custom-connections/firebase.mdx index 9220a701484..45d1a02095c 100644 --- a/embedded-wallets/authentication/custom-connections/firebase.mdx +++ b/embedded-wallets/authentication/custom-connections/firebase.mdx @@ -138,7 +138,7 @@ web3Auth.setResultUrl(intent?.data) ##### Logging in -Once initialized, you can use the `web3Auth.login(LoginParams("{selectedLoginProvider}"))` function to authenticate the user when they click the login button. +Once initialized, you can use the `web3Auth.connectTo(LoginParams("{selectedLoginProvider}"))` function to authenticate the user when they click the login button. ```kotlin private fun signIn() { @@ -157,7 +157,7 @@ private fun signIn() { Log.d(TAG, "GetTokenResult result = $idToken") val selectedLoginProvider = Provider.JWT // focus-start - val loginCompletableFuture: CompletableFuture = web3Auth.login( + val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( selectedLoginProvider, extraLoginOptions = ExtraLoginOptions( diff --git a/embedded-wallets/sdk/android/advanced/README.mdx b/embedded-wallets/sdk/android/advanced/README.mdx index 3b3fee37364..65986bccf15 100644 --- a/embedded-wallets/sdk/android/advanced/README.mdx +++ b/embedded-wallets/sdk/android/advanced/README.mdx @@ -124,17 +124,17 @@ The `chains` parameter lets you specify a custom blockchain network for the SDK. ### `Chains` Fields -| Field | Type | Required | Description | -| ------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------- | -| `chainId` | `String` | Yes | Chain ID in hex format (e.g. `"0x1"` for Ethereum mainnet, `"0x89"` for Polygon). | -| `rpcTarget` | `String` | Yes | RPC endpoint URL for the chain. | -| `chainNamespace` | `ChainNamespace` | No | Namespace of the chain. Accepts `ChainNamespace.EIP155`, `SOLANA`, or `OTHER`. Default is `EIP155`. | -| `decimals` | `Int?` | No | Number of decimals for the native token. Default is `18`. | -| `blockExplorerUrl` | `String?` | No | URL of the block explorer for this chain. | -| `displayName` | `String?` | No | Human-readable name for the chain. | -| `logo` | `String?` | No | URL of the chain's logo image. | -| `ticker` | `String?` | No | Ticker symbol for the native token (e.g. `"ETH"`). | -| `tickerName` | `String?` | No | Full name of the native token (e.g. `"Ethereum"`). | +| Field | Type | Required | Description | +| ------------------ | ---------------- | -------- | --------------------------------------------------------------------------------------------------- | +| `chainId` | `String` | Yes | Chain ID in hex format (e.g. `"0x1"` for Ethereum mainnet, `"0x89"` for Polygon). | +| `rpcTarget` | `String` | Yes | RPC endpoint URL for the chain. | +| `chainNamespace` | `ChainNamespace` | No | Namespace of the chain. Accepts `ChainNamespace.EIP155`, `SOLANA`, or `OTHER`. Default is `EIP155`. | +| `decimals` | `Int?` | No | Number of decimals for the native token. Default is `18`. | +| `blockExplorerUrl` | `String?` | No | URL of the block explorer for this chain. | +| `displayName` | `String?` | No | Human-readable name for the chain. | +| `logo` | `String?` | No | URL of the chain's logo image. | +| `ticker` | `String?` | No | Ticker symbol for the native token (e.g. `"ETH"`). | +| `tickerName` | `String?` | No | Full name of the native token (e.g. `"Ethereum"`). | ### Interface @@ -196,7 +196,7 @@ The `walletServicesConfig` parameter in `Web3AuthOptions` allows you to customiz | Parameter | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy` enum. Default is `ConfirmationStrategy.DEFAULT`. | +| `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy` enum. Default is `ConfirmationStrategy.DEFAULT`. | | `whiteLabel?` | Whitelabel settings specific to the wallet services UI. When set, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as value. | ```kotlin diff --git a/embedded-wallets/sdk/android/advanced/smart-accounts.mdx b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx index f348dcf73af..002c7556fbd 100644 --- a/embedded-wallets/sdk/android/advanced/smart-accounts.mdx +++ b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx @@ -21,19 +21,19 @@ You can customize the wallet UI behavior for smart account flows using `walletSe ### `WalletServicesConfig` -| Parameter | Description | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `confirmationStrategy?` | Controls how transaction confirmations are presented. Accepts `ConfirmationStrategy` as a value. Default is `ConfirmationStrategy.DEFAULT`. | -| `whiteLabel?` | Optional whitelabel configuration to apply specifically to the wallet services UI. Accepts `WhiteLabelData` as a value. When set, it is merged with the project-level whitelabel config. | +| Parameter | Description | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `confirmationStrategy?` | Controls how transaction confirmations are presented. Accepts `ConfirmationStrategy` as a value. Default is `ConfirmationStrategy.DEFAULT`. | +| `whiteLabel?` | Optional whitelabel configuration to apply specifically to the wallet services UI. Accepts `WhiteLabelData` as a value. When set, it is merged with the project-level whitelabel config. | ### `ConfirmationStrategy` -| Value | Description | -| -------------- | ------------------------------------------------------------------ | -| `POPUP` | Shows transaction confirmations in a popup window. | -| `MODAL` | Shows transaction confirmations in a modal overlay. | +| Value | Description | +| -------------- | ------------------------------------------------------------------- | +| `POPUP` | Shows transaction confirmations in a popup window. | +| `MODAL` | Shows transaction confirmations in a modal overlay. | | `AUTO_APPROVE` | Automatically approves transactions without showing a confirmation. | -| `DEFAULT` | Uses the platform default confirmation behavior. | +| `DEFAULT` | Uses the platform default confirmation behavior. | ### Interface @@ -73,15 +73,15 @@ val web3Auth = Web3Auth( ## Using Smart Account Operations -Once smart accounts are enabled in your dashboard, you can use the `request` method to send user operations. See the [request](../usage/request) page for full details and examples. +Once smart accounts are enabled in your dashboard, you can use the `request` method to send user operations. See the [request](../../usage/request) page for full details and examples. ### Supported Smart Account Methods -| Method | Description | -| ------------------------------ | --------------------------------------------------- | -| `eth_sendUserOperation` | Send a user operation for account abstraction. | -| `eth_estimateUserOperationGas` | Estimate gas for a user operation. | -| `wallet_showUserOperation` | Display user operation details in the wallet UI. | +| Method | Description | +| ------------------------------ | ------------------------------------------------ | +| `eth_sendUserOperation` | Send a user operation for account abstraction. | +| `eth_estimateUserOperationGas` | Estimate gas for a user operation. | +| `wallet_showUserOperation` | Display user operation details in the wallet UI. | ### Example diff --git a/embedded-wallets/sdk/android/usage/connect-to.mdx b/embedded-wallets/sdk/android/usage/connect-to.mdx index c180d6335f7..69f3f95a6d8 100644 --- a/embedded-wallets/sdk/android/usage/connect-to.mdx +++ b/embedded-wallets/sdk/android/usage/connect-to.mdx @@ -103,17 +103,17 @@ enum class AuthConnection { `connectTo` returns a `CompletableFuture`. The response contains: -| Field | Type | Description | -| ---------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------- | -| `privateKey` | `String?` | secp256k1 private key (EVM). Use `getPrivateKey()` for a safe accessor. | -| `ed25519PrivKey` | `String?` | Ed25519 private key (Solana, Near, etc.). Use `getEd25519PrivateKey()` for a safe accessor. | -| `userInfo` | `UserInfo?` | User profile information. See [getUserInfo](./getUserInfo) for field details. | -| `coreKitKey` | `String?` | SFA key returned when `useSFAKey = true`. | -| `coreKitEd25519PrivKey`| `String?` | SFA Ed25519 key returned when `useSFAKey = true`. | -| `factorKey` | `String?` | Factor key for MFA flows. | -| `sessionId` | `String?` | Current session identifier. | -| `signatures` | `List?` | Session token signatures for advanced use cases. | -| `error` | `String?` | Non-null when the session returned an error. | +| Field | Type | Description | +| ----------------------- | --------------- | ------------------------------------------------------------------------------------------- | +| `privateKey` | `String?` | secp256k1 private key (EVM). Use `getPrivateKey()` for a safe accessor. | +| `ed25519PrivKey` | `String?` | Ed25519 private key (Solana, Near, etc.). Use `getEd25519PrivateKey()` for a safe accessor. | +| `userInfo` | `UserInfo?` | User profile information. See [getUserInfo](../getUserInfo) for field details. | +| `coreKitKey` | `String?` | SFA key returned when `useSFAKey = true`. | +| `coreKitEd25519PrivKey` | `String?` | SFA Ed25519 key returned when `useSFAKey = true`. | +| `factorKey` | `String?` | Factor key for MFA flows. | +| `sessionId` | `String?` | Current session identifier. | +| `signatures` | `List?` | Session token signatures for advanced use cases. | +| `error` | `String?` | Non-null when the session returned an error. | Prefer the typed accessors `getPrivateKey()` and `getEd25519PrivateKey()` over reading `privateKey` directly — they correctly handle the `useSFAKey` flag and throw `IllegalStateException` instead of returning null when no key is available. From 10f3bc415ca7467f962823e056602285b441b681 Mon Sep 17 00:00:00 2001 From: Alexandra Carrillo Date: Wed, 15 Apr 2026 11:48:35 -0700 Subject: [PATCH 10/12] cursor fix --- src/utils/w3a-sdk-map.js | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/utils/w3a-sdk-map.js b/src/utils/w3a-sdk-map.js index 0116fd3f3f8..8e424fb40cd 100644 --- a/src/utils/w3a-sdk-map.js +++ b/src/utils/w3a-sdk-map.js @@ -35,6 +35,9 @@ export function getPnPVersion(platform) { if (platform === reactnative) { return pnpRNVersion } + if (platform === node) { + return pnpNodeVersion + } if (platform === flutter) { return pnpFlutterVersion } From 03ada7b9d8064d9c46bf37fe8c4157d63a752da2 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Thu, 2 Jul 2026 19:57:16 +0400 Subject: [PATCH 11/12] Updates --- .../custom-connections/auth0.mdx | 27 +- .../custom-connections/firebase.mdx | 32 +- .../_evm-get-account.mdx | 4 +- .../connect-blockchain/solana/android.mdx | 16 +- embedded-wallets/migration-guides/README.mdx | 2 +- embedded-wallets/migration-guides/android.mdx | 352 ++++++++++++--- embedded-wallets/sdk/android/README.mdx | 2 +- .../sdk/android/advanced/README.mdx | 20 +- .../migration-guides/android-v9-to-v10.mdx | 414 ------------------ embedded-wallets/sdk/android/usage/README.mdx | 22 +- src/pages/tutorials/android-wallet.mdx | 4 +- src/utils/w3a-sdk-map.js | 2 +- vercel.json | 10 + 13 files changed, 374 insertions(+), 533 deletions(-) delete mode 100644 embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx diff --git a/embedded-wallets/authentication/custom-connections/auth0.mdx b/embedded-wallets/authentication/custom-connections/auth0.mdx index 2b13c4fb63b..64e0333bace 100644 --- a/embedded-wallets/authentication/custom-connections/auth0.mdx +++ b/embedded-wallets/authentication/custom-connections/auth0.mdx @@ -123,20 +123,20 @@ In your activity, create a `Web3Auth` instance with your Web3Auth project's conf ```kotlin web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = getString(R.string.web3auth_project_id), // pass over your Web3Auth Client ID from Embedded Wallets dashboard - network = Network.SAPPHIRE_MAINNET - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // your app's redirect URL + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // your app's redirect URL // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "web3auth-auth0-demo", - typeOfLogin = TypeOfLogin.JWT, - name = "Auth0 Login", + authConnectionConfig = listOf( + AuthConnectionConfig( + authConnection = AuthConnection.CUSTOM, + authConnectionId = "web3auth-auth0-demo", clientId = getString(R.string.web3auth_auth0_client_id) - ) + ) ) // focus-end - ) + ), + this ) // Handle user signing in when app is not alive @@ -145,18 +145,17 @@ web3Auth.setResultUrl(intent?.data) ##### Logging in -Once initialized, you can use the `web3Auth.connectTo(LoginParams("{selectedLoginProvider}"))` function to authenticate the user when they click the login button. +Once initialized, you can use the `web3Auth.connectTo(LoginParams(...))` function to authenticate the user when they click the login button. ```kotlin private fun signIn() { - val selectedLoginProvider = Provider.JWT // For Auth0, we use JWT val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( // focus-start LoginParams( - selectedLoginProvider, + authConnection = AuthConnection.CUSTOM, + authConnectionId = "web3auth-auth0-demo", extraLoginOptions = ExtraLoginOptions( - domain = "https://YOUR_AUTH0_DOMAIN", - verifierIdField = "sub" + domain = "https://YOUR_AUTH0_DOMAIN" ) ) // focus-end diff --git a/embedded-wallets/authentication/custom-connections/firebase.mdx b/embedded-wallets/authentication/custom-connections/firebase.mdx index 45d1a02095c..50678fc8051 100644 --- a/embedded-wallets/authentication/custom-connections/firebase.mdx +++ b/embedded-wallets/authentication/custom-connections/firebase.mdx @@ -116,20 +116,20 @@ In your activity, create a `Web3Auth` instance with your Web3Auth project's conf ```kotlin web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = getString(R.string.web3auth_project_id), // pass over your Web3Auth Client ID from Embedded Wallets dashboard - network = Network.SAPPHIRE_MAINNET - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // your app's redirect URL + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // your app's redirect URL // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "web3auth-firebase-examples", - typeOfLogin = TypeOfLogin.JWT, - name = "Firebase Login", + authConnectionConfig = listOf( + AuthConnectionConfig( + authConnection = AuthConnection.CUSTOM, + authConnectionId = "web3auth-firebase-examples", clientId = getString(R.string.web3auth_project_id) - ) + ) ) // focus-end - ) + ), + this ) // Handle user signing in when app is not alive @@ -138,7 +138,7 @@ web3Auth.setResultUrl(intent?.data) ##### Logging in -Once initialized, you can use the `web3Auth.connectTo(LoginParams("{selectedLoginProvider}"))` function to authenticate the user when they click the login button. +Once initialized, you can use the `web3Auth.connectTo(LoginParams(...))` function to authenticate the user when they click the login button. ```kotlin private fun signIn() { @@ -155,17 +155,15 @@ private fun signIn() { val idToken = result.token Log.d(TAG, "GetTokenResult result = $idToken") - val selectedLoginProvider = Provider.JWT // focus-start val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - selectedLoginProvider, - extraLoginOptions = ExtraLoginOptions( - domain = "firebase", id_token = idToken - ) - ) + authConnection = AuthConnection.CUSTOM, + authConnectionId = "web3auth-firebase-examples", + idToken = idToken ) - // focus-end + ) + // focus-end loginCompletableFuture.whenComplete { loginResponse, error -> if (error == null) { diff --git a/embedded-wallets/connect-blockchain/_android-connect-blockchain/_evm-get-account.mdx b/embedded-wallets/connect-blockchain/_android-connect-blockchain/_evm-get-account.mdx index 12da412604e..106148685a1 100644 --- a/embedded-wallets/connect-blockchain/_android-connect-blockchain/_evm-get-account.mdx +++ b/embedded-wallets/connect-blockchain/_android-connect-blockchain/_evm-get-account.mdx @@ -1,4 +1,4 @@ -Once user has successfully logged in, you can retrieve the user's private key using the `getPrivKey` method from the Embedded Wallets Android SDK. We'll use this private key to generate the Credentials for the user. +Once user has successfully logged in, you can retrieve the user's private key using the `getPrivateKey` method from the Embedded Wallets Android SDK. We'll use this private key to generate the Credentials for the user. This Credentials object has the user's keypair of private key and public key, and can be used to sign the transactions. Please note, that this assumes that the user has already logged in and the private key is available. @@ -6,7 +6,7 @@ This Credentials object has the user's keypair of private key and public key, an import org.web3j.crypto.Credentials // Use your Embedded Wallets SDK instance to get the private key -val privateKey = web3Auth.getPrivKey() +val privateKey = web3Auth.getPrivateKey() // Generate the Credentials val credentials = Credentials.create(privateKey) diff --git a/embedded-wallets/connect-blockchain/solana/android.mdx b/embedded-wallets/connect-blockchain/solana/android.mdx index d9ed0b3fbb7..6acb4ad3681 100644 --- a/embedded-wallets/connect-blockchain/solana/android.mdx +++ b/embedded-wallets/connect-blockchain/solana/android.mdx @@ -131,33 +131,33 @@ The session can be persisted for up to 30 days max. ```kotlin import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Network import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork // Initialize Web3Auth SDK // focus-start val web3Auth: Web3Auth = Web3Auth( Web3AuthOptions( clientId = "BPi5PB_UiIZ-cPz1GtV5i1I2iOSOHuimiXBI0e-Oe_u6X3oVAbCiAZOTEBtTXw4tsluTITPqA8zMsfxIKMjiqNQ", - context = context, - network = Network.SAPPHIRE_MAINNET, - redirectUrl = Uri.parse( "com.example.androidsolanaexample://auth") - ) + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "com.example.androidsolanaexample://auth" + ), + context ) // focus-end // Check whether private key is empty or not for user authentication status. -val isUserAuthenticated = web3Auth.getPrivkey().isNotEmpty() +val isUserAuthenticated = web3Auth.getEd25519PrivateKey().isNotEmpty() // Customize your logic to perform operations or navigation ``` ## Get account -We can use `getEd25519PrivKey` method in Web3Auth to retrieve the private key for the Solana ecosystem. In the following code block, we'll use the Ed25519 private key to retrieve user's public address by creating `Keypair`. The `Keypair` instance from `sol4k` SDK once created can be used to sign the Solana transactions. +We can use `getEd25519PrivateKey` method in Web3Auth to retrieve the private key for the Solana ecosystem. In the following code block, we'll use the Ed25519 private key to retrieve user's public address by creating `Keypair`. The `Keypair` instance from `sol4k` SDK once created can be used to sign the Solana transactions. ```kotlin -val ed25519PrivateKey = web3Auth.getEd25519PrivKey() +val ed25519PrivateKey = web3Auth.getEd25519PrivateKey() val solanaKeyPair = Keypair.fromSecretKey(ed25519PrivateKey.hexToByteArray()) // focus-next-line diff --git a/embedded-wallets/migration-guides/README.mdx b/embedded-wallets/migration-guides/README.mdx index c7b508df73f..e4723946b0a 100644 --- a/embedded-wallets/migration-guides/README.mdx +++ b/embedded-wallets/migration-guides/README.mdx @@ -30,7 +30,7 @@ current SDK in one pass. | Platform | Upgrade to | Covers upgrades from | | ---------------------------------------------------------------------- | ---------- | -------------------- | | [Web (JavaScript, React, Vue)](/embedded-wallets/migration-guides/web) | v11 | v9 through v10 | -| [Android](/embedded-wallets/migration-guides/android) | v9 | v4 through v8 | +| [Android](/embedded-wallets/migration-guides/android) | v10 | v4 through v9 | | [iOS](/embedded-wallets/migration-guides/ios) | v10 | v6 through v9 | | [React Native](/embedded-wallets/migration-guides/react-native) | v9 | v3 through v8 | | [Flutter](/embedded-wallets/migration-guides/flutter) | v6 | v3 through v5 | diff --git a/embedded-wallets/migration-guides/android.mdx b/embedded-wallets/migration-guides/android.mdx index 7c0cae33134..98a92bb5df9 100644 --- a/embedded-wallets/migration-guides/android.mdx +++ b/embedded-wallets/migration-guides/android.mdx @@ -1,12 +1,15 @@ --- -title: Android SDK v9 Migration Guide -sidebar_label: Android SDK v9 -description: Upgrade the Embedded Wallets Android SDK directly from older versions to v9. -keywords: [migration, v9, android, web3auth, embedded wallets, kotlin] +title: Android SDK v10 Migration Guide +sidebar_label: Android SDK v10 +description: Upgrade the Embedded Wallets Android SDK directly from older versions to v10. +keywords: [migration, v10, v9, android, web3auth, embedded wallets, kotlin] --- -This guide upgrades Embedded Wallets Android SDK integrations from **v4 through v8** directly to -**v9**. +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +This guide upgrades Embedded Wallets Android SDK integrations from **v4 through v9** directly to +**v10**. ## AI-assisted migration @@ -19,21 +22,26 @@ Copy the prompt below into your AI coding assistant (Cursor, Claude Code, Codex, similar): ```txt -Migrate my MetaMask Embedded Wallets Android (web3auth-android-sdk) project to v9. +Migrate my MetaMask Embedded Wallets Android (web3auth-android-sdk) project to v10. Before changing code: 1. Use the web3auth skill and MCP tools (search_docs, get_doc, get_example, get_sdk_reference). -2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/android-v9 +2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/android 3. Detect my current SDK version from build.gradle and list which breaking changes apply. -Then migrate my codebase directly to v9: -- Update the JitPack dependency to com.github.web3auth:web3auth-android-sdk:9.1.2 (or latest v9). +Then migrate my codebase directly to v10: +- Update the JitPack dependency to com.github.web3auth:web3auth-android-sdk:10.0.1 (or latest v10). - Set compileSdk and targetSdk to 34. - Add mandatory redirectUrl to Web3AuthOptions ({YOUR_APP_PACKAGE_NAME}://auth). - Update AndroidManifest.xml (allowBackup=false, tools:replace, deep link intent filter, singleTop). -- Replace getSignResponse() with the SignResponse returned from request(). -- Remove loginParams from launchWalletServices and request; pass chainConfig instead. +- Replace login() with connectTo() and Provider with AuthConnection. +- Replace Network with Web3AuthNetwork, loginConfig with authConnectionConfig, and buildEnv with authBuildEnv. +- Replace getPrivKey() with getPrivateKey() and getEd25519PrivKey() with getEd25519PrivateKey(). +- Replace launchWalletServices() with showWalletUI() and remove ChainConfig parameters. +- Update request() to pass only method and requestParams; remove ChainConfig. +- Replace getSignResponse() with the SignResponse returned from request() (if still on v9 patterns). - Update WhiteLabelData fields (appName, mode, buildEnv) if whitelabeling is configured. +- Configure chains in the Embedded Wallets dashboard; v10 reads chain config from the dashboard. - Do not change my Client ID or Sapphire network unless I ask; that would change wallet addresses. After migrating, list every file you changed and any manual dashboard steps I still need to do. @@ -46,7 +54,7 @@ Review the plan before generating code; config mistakes can change wallet addres ::: -## Install v9 +## Install v10 Add JitPack to your project-level `build.gradle` if it is not already present: @@ -65,7 +73,7 @@ Update the dependency in your app-level `build.gradle`: ```groovy dependencies { - implementation 'com.github.web3auth:web3auth-android-sdk:9.1.2' + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.1' } ``` @@ -82,30 +90,36 @@ android { } ``` +Allowlist `{SCHEME}://{YOUR_APP_PACKAGE_NAME}` on the +[Embedded Wallets dashboard](https://developer.metamask.io). + ## Breaking changes Apply the sections below that match your current version. -If you're already on v8, focus on the [v9 changes](#v9-changes). +If you're already on v9, focus on the [v10 changes](#v10-changes). ### Network and SDK requirements (from v5) -Use Sapphire networks instead of legacy OpenLogin networks: +Use Sapphire networks instead of legacy OpenLogin networks. +In v10, `Network` becomes `Web3AuthNetwork`: ```kotlin +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + val web3Auth = Web3Auth( Web3AuthOptions( - context = this, clientId = getString(R.string.web3auth_project_id), - network = Network.SAPPHIRE_MAINNET, // or Network.SAPPHIRE_DEVNET - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), - ) + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ), + this ) ``` -Add `buildEnv` when you need a non-production auth environment: +Add `authBuildEnv` when you need a non-production auth environment: ```kotlin -buildEnv = BuildEnv.PRODUCTION // PRODUCTION, STAGING, or TESTING +authBuildEnv = BuildEnv.PRODUCTION // PRODUCTION, STAGING, or TESTING ``` ### Whitelabel configuration (from v5) @@ -122,15 +136,13 @@ Prefer [dashboard customization](/embedded-wallets/dashboard/customization) for ### Mandatory redirect URL (from v7.4) -`redirectUrl` is required in `Web3AuthOptions`: +`redirectUrl` is required in `Web3AuthOptions`. +In v10, pass it as a `String` instead of a `Uri`: ```kotlin -redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth") +redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth" ``` -Allowlist `{SCHEME}://{YOUR_APP_PACKAGE_NAME}` on the -[Embedded Wallets dashboard](https://developer.metamask.io). - ### AndroidManifest changes (from v7.1.2) From v7.1.2, set `android:allowBackup` to `false` and add `tools:replace`: @@ -150,8 +162,7 @@ See the [Android SDK get started](/embedded-wallets/sdk/android/) for the full m ### `launchWalletServices` signature (from v7.2) -Remove `loginParams`. -Pass only `chainConfig`: +From v7.2 through v9, remove `loginParams` and pass only `chainConfig`: ```kotlin val launchWalletCompletableFuture = web3Auth.launchWalletServices( @@ -164,10 +175,13 @@ val launchWalletCompletableFuture = web3Auth.launchWalletServices( ) ``` +In v10, replace `launchWalletServices()` with `showWalletUI()` and remove `ChainConfig`. +See [v10 changes](#v10-changes). + ### `request` signature (from v7.3) -Remove `loginParams`. -Pass `chainConfig`, method name, and request parameters: +From v7.3 through v9, remove `loginParams` and pass `chainConfig`, method name, and request +parameters: ```kotlin val params = JsonArray().apply { @@ -187,7 +201,10 @@ val signMsgCompletableFuture = web3Auth.request( ) ``` -### v9 changes {#v9-changes} +In v10, remove `chainConfig` from `request()`. +See [v10 changes](#v10-changes). + +### v9 changes `getSignResponse()` is removed. The `request()` method returns `SignResponse` directly: @@ -205,33 +222,264 @@ signMsgCompletableFuture.whenComplete { signResult, error -> v9 also adds support for Web3Auth Auth Service v9 and Wallet Services v3 (including swap in the prebuilt wallet UI). -## New APIs (non-breaking) +### v10 changes {#v10-changes} -These APIs were added in intermediate versions. -If you're upgrading from an older SDK, adopt the v9 signatures shown above. +v10 unifies Plug and Play (PnP) and Single Factor Auth (SFA) in one SDK and renames several APIs. + +#### Import changes + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import com.web3auth.core.types.Network +import com.web3auth.core.types.Provider +import com.web3auth.core.types.LoginConfigItem +import com.web3auth.core.types.TypeOfLogin +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import com.web3auth.core.types.AuthConnection +import com.web3auth.core.types.AuthConnectionConfig +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork +``` + + + + +#### Enum renames + +| v9.x | v10.x | +| ----------------- | ----------------------- | +| `Provider` | `AuthConnection` | +| `TypeOfLogin` | `AuthConnection` | +| `Network` | `Web3AuthNetwork` | +| `LoginConfigItem` | `AuthConnectionConfig` | +| `Provider.JWT` | `AuthConnection.CUSTOM` | + +#### `Web3AuthOptions` configuration + + + + + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_CLIENT_ID", + network = Network.SAPPHIRE_MAINNET, + redirectUrl = Uri.parse("your-app://auth"), + loginConfig = hashMapOf("google" to LoginConfigItem( + verifier = "verifier-name", + typeOfLogin = TypeOfLogin.GOOGLE, + clientId = "google-client-id" + )), + buildEnv = BuildEnv.PRODUCTION + ) +) +``` + + + + + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + clientId = "YOUR_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "your-app://auth", + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "verifier-name", + authConnection = AuthConnection.GOOGLE, + clientId = "google-client-id" + )), + authBuildEnv = BuildEnv.PRODUCTION + ), + this +) +``` + + + -| API | Added in | Purpose | -| ------------------------ | -------- | --------------------------------------------- | -| `enableMFA()` | v6 | Initiate MFA setup for logged-in users | -| `launchWalletServices()` | v6 | Open the templated wallet UI | -| `request()` | v6.1 | Sign transactions with confirmation screens | -| SMS Passwordless login | v7.2 | `Provider.SMS_PASSWORDLESS` with `login_hint` | -| Farcaster login | v7.2 | `Provider.farcaster` | +#### Authentication method -See [Wallet Services](/embedded-wallets/sdk/android/usage/launch-wallet-services) and +Replace `login()` with `connectTo()`: + + + + + +```kotlin +// Simple social login +val loginCompletableFuture = web3Auth.login( + LoginParams(Provider.GOOGLE) +) + +// Email passwordless +val loginCompletableFuture = web3Auth.login( + LoginParams( + Provider.EMAIL_PASSWORDLESS, + extraLoginOptions = ExtraLoginOptions(login_hint = "user@example.com") + ) +) + +// JWT login +val loginCompletableFuture = web3Auth.login( + LoginParams( + Provider.JWT, + extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token") + ) +) +``` + + + + + +```kotlin +// Simple social login (PnP mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) +) + +// Email passwordless (PnP mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.EMAIL_PASSWORDLESS, + loginHint = "user@example.com" + ) +) + +// JWT login (SFA mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_auth_connection_id", + idToken = "your_jwt_token" + ) +) +``` + + + + +#### Private key methods + +| v9.x | v10.x | +| --------------------- | ------------------------ | +| `getPrivKey()` | `getPrivateKey()` | +| `getEd25519PrivKey()` | `getEd25519PrivateKey()` | + +#### Wallet services + + + + + +```kotlin +val chainConfig = ChainConfig( + chainId = "0x1", + rpcTarget = "https://rpc.ethereum.org", + ticker = "ETH", + chainNamespace = ChainNamespace.EIP155 +) + +val launchWalletCF = web3Auth.launchWalletServices(chainConfig) + +val signCF = web3Auth.request( + chainConfig = chainConfig, + method = "personal_sign", + requestParams = params +) +``` + + + + + +```kotlin +val launchWalletCF = web3Auth.showWalletUI() + +val signCF = web3Auth.request( + method = "personal_sign", + requestParams = params +) +``` + + + + +Configure chains in the [Embedded Wallets dashboard](/embedded-wallets/dashboard/chains-and-networks/). +v10 reads chain configuration from your project settings instead of `ChainConfig` in code. + +## New APIs (non-breaking) + +These APIs were added in intermediate versions. +If you're upgrading from an older SDK, adopt the v10 signatures shown above. + +| API | Added in | Purpose | +| ------------------------ | -------- | -------------------------------------------------------- | +| `enableMFA()` | v6 | Initiate MFA setup for logged-in users | +| `launchWalletServices()` | v6 | Open the templated wallet UI (v10: `showWalletUI()`) | +| `request()` | v6.1 | Sign transactions with confirmation screens | +| SMS Passwordless login | v7.2 | `AuthConnection.SMS_PASSWORDLESS` with `loginHint` | +| Farcaster login | v7.2 | `AuthConnection.FARCASTER` | +| SFA with JWT | v10 | `connectTo()` with `AuthConnection.CUSTOM` and `idToken` | + +See [Wallet Services](/embedded-wallets/sdk/android/usage/launch-wallet-services), +[Request](/embedded-wallets/sdk/android/usage/request), and [MFA](/embedded-wallets/sdk/android/advanced/mfa) for usage details. ## Summary table -| Area | Before v5 | v5-v7.3 | v9 | -| ---------------------- | ------------------- | -------------------------- | --------------------------- | -| Network | Mainnet, Cyan, etc. | Sapphire supported | Sapphire recommended | -| compileSdk / targetSdk | 33 | 34 | 34 | -| `redirectUrl` | Optional | Mandatory (v7.4+) | Mandatory | -| Whitelabel `name` | `name` | `appName` | `appName` | -| `launchWalletServices` | N/A | Drops `loginParams` (v7.2) | `chainConfig` only | -| `request` | N/A | Drops `loginParams` (v7.3) | Returns `SignResponse` | -| Sign result | N/A | `getSignResponse()` | Return value of `request()` | +| Area | Before v5 | v5-v9 | v10 | +| ---------------------- | ------------------- | ------------------------ | -------------------------------- | +| Network | Mainnet, Cyan, etc. | Sapphire supported | `Web3AuthNetwork` (Sapphire) | +| compileSdk / targetSdk | 33 | 34 | 34 | +| `redirectUrl` | Optional | Mandatory (v7.4+) | Mandatory (`String`) | +| Whitelabel `name` | `name` | `appName` | `appName` | +| Authentication | N/A | `login()` + `Provider` | `connectTo()` + `AuthConnection` | +| Private key | N/A | `getPrivKey()` | `getPrivateKey()` | +| Wallet UI | N/A | `launchWalletServices()` | `showWalletUI()` | +| `request` | N/A | `chainConfig` + method | method + `requestParams` only | +| Sign result | N/A | `getSignResponse()` (v8) | Return value of `request()` | +| Chain config | N/A | Passed in code | Dashboard-managed | ## Next steps diff --git a/embedded-wallets/sdk/android/README.mdx b/embedded-wallets/sdk/android/README.mdx index 9df67aba3b8..7fa98d28572 100644 --- a/embedded-wallets/sdk/android/README.mdx +++ b/embedded-wallets/sdk/android/README.mdx @@ -55,7 +55,7 @@ Then, in your app-level `build.gradle` dependencies section, add the following: dependencies { // ... // focus-next-line - implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.1' } ``` diff --git a/embedded-wallets/sdk/android/advanced/README.mdx b/embedded-wallets/sdk/android/advanced/README.mdx index 65986bccf15..fe46ce134da 100644 --- a/embedded-wallets/sdk/android/advanced/README.mdx +++ b/embedded-wallets/sdk/android/advanced/README.mdx @@ -47,17 +47,17 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. -| Parameter | Description | -| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `context` | Android context to launch web-based authentication, usually is the current activity. It's a mandatory field, and accepts `android.content.Context` as a value. | -| `clientId` | Your Embedded Wallets Client ID. You can get it from Embedded Wallets [dashboard](https://developer.metamask.io/) under project details. It's a mandatory field of type `String` | -| `web3AuthNetwork` | Defines the Embedded Wallets Network. It's a mandatory field of type `Web3AuthNetwork`. | -| `redirectUrl` | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type `String`. | -| `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is `86400 * 30` (30 days). `sessionTime` can be max 30 days. | -| `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for wallet pregeneration and SFA mode. | -| `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. See [Chains configuration](#chains-configuration) below. | +| Parameter | Description | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `context` | Android context to launch web-based authentication, usually is the current activity. It's a mandatory field, and accepts `android.content.Context` as a value. | +| `clientId` | Your Embedded Wallets Client ID. You can get it from Embedded Wallets [dashboard](https://developer.metamask.io/) under project details. It's a mandatory field of type `String` | +| `web3AuthNetwork` | Defines the Embedded Wallets Network. It's a mandatory field of type `Web3AuthNetwork`. | +| `redirectUrl` | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type `String`. | +| `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is `86400 * 30` (30 days). `sessionTime` can be max 30 days. | +| `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for wallet pregeneration and SFA mode. | +| `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. See [Chains configuration](#chains-configuration) below. | | `defaultChainId?` | Default chain ID to use. It's an optional field with a default value of `"0x1"` (Ethereum mainnet). The first chain from the project config will be used if the project has chains configured. | -| `enableLogging?` | Setting to true will enable logs. It's an optional field with default value as `false`. | +| `enableLogging?` | Setting to true will enable logs. It's an optional field with default value as `false`. | diff --git a/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx deleted file mode 100644 index 65055641b0e..00000000000 --- a/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx +++ /dev/null @@ -1,414 +0,0 @@ ---- -title: Migrating from v9.x to v10.x -sidebar_label: v9.x to v10.x -description: 'Web3Auth Android SDK - Migrating from v9.x to v10.x | Embedded Wallets' ---- - -import TabItem from '@theme/TabItem' -import Tabs from '@theme/Tabs' - -This migration guide provides a step-by-step walkthrough for upgrading your Web3Auth Android SDK implementation from v9.x to v10.x. This is a major release with significant API changes, new features, and improvements. - -## Overview of Changes - -Web3Auth Android SDK v10.x introduces several major changes: - -- **Combined PnP and SFA SDK**: Unified authentication flow supporting both Plug and Play (PnP) and Single Factor Auth (SFA) in one SDK -- **Updated Authentication API**: `login()` method replaced with `connectTo()` for better clarity and SFA support -- **Simplified Wallet Services**: Automatic chain configuration from dashboard settings -- **Enhanced Type Safety**: Updated enums and parameter structures -- **Analytics Integration**: Built-in analytics for better insights -- **Performance Improvements**: Optimized parameter handling and reduced configuration complexity - -## Breaking Changes - -### 1. Update Dependencies - -First, update your dependency to the latest version: - -```groovy -dependencies { - // Old - implementation 'com.github.web3auth:web3auth-android-sdk:9.1.2' - - // New - implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' -} -``` - -### 2. Import Changes - -Add the new required import for Web3AuthNetwork: - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions -import com.web3auth.core.types.Network -import com.web3auth.core.types.Provider -import com.web3auth.core.types.LoginConfigItem -import com.web3auth.core.types.TypeOfLogin -``` - - - - - -```kotlin -import com.web3auth.core.Web3Auth -import com.web3auth.core.types.Web3AuthOptions -import com.web3auth.core.types.AuthConnection -import com.web3auth.core.types.AuthConnectionConfig -import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork -``` - - - - -### 3. Enum Changes - -Several enums have been renamed for better clarity: - -| v9.x | v10.x | -| ----------------- | ----------------------- | -| `Provider` | `AuthConnection` | -| `TypeOfLogin` | `AuthConnection` | -| `Network` | `Web3AuthNetwork` | -| `LoginConfigItem` | `AuthConnectionConfig` | -| `Provider.JWT` | `AuthConnection.CUSTOM` | - -### 4. Web3AuthOptions Configuration - -The configuration object has been updated with new parameter names: - - - - - -```kotlin -val web3Auth = Web3Auth( - Web3AuthOptions( - context = this, - clientId = "YOUR_CLIENT_ID", - network = Network.SAPPHIRE_MAINNET, - redirectUrl = Uri.parse("your-app://auth"), - loginConfig = hashMapOf("google" to LoginConfigItem( - verifier = "verifier-name", - typeOfLogin = TypeOfLogin.GOOGLE, - clientId = "google-client-id" - )), - buildEnv = BuildEnv.PRODUCTION - ) -) -``` - - - - - -```kotlin -val web3Auth = Web3Auth( - Web3AuthOptions( - clientId = "YOUR_CLIENT_ID", - web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, - redirectUrl = "your-app://auth", // Now a String instead of Uri - authConnectionConfig = listOf(AuthConnectionConfig( - authConnectionId = "verifier-name", - authConnection = AuthConnection.GOOGLE, - clientId = "google-client-id" - )), - authBuildEnv = BuildEnv.PRODUCTION // Renamed from buildEnv - ), - this -) -``` - - - - -### 5. Authentication Method Changes - -The main authentication method has been renamed and enhanced: - - - - - -```kotlin -// Simple social login -val loginCompletableFuture = web3Auth.login( - LoginParams(Provider.GOOGLE) -) - -// Email passwordless -val loginCompletableFuture = web3Auth.login( - LoginParams( - Provider.EMAIL_PASSWORDLESS, - extraLoginOptions = ExtraLoginOptions(login_hint = "user@example.com") - ) -) - -// JWT login -val loginCompletableFuture = web3Auth.login( - LoginParams( - Provider.JWT, - extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token") - ) -) -``` - - - - - -```kotlin -// Simple social login (PnP mode) -val loginCompletableFuture = web3Auth.connectTo( - LoginParams(AuthConnection.GOOGLE) -) - -// Email passwordless (PnP mode) -val loginCompletableFuture = web3Auth.connectTo( - LoginParams( - AuthConnection.EMAIL_PASSWORDLESS, - loginHint = "user@example.com" // Simplified parameter - ) -) - -// JWT login (SFA mode) -val loginCompletableFuture = web3Auth.connectTo( - LoginParams( - AuthConnection.CUSTOM, - authConnectionId = "your_auth_connection_id", - idToken = "your_jwt_token" // Dedicated parameter for SFA - ) -) -``` - - - - -### 6. Private Key Method Names - -The private key retrieval methods have been renamed for clarity: - - - - - -```kotlin -val privateKey = web3Auth.getPrivKey() -val ed25519Key = web3Auth.getEd25519PrivKey() -``` - - - - - -```kotlin -val privateKey = web3Auth.getPrivateKey() -val ed25519Key = web3Auth.getEd25519PrivateKey() -``` - - - - -### 7. Wallet Services Simplification - -Wallet services methods have been simplified with automatic chain configuration: - - - - - -```kotlin -// Launch wallet services -val chainConfig = ChainConfig( - chainId = "0x1", - rpcTarget = "https://rpc.ethereum.org", - ticker = "ETH", - chainNamespace = ChainNamespace.EIP155 -) - -val launchWalletCF = web3Auth.launchWalletServices(chainConfig) - -// Request signing -val signCF = web3Auth.request( - chainConfig = chainConfig, - method = "personal_sign", - requestParams = params -) -``` - - - - - -```kotlin -// Launch wallet services (automatic chain config from dashboard) -val launchWalletCF = web3Auth.showWalletUI() - -// Request signing (automatic chain config from dashboard) -val signCF = web3Auth.request( - method = "personal_sign", - requestParams = params -) -``` - - - - -## New Features - -### 1. Single Factor Auth (SFA) Support - -v10.x introduces built-in SFA support. You can now use SFA by providing an `idToken`: - -```kotlin -// SFA login with custom JWT -val loginCompletableFuture = web3Auth.connectTo( - LoginParams( - AuthConnection.CUSTOM, - authConnectionId = "your_verifier_id", - idToken = "your_jwt_token" - ) -) - -// SFA with aggregate verifier -val loginCompletableFuture = web3Auth.connectTo( - LoginParams( - AuthConnection.CUSTOM, - authConnectionId = "aggregate_verifier_id", - groupedAuthConnectionId = "sub_verifier_id", - idToken = "your_jwt_token" - ) -) -``` - -### 2. Enhanced Parameter Handling - -v10.x provides better parameter organization: - -```kotlin -val loginCompletableFuture = web3Auth.connectTo( - LoginParams( - authConnection = AuthConnection.EMAIL_PASSWORDLESS, - loginHint = "user@example.com", // Direct parameter - dappUrl = "https://your-dapp.com", // For analytics - appState = "custom_state" // App state tracking - ) -) -``` - -### 3. Automatic Chain Configuration - -Chain configuration is now managed automatically from your Web3Auth Dashboard: - -1. Configure chains in your [Web3Auth Dashboard](https://dashboard.web3auth.io) -2. The SDK automatically uses these configurations -3. No need to manually pass `ChainConfig` to wallet services - -## Migration Steps - -### Step 1: Update Dependencies - -```groovy -// In your app-level build.gradle -dependencies { - implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' -} -``` - -### Step 2: Update Imports - -Replace old imports with new ones as shown in the [Import Changes](#2-import-changes) section. - -### Step 3: Update Initialization - -1. Replace `network` with `web3AuthNetwork` -2. Replace `redirectUrl` Uri with String -3. Update `loginConfig` to `authConnectionConfig` -4. Replace `buildEnv` with `authBuildEnv` - -### Step 4: Update Authentication Calls - -1. Replace `login()` with `connectTo()` -2. Replace `Provider` with `AuthConnection` -3. Update parameter names in `LoginParams` - -### Step 5: Update Private Key Calls - -1. Replace `getPrivKey()` with `getPrivateKey()` -2. Replace `getEd25519PrivKey()` with `getEd25519PrivateKey()` - -### Step 6: Update Wallet Services - -1. Replace `launchWalletServices()` with `showWalletUI()` -2. Remove `ChainConfig` parameters from both `showWalletUI()` and `request()` - -### Step 7: Configure Dashboard - -Ensure your Web3Auth Dashboard has the necessary chain configurations since they're now automatically managed. - -## Troubleshooting - -### Common Issues - -1. **Chain Configuration Missing**: Ensure your Web3Auth Dashboard has the required chains configured -2. **Import Errors**: Make sure to import `Web3AuthNetwork` from the correct package -3. **Parameter Mismatch**: Double-check that you're using the new parameter names - -### Migration Checklist - -- Dependencies updated to v10.x -- Imports updated with new package references -- `Web3AuthOptions` configuration updated -- `login()` calls replaced with `connectTo()` -- Private key method names updated -- Wallet services methods updated -- Dashboard chain configuration verified -- Testing completed for all authentication flows - -## Support - -If you encounter any issues during migration, please: - -1. Check this migration guide thoroughly -2. Review the [updated documentation](/embedded-wallets/sdk/android) -3. Visit our [Support Forum](https://web3auth.io/community/c/help-pnp/pnp-sdk/android/16) -4. Check the [GitHub repository](https://github.com/Web3Auth/web3auth-android-sdk) for known issues - -The v10.x release provides a more robust, feature-rich, and developer-friendly experience while maintaining the core Web3Auth functionality you rely on. diff --git a/embedded-wallets/sdk/android/usage/README.mdx b/embedded-wallets/sdk/android/usage/README.mdx index ffb6a0b305f..254f3951914 100644 --- a/embedded-wallets/sdk/android/usage/README.mdx +++ b/embedded-wallets/sdk/android/usage/README.mdx @@ -16,10 +16,10 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Authentication functions -| Function Name | Description | -| ------------------------------------ | --------------------------------------------------------------------------------------------------- | -| [`connectTo()`](./connect-to.mdx) | Logs in the user with the selected auth connection. Supports both PnP and SFA authentication modes. | -| [`logout()`](./logout.mdx) | Logs out the user from the current session. | +| Function Name | Description | +| --------------------------------- | --------------------------------------------------------------------------------------------------- | +| [`connectTo()`](./connect-to.mdx) | Logs in the user with the selected auth connection. Supports both PnP and SFA authentication modes. | +| [`logout()`](./logout.mdx) | Logs out the user from the current session. | ### User management functions @@ -30,9 +30,9 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Private key functions -| Function Name | Description | -| ------------------------------------------------------ | ------------------------------------------------------------------------------- | -| [`getPrivateKey()`](./get-private-key.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | +| Function Name | Description | +| --------------------------------------------------------- | ------------------------------------------------------------------------------- | +| [`getPrivateKey()`](./get-private-key.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | | [`getEd25519PrivateKey()`](./get-ed25519-private-key.mdx) | Retrieve the user's ed25519 private key for chains like Solana, Near, Algorand. | ### Security functions @@ -44,10 +44,10 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Wallet Services functions -| Function Name | Description | -| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| [`showWalletUI()`](./launch-wallet-services.mdx) | Launches the templated wallet UI in WebView with automatic chain configuration from dashboard. | -| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions with simplified parameters. | +| Function Name | Description | +| ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | +| [`showWalletUI()`](./launch-wallet-services.mdx) | Launches the templated wallet UI in WebView with automatic chain configuration from dashboard. | +| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions with simplified parameters. | ## `getWeb3AuthResponse()` diff --git a/src/pages/tutorials/android-wallet.mdx b/src/pages/tutorials/android-wallet.mdx index 9fafeb5f867..b7bbf387a7c 100644 --- a/src/pages/tutorials/android-wallet.mdx +++ b/src/pages/tutorials/android-wallet.mdx @@ -71,7 +71,7 @@ dependencyResolutionManagement { dependencies { // ... // focus-next-line - implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.1' } ``` @@ -303,7 +303,7 @@ app-level dependencies. dependencies { // ... // focus-next-line - implementation 'org.web3j:core:4.8.7-android' + implementation 'org.web3j:core:4.8.8-android' } ``` diff --git a/src/utils/w3a-sdk-map.js b/src/utils/w3a-sdk-map.js index 8e424fb40cd..81f3410abf7 100644 --- a/src/utils/w3a-sdk-map.js +++ b/src/utils/w3a-sdk-map.js @@ -14,7 +14,7 @@ export const unity = 'Unity' export const unreal = 'Unreal Engine' export const pnpWebVersion = `11.0.x` -export const pnpAndroidVersion = `10.0.x` +export const pnpAndroidVersion = `10.0.1` export const pnpIOSVersion = `11.1.0` export const pnpRNVersion = `8.1.x` export const pnpNodeVersion = `5.0.x` diff --git a/vercel.json b/vercel.json index 6e473386a53..17a830538e9 100644 --- a/vercel.json +++ b/vercel.json @@ -1067,6 +1067,16 @@ "destination": "/embedded-wallets/migration-guides/web/", "permanent": true }, + { + "source": "/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10/", + "destination": "/embedded-wallets/migration-guides/android/", + "permanent": true + }, + { + "source": "/embedded-wallets/migration-guides/android-v9-to-v10/", + "destination": "/embedded-wallets/migration-guides/android/", + "permanent": true + }, { "source": "/embedded-wallets/sdk/android/migration-guides/:path*", "destination": "/embedded-wallets/migration-guides/android/", From f78f3a60127ce741b8215c94d0614deca9d00059 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Thu, 2 Jul 2026 20:14:43 +0400 Subject: [PATCH 12/12] Run vale and consensys style guide --- .../custom-connections/auth0.mdx | 18 +-- .../custom-connections/firebase.mdx | 26 ++-- .../connect-blockchain/solana/android.mdx | 15 +-- embedded-wallets/migration-guides/android.mdx | 52 ++++---- embedded-wallets/sdk/android/README.mdx | 26 ++-- .../sdk/android/advanced/README.mdx | 30 ++--- .../advanced/custom-authentication.mdx | 114 +++++++++--------- .../sdk/android/advanced/dapp-share.mdx | 24 ++-- embedded-wallets/sdk/android/advanced/mfa.mdx | 32 ++--- .../sdk/android/advanced/smart-accounts.mdx | 2 +- .../sdk/android/advanced/whitelabel.mdx | 12 +- embedded-wallets/sdk/android/usage/README.mdx | 20 +-- .../sdk/android/usage/connect-to.mdx | 60 ++++----- .../sdk/android/usage/enable-mfa.mdx | 4 +- .../sdk/android/usage/get-user-info.mdx | 30 ++--- .../android/usage/launch-wallet-services.mdx | 4 +- .../sdk/android/usage/manage-mfa.mdx | 2 +- .../sdk/android/usage/request.mdx | 4 +- src/utils/w3a-sdk-map.js | 16 +-- 19 files changed, 253 insertions(+), 238 deletions(-) diff --git a/embedded-wallets/authentication/custom-connections/auth0.mdx b/embedded-wallets/authentication/custom-connections/auth0.mdx index 64e0333bace..44f0a9b1bb0 100644 --- a/embedded-wallets/authentication/custom-connections/auth0.mdx +++ b/embedded-wallets/authentication/custom-connections/auth0.mdx @@ -1,7 +1,7 @@ --- -title: Auth0 Login with Embedded Wallets +title: Auth0 sign-in with Embedded Wallets sidebar_label: Auth0 -description: 'Auth0 Login with Embedded Wallets | Embedded Wallets' +description: 'Auth0 sign-in with Embedded Wallets | Embedded Wallets' --- import Tabs from '@theme/Tabs' @@ -17,7 +17,7 @@ import ImplicitLoginAuth0Spa from '../../sdk/react/advanced/_custom-authenticati [Auth0](https://auth0.com/docs/get-started/auth0-overview) is an authentication and authorization platform that enables developers to securely manage user identities. Web3Auth offers native support for integrating Auth0 as a service provider, allowing projects to leverage Auth0's robust authentication mechanisms within the Web3Auth ecosystem. -Auth0 supports a [wide set of social logins](https://marketplace.auth0.com/categories/social-login). +Auth0 supports a [wide set of social sign-in providers](https://marketplace.auth0.com/categories/social-login). ## Create an Auth0 application @@ -43,7 +43,7 @@ export const Auth0Setup = [ path: 'https://auth0.com/docs/quickstart/native/android/interactive', }, { - key: 'ios', + key: 'iOS', title: 'iOS', icon: 'logo-apple.png', path: 'https://auth0.com/docs/quickstart/native/ios-swift/interactive', @@ -143,9 +143,9 @@ web3Auth = Web3Auth( web3Auth.setResultUrl(intent?.data) ``` -##### Logging in +##### Signing in -Once initialized, you can use the `web3Auth.connectTo(LoginParams(...))` function to authenticate the user when they click the login button. +Once initialized, you can use the `web3Auth.connectTo(LoginParams(...))` function to authenticate the user when they click the sign-in button. ```kotlin private fun signIn() { @@ -163,13 +163,13 @@ private fun signIn() { } ``` -When connecting, the `connectTo` function takes the `LoginParams` arguments for the login. See the [LoginParams](/embedded-wallets/sdk/android/usage/connect-to#parameters) for more details. +When connecting, the `connectTo` function takes the `LoginParams` arguments for sign-in. See the [LoginParams](/embedded-wallets/sdk/android/usage/connect-to#parameters) for more details. ### Flutter ##### Create a Web3Auth instance -In your `main.dart` file, initialize the `Web3AuthFlutter` plugin at the very beginning such as in the overriden `initState` function +In your `main.dart` file, initialize the `Web3AuthFlutter` plugin at the start of your app, such as in the overridden `initState` function ```dart Future initPlatformState() async { @@ -207,7 +207,7 @@ Future initPlatformState() async { ##### Logging in -Once initialized, you can use the `Web3AuthFlutter.login(LoginParams( loginProvider: Provider.google ))` function to authenticate the user when they click the login button. +Once initialized, you can use the `Web3AuthFlutter.login(LoginParams( loginProvider: Provider.google ))` function to authenticate the user when they click the sign-in button. ```dart Future _withAuth0() { diff --git a/embedded-wallets/authentication/custom-connections/firebase.mdx b/embedded-wallets/authentication/custom-connections/firebase.mdx index 50678fc8051..e624b0c9400 100644 --- a/embedded-wallets/authentication/custom-connections/firebase.mdx +++ b/embedded-wallets/authentication/custom-connections/firebase.mdx @@ -1,7 +1,7 @@ --- -title: Firebase Login with Embedded Wallets +title: Firebase sign-in with Embedded Wallets sidebar_label: Firebase -description: 'Firebase Login with Embedded Wallets | Embedded Wallets' +description: 'Firebase sign-in with Embedded Wallets | Embedded Wallets' --- import Tiles from '@theme/Tiles' @@ -10,9 +10,9 @@ import CustomConnectionOptions from '@site/static/img/embedded-wallets/dev-dashb import FirebaseConnection from '@site/static/img/embedded-wallets/dev-dashboard/firebase-connection.png' import JwtLoginFirebase from '../../sdk/react/advanced/_custom-authentication-snippets/_jwt_login_firebase.mdx' -[Firebase](https://firebase.google.com/) is a popular backend platform that enables developers to integrate authentication, databases, and other services into their applications. Embedded Wallets supports Firebase as an authentication provider, allowing developers to leverage Firebase Authentication within the Web3Auth framework for secure user login and key management. +[Firebase](https://firebase.google.com/) is a popular backend platform that enables developers to integrate authentication, databases, and other services into their applications. Embedded Wallets supports Firebase as an authentication provider, allowing developers to leverage Firebase Authentication within the Web3Auth framework for secure user sign-in and key management. -Firebase [supports a wide set of social logins](https://firebase.google.com/docs/auth). +Firebase [supports a wide set of social sign-in providers](https://firebase.google.com/docs/auth). ## Create a Firebase project @@ -25,6 +25,8 @@ Web3Auth's Firebase integration enables the use of Firebase-issued ID tokens to For detailed implementation steps and platform-specific instructions, developers can follow the [Firebase documentation](https://firebase.google.com/docs). ::: + + export const FirebaseSetup = [ { name: '', @@ -43,7 +45,7 @@ export const FirebaseSetup = [ path: 'https://firebase.google.com/docs/android/setup', }, { - key: 'ios', + key: 'iOS', title: 'iOS', icon: 'logo-apple.png', path: 'https://firebase.google.com/docs/ios/setup', @@ -64,6 +66,8 @@ export const FirebaseSetup = [ }, ] + + ## Create a Firebase connection @@ -87,7 +91,7 @@ Follow these steps to create a Firebase connection: 1. Select the **JWT user identifier**: `email`, `sub` or `custom`. 1. (Optional) Toggle the case sensitivity of **User Identifier**. 1. Click on **Add Custom Validations** to add validations manually. - 1. Type iss as a field and `https://securetoken.google.com/FIREBASE-PROJECT-ID` as a value. + 1. Type `iss` as a field and `https://securetoken.google.com/FIREBASE-PROJECT-ID` as a value. 1. Next, type aud as a field and `FIREBASE-PROJECT-ID` as a value. 1. Click on the **Add Connection** button to save the settings. @@ -136,9 +140,9 @@ web3Auth = Web3Auth( web3Auth.setResultUrl(intent?.data) ``` -##### Logging in +##### Signing in -Once initialized, you can use the `web3Auth.connectTo(LoginParams(...))` function to authenticate the user when they click the login button. +Once initialized, you can use the `web3Auth.connectTo(LoginParams(...))` function to authenticate the user when they click the sign-in button. ```kotlin private fun signIn() { @@ -185,13 +189,13 @@ private fun signIn() { } ``` -When connecting, the `connectTo` function takes the `LoginParams` arguments for the login. See the [LoginParams](/embedded-wallets/sdk/android/usage/connect-to#parameters) for more details. +When connecting, the `connectTo` function takes the `LoginParams` arguments for sign-in. See the [LoginParams](/embedded-wallets/sdk/android/usage/connect-to#parameters) for more details. ### Flutter ##### Create a Web3Auth instance -In your `main.dart` file, initialize the `Web3AuthFlutter` plugin at the very beginning such as in the overriden `initState` function +In your `main.dart` file, initialize the `Web3AuthFlutter` plugin at the start of your app, such as in the overridden `initState` function ```dart @override @@ -236,7 +240,7 @@ Future initPlatformState() async { ##### Logging in -Once initialized, you can use the `Web3AuthFlutter.login(LoginParams( loginProvider: Provider.google ))` function to authenticate the user when they click the login button. +Once initialized, you can use the `Web3AuthFlutter.login(LoginParams( loginProvider: Provider.google ))` function to authenticate the user when they click the sign-in button. ```dart Future _withJWT() async { diff --git a/embedded-wallets/connect-blockchain/solana/android.mdx b/embedded-wallets/connect-blockchain/solana/android.mdx index 6acb4ad3681..eef9204d1cb 100644 --- a/embedded-wallets/connect-blockchain/solana/android.mdx +++ b/embedded-wallets/connect-blockchain/solana/android.mdx @@ -10,7 +10,7 @@ description: 'Integrate Embedded Wallets with the Solana Blockchain in Android | import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -While using the Embedded Wallets Android SDK (formerly Web3Auth), you can retrieve the Ed25519 private key upon successful authentication. This private key can be used to derive the user's public address and interact with the [Solana](https://solana.org/) chain. We've highlighted a few methods here to get you started quickly. +While using the Embedded Wallets Android SDK (formerly Web3Auth), you can retrieve the Ed25519 private key upon successful authentication. This private key can be used to derive the user's public address and interact with the [Solana](https://solana.org/) chain. We've highlighted a few methods here to help you get started. ::::note @@ -77,7 +77,7 @@ In your app-level `build.gradle` dependencies section, add the following: @@ -91,7 +91,7 @@ dependencies { - + ```kotlin dependencies { @@ -104,7 +104,7 @@ dependencies { ## Initialize -To Initialize the `Connection` we require a RPC URL. The `Connection` object will provide a gateway and protocol to interact with Solana cluster while sending requests and receving response. The `sol4k` SDK also provides `RpcUrl` constant for all the supported clusters. For this example, we are using `RpcUrl.DEVNET` for Devnet-beta. To interact with Testnet or Mainnet, change the `RpcUrl`. +To Initialize the `Connection` we require a RPC URL. The `Connection` object will provide a gateway and protocol to interact with Solana cluster while sending requests and receiving responses. The `sol4k` SDK also provides `RpcUrl` constant for all the supported clusters. For this example, we are using `RpcUrl.DEVNET` for Devnet-beta. To interact with Testnet or Mainnet, change the `RpcUrl`. ### Initializing the Solana SDK @@ -161,12 +161,13 @@ val ed25519PrivateKey = web3Auth.getEd25519PrivateKey() val solanaKeyPair = Keypair.fromSecretKey(ed25519PrivateKey.hexToByteArray()) // focus-next-line -val userAccount = solanaKeyPair.publicKey.toBase58() +// Get the user's public key +val publicKey = solanaKeyPair.publicKey.toBase58() ``` ## Get user balance -Once we have retrieved userAccount, we can use it to fetch user balance. We'll use `getBalance` method from `Connection` instance to interact with Solana cluster and fetch user balance. The response of `getBalance` is BigInteger, we will need to divide it by 10^9, because Solana's token decimals is 9. +Once you have the user's public key, you can use it to fetch the user balance. We'll use `getBalance` method from `Connection` instance to interact with Solana cluster and fetch user balance. The response of `getBalance` is BigInteger, we will need to divide it by 10^9, because Solana's token decimals is 9. ```kotlin try { @@ -186,7 +187,7 @@ try { ## Sign a transaction -Let's now go through how can we sign the transaction. In the below codeblock, we'll create a new function `prepareSignedTransaction` which can be used to retrieve the Base58 signature as well as broadcast transaction to the cluster. We'll use `TransferInstruction` to create the transaction to self transfer 0.01 Sol and sign it. +Let's now go through how can we sign the transaction. In the below code block, we'll create a new function `prepareSignedTransaction` which can be used to retrieve the Base58 signature as well as broadcast transaction to the cluster. We'll use `TransferInstruction` to create the transaction to self transfer 0.01 Sol and sign it. ```kotlin private suspend fun prepareSignedTransaction(sender: Keypair) : Transaction = withContext(Dispatchers.IO) { diff --git a/embedded-wallets/migration-guides/android.mdx b/embedded-wallets/migration-guides/android.mdx index 98a92bb5df9..d6a9ec73e4d 100644 --- a/embedded-wallets/migration-guides/android.mdx +++ b/embedded-wallets/migration-guides/android.mdx @@ -157,7 +157,7 @@ From v7.1.2, set `android:allowBackup` to `false` and add `tools:replace`: ``` -Set your main activity `launchMode` to **singleTop** and add the deep link intent filter. +Set your main activity `launchMode` to `singleTop` and add the deep link intent filter. See the [Android SDK get started](/embedded-wallets/sdk/android/) for the full manifest setup. ### `launchWalletServices` signature (from v7.2) @@ -340,7 +340,7 @@ Replace `login()` with `connectTo()`: ```kotlin -// Simple social login +// Simple social sign-in val loginCompletableFuture = web3Auth.login( LoginParams(Provider.GOOGLE) ) @@ -353,7 +353,7 @@ val loginCompletableFuture = web3Auth.login( ) ) -// JWT login +// JWT sign-in val loginCompletableFuture = web3Auth.login( LoginParams( Provider.JWT, @@ -367,7 +367,7 @@ val loginCompletableFuture = web3Auth.login( ```kotlin -// Simple social login (PnP mode) +// Simple social sign-in (PnP mode) val loginCompletableFuture = web3Auth.connectTo( LoginParams(AuthConnection.GOOGLE) ) @@ -380,7 +380,7 @@ val loginCompletableFuture = web3Auth.connectTo( ) ) -// JWT login (SFA mode) +// JWT sign-in (SFA mode) val loginCompletableFuture = web3Auth.connectTo( LoginParams( AuthConnection.CUSTOM, @@ -400,7 +400,7 @@ val loginCompletableFuture = web3Auth.connectTo( | `getPrivKey()` | `getPrivateKey()` | | `getEd25519PrivKey()` | `getEd25519PrivateKey()` | -#### Wallet services +#### Wallet Services ``` -### 4. Triggering login exceptions +### 4. Triggering sign-in exceptions :::note -The Android SDK uses the custom tabs and from current implementation of Chrome custom tab, it's not possible to add a listener directly to Chrome custom tab close button and trigger login exceptions. +The Android SDK uses the custom tabs and from current implementation of Chrome custom tab, it's not possible to add a listener directly to Chrome custom tab close button and trigger sign-in exceptions. ::: -Apply the `setCustomTabsClosed` method in your login screen to trigger login exceptions for Android. +Apply the `setCustomTabsClosed` method in your sign-in screen to trigger sign-in exceptions for Android. ```kotlin class MainActivity : AppCompatActivity() { @@ -173,7 +173,7 @@ web3Auth.setResultUrl(intent?.data) ### 2. Set result URL -Whenever user initiates a login flow, a new intent of CustomTabs is launched. It's necessary step to use `setResultUrl` in `onNewIntent` method to successful track the login process. +Whenever user initiates a sign-in flow, a new intent of CustomTabs is launched. It's necessary step to use `setResultUrl` in `onNewIntent` method to successful track the sign-in process. ```kotlin override fun onNewIntent(intent: Intent?) { @@ -288,10 +288,10 @@ val web3Auth = Web3Auth( ## Single Factor Auth (SFA) Support -Web3Auth Android SDK includes built-in support for Single Factor Auth (SFA), allowing for seamless authentication when you already have a JWT token from your authentication system. When MFA is disabled, users won't even notice Web3Auth's presence - they'll be automatically authenticated using just your JWT token, making the login experience completely frictionless. +Web3Auth Android SDK includes built-in support for Single Factor Auth (SFA), allowing for seamless authentication when you already have a JWT token from your authentication system. When MFA is disabled, users won't even notice Web3Auth's presence; they'll be automatically authenticated using just your JWT token, making the sign-in experience frictionless. ```kotlin -// SFA login with custom JWT +// SFA sign-in with custom JWT val loginCompletableFuture = web3Auth.connectTo( LoginParams( AuthConnection.CUSTOM, @@ -301,7 +301,7 @@ val loginCompletableFuture = web3Auth.connectTo( ) ``` -SFA mode is automatically activated when you provide an `idToken` parameter. This enables direct authentication without additional social login steps, perfect for applications that already have their own authentication system. +SFA mode is automatically activated when you provide an `idToken` parameter. This enables direct authentication without additional social sign-in steps, perfect for applications that already have their own authentication system. ## Blockchain Integration @@ -352,9 +352,9 @@ val ed25519PrivateKey = web3Auth.getEd25519PrivateKey() // Generate the Solana KeyPair val solanaKeyPair = Keypair.fromSecretKey(ed25519PrivateKey.hexToByteArray()) -// Get the user account -val userAccount = solanaKeyPair.publicKey.toBase58() +// Get the user's public key +val publicKey = solanaKeyPair.publicKey.toBase58() // Get the user balance -val userBalance = connection.getBalance(userAccount).toBigDecimal() +val userBalance = connection.getBalance(publicKey).toBigDecimal() ``` diff --git a/embedded-wallets/sdk/android/advanced/README.mdx b/embedded-wallets/sdk/android/advanced/README.mdx index fe46ce134da..8166706cc4e 100644 --- a/embedded-wallets/sdk/android/advanced/README.mdx +++ b/embedded-wallets/sdk/android/advanced/README.mdx @@ -54,7 +54,7 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. | `web3AuthNetwork` | Defines the Embedded Wallets Network. It's a mandatory field of type `Web3AuthNetwork`. | | `redirectUrl` | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type `String`. | | `sessionTime?` | Allows developers to configure the session management time. Session time is in seconds, default is `86400 * 30` (30 days). `sessionTime` can be max 30 days. | -| `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for wallet pregeneration and SFA mode. | +| `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for pre-generated wallets and SFA mode. | | `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. See [Chains configuration](#chains-configuration) below. | | `defaultChainId?` | Default chain ID to use. It's an optional field with a default value of `"0x1"` (Ethereum mainnet). The first chain from the project config will be used if the project has chains configured. | | `enableLogging?` | Setting to true will enable logs. It's an optional field with default value as `false`. | @@ -63,12 +63,12 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. -| Parameter | Description | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `whiteLabel?` | WhiteLabel options for web3auth. It helps you define custom UI, branding, and translations for your brand app. It takes `WhiteLabelData` as a value. | -| `authConnectionConfig?` | Auth connection config for the custom auth connections. It takes `List` as a value. | -| `mfaSettings?` | Allows developers to configure the MFA settings for authentication. It takes `MfaSettings` as a value. | -| `walletServicesConfig?` | Configuration for wallet services including whitelabel options. It takes `WalletServicesConfig` as a value. | +| Parameter | Description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `whiteLabel?` | Whitelabel options for Embedded Wallets. It helps you define custom UI, branding, and translations for your brand app. It takes `WhiteLabelData` as a value. | +| `authConnectionConfig?` | Auth connection config for the custom auth connections. It takes `List` as a value. | +| `mfaSettings?` | Allows developers to configure the MFA settings for authentication. It takes `MfaSettings` as a value. | +| `walletServicesConfig?` | Configuration for Wallet Services including whitelabel options. It takes `WalletServicesConfig` as a value. | @@ -101,7 +101,7 @@ Control how long users stay authenticated and how sessions persist. The session **Key Configuration Options:** -- `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to log in again. +- `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to sign in again. - Minimum: 1 second (`1`). - Maximum: 30 days (`86400 * 30`). - Default: 30 days (`86400 * 30`). @@ -120,21 +120,21 @@ var web3Auth = Web3Auth( ## Chains Configuration -The `chains` parameter lets you specify a custom blockchain network for the SDK. When set, this chain is used by wallet services (`showWalletUI`, `request`) in addition to any chains configured in the project dashboard. +The `chains` parameter lets you specify a custom blockchain network for the SDK. When set, this chain is used by Wallet Services (`showWalletUI`, `request`) in addition to any chains configured in the project dashboard. ### `Chains` Fields | Field | Type | Required | Description | | ------------------ | ---------------- | -------- | --------------------------------------------------------------------------------------------------- | -| `chainId` | `String` | Yes | Chain ID in hex format (e.g. `"0x1"` for Ethereum mainnet, `"0x89"` for Polygon). | +| `chainId` | `String` | Yes | Chain ID in hex format (for example, `"0x1"` for Ethereum mainnet, `"0x89"` for Polygon). | | `rpcTarget` | `String` | Yes | RPC endpoint URL for the chain. | | `chainNamespace` | `ChainNamespace` | No | Namespace of the chain. Accepts `ChainNamespace.EIP155`, `SOLANA`, or `OTHER`. Default is `EIP155`. | | `decimals` | `Int?` | No | Number of decimals for the native token. Default is `18`. | | `blockExplorerUrl` | `String?` | No | URL of the block explorer for this chain. | | `displayName` | `String?` | No | Human-readable name for the chain. | | `logo` | `String?` | No | URL of the chain's logo image. | -| `ticker` | `String?` | No | Ticker symbol for the native token (e.g. `"ETH"`). | -| `tickerName` | `String?` | No | Full name of the native token (e.g. `"Ethereum"`). | +| `ticker` | `String?` | No | Ticker symbol for the native token (for example, `"ETH"`). | +| `tickerName` | `String?` | No | Full name of the native token (for example, `"Ethereum"`). | ### Interface @@ -175,11 +175,11 @@ val web3Auth = Web3Auth( ## Custom authentication methods -Control the login options presented to your users. For detailed configuration options and implementation examples, see the [custom authentication](./custom-authentication.mdx) section. +Control the sign-in options presented to your users. For detailed configuration options and implementation examples, see the [custom authentication](./custom-authentication.mdx) section. ## UI customization -Customize the brand experience by customizing the Embedded Wallets login screens to match your application's design. For complete customization options, refer to the [Whitelabeling & UI Customization](./whitelabel.mdx) section. +Customize the brand experience by customizing the Embedded Wallets sign-in screens to match your application's design. For complete customization options, refer to the [Whitelabeling & UI Customization](./whitelabel.mdx) section. ## Multi-Factor Authentication @@ -197,7 +197,7 @@ The `walletServicesConfig` parameter in `Web3AuthOptions` allows you to customiz | Parameter | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy` enum. Default is `ConfirmationStrategy.DEFAULT`. | -| `whiteLabel?` | Whitelabel settings specific to the wallet services UI. When set, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as value. | +| `whiteLabel?` | Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as value. | ```kotlin val web3Auth = Web3Auth( diff --git a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx index 3759639e4fd..2ef75b07f1a 100644 --- a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx @@ -32,14 +32,12 @@ Learn more about the [auth provider setup](/embedded-wallets/authentication) and ## Configuration -To use custom authentication (Using Social providers or Login providers like Auth0, AWS Cognito, Firebase etc. or even your own custom JWT login) you can add the configuration using `authConnectionConfig` parameter during the initialization. +To use custom authentication (using social providers or sign-in providers like Auth0, AWS identity services, Firebase, and so on, or even your own custom JWT sign-in) you can add the configuration using `authConnectionConfig` parameter during the initialization. **"Auth Connection"** is called **"Verifier"** in the Android SDK. It is the older terminology which we will be updating in the upcoming releases. Consequentially, you will see the terms **"Verifier ID"** and **"Aggregate Verifier"** used in the codebase and documentation referring to **"Auth Connection ID"** and **"Grouped Auth Connection"** respectively. -::: - The `authConnectionConfig` parameter is a list of `AuthConnectionConfig` instances, each defining a specific authentication connection. After creating the auth connection from the [Web3Auth Dashboard](https://dashboard.web3auth.io), you can use the following parameters in the `AuthConnectionConfig`. @@ -54,21 +52,21 @@ After creating the auth connection from the [Web3Auth Dashboard](https://dashboa -| Parameter | Description | -| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `authConnectionId` | The name of the auth connection that you have registered on the Web3Auth Dashboard. It's a mandatory field, and accepts `String` as a value. | -| `authConnection` | Type of login of this auth connection, this value will affect the login flow that is adapted. For example, if you choose `google`, a Google sign-in flow will be used. If you choose `custom`, you should be providing your own JWT token, no sign-in flow will be presented. It's a mandatory field, and accepts `AuthConnection` as a value. | -| `clientId` | Client id provided by your login provider used for custom auth connection. e.g. Google's Client ID or Web3Auth's client Id if using 'custom' as AuthConnection. It's a mandatory field, and accepts `String` as a value. | -| `name?` | Display name for the auth connection. If null, the default name is used. It accepts `String` as a value. | -| `description?` | Description for the button. If provided, it renders as a full length button. else, icon button. It accepts `String` as a value. | -| `groupedAuthConnectionId?` | The field in JWT token which maps to grouped auth connection id. Please make sure you selected correct JWT auth connection id in the developer dashboard. It accepts `String` as a value. | -| `logoHover?` | Logo to be shown on mouse hover. It accepts `String` as a value. | -| `logoLight?` | Light logo for dark background. It accepts `String` as a value. | -| `logoDark?` | Dark logo for light background. It accepts `String` as a value. | -| `mainOption?` | Show login button on the main list. It accepts `Boolean` as a value. Default value is false. | -| `showOnModal?` | Whether to show the login button on modal or not. Default value is true. | -| `showOnDesktop?` | Whether to show the login button on desktop. Default value is true. | -| `showOnMobile?` | Whether to show the login button on mobile. Default value is true. | +| Parameter | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `authConnectionId` | The name of the auth connection that you have registered on the Web3Auth Dashboard. It's a mandatory field, and accepts `String` as a value. | +| `authConnection` | Type of sign-in for this auth connection; this value affects the sign-in flow that is used. For example, if you choose the Google auth connection, a Google sign-in flow will be used. If you choose `custom`, you should be providing your own JWT token, and no sign-in flow will be presented. It's a mandatory field, and accepts `AuthConnection` as a value. | +| `clientId` | Client id provided by your sign-in provider used for custom auth connection. For example, Google's Client ID or Web3Auth's client Id if using `custom` as AuthConnection. It's a mandatory field, and accepts `String` as a value. | +| `name?` | Display name for the auth connection. If null, the default name is used. It accepts `String` as a value. | +| `description?` | Description for the button. If provided, it renders as a full length button. else, icon button. It accepts `String` as a value. | +| `groupedAuthConnectionId?` | The field in JWT token which maps to the grouped Auth Connection ID. Please make sure you selected the correct JWT Auth Connection ID in the developer dashboard. It accepts `String` as a value. | +| `logoHover?` | Logo to be shown on mouse hover. It accepts `String` as a value. | +| `logoLight?` | Light logo for dark background. It accepts `String` as a value. | +| `logoDark?` | Dark logo for light background. It accepts `String` as a value. | +| `mainOption?` | Show sign-in button on the main list. It accepts `Boolean` as a value. Default value is false. | +| `showOnModal?` | Whether to show the sign-in button on modal or not. Default value is true. | +| `showOnDesktop?` | Whether to show the sign-in button on desktop. Default value is true. | +| `showOnMobile?` | Whether to show the sign-in button on mobile. Default value is true. | @@ -134,6 +132,8 @@ enum class AuthConnection { ### Usage + + = web3Auth.conne -## Configure extra login options + -Additional to the `LoginConfig` you can pass extra options to the `login` function to configure the login flow for cases requiring additional info for enabling login. The `ExtraLoginOptions` accepts the following parameters. +## Configure extra sign-in options + +Additional to the `LoginConfig` you can pass extra options to the `connectTo` method to configure the sign-in flow for cases requiring additional info for enabling sign-in. The `ExtraLoginOptions` accepts the following parameters. ### Parameters @@ -294,30 +296,30 @@ Additional to the `LoginConfig` you can pass extra options to the `login` functi -| Parameter | Description | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `additionalParams?` | Additional params in `HashMap` format for OAuth login, use id_token(JWT) to authenticate with web3auth. | -| `domain?` | Your custom authentication domain in `String` format. For example, if you are using Auth0, it can be example.au.auth0.com. | -| `client_id?` | Client id in `String` format, provided by your login provider used for custom verifier. | -| `leeway?` | The value used to account for clock skew in JWT expirations. The value is in the seconds, and ideally should no more than 60 seconds or 120 seconds at max. It takes `String` as a value. | -| `userIdField?` | The field in JWT token which maps to user id. Please make sure you selected correct JWT user id in the developer dashboard. It takes `String` as a value. | -| `isUserIdCaseSensitive?` | Boolean to confirm Whether the user id field is case sensitive or not. | -| `display?` | Allows developers the configure the display of UI. It takes `Display` as a value. | -| `prompt?` | Prompt shown to the user during authentication process. It takes `Prompt` as a value. | -| `max_age?` | Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It takes `String` as a value. | -| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | -| `id_token_hint?` | It denotes the previously issued ID token. It takes `String` as a value. | -| `id_token?` | JWT (ID Token) to be passed for login. | -| `access_token?` | Access token for OAuth flows. It takes `String` as a value. | -| `flow_type?` | Specifies the email passwordless flow type. It takes `EmailFlowType` as a value (`CODE` or `LINK`). | -| `acr_values?` | acc_values | -| `scope?` | The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It takes `String` as a value. | -| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It takes `String` as a value. | -| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget. It takes `String` as a value. | -| `state?` | state | -| `response_type?` | Defines which grant to execute for the authorization server. It takes `String` as a value. | -| `nonce?` | nonce | -| `redirect_uri?` | It can be used to specify the default url, where your custom jwt verifier can redirect your browser to with the result. If you are using Auth0, it must be whitelisted in the Allowed Callback URLs in your Auth0's application. | +| Parameter | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `additionalParams?` | Additional params in `HashMap` format for OAuth sign-in, use id_token(JWT) to authenticate with web3auth. | +| `domain?` | Your custom authentication domain in `String` format. For example, if you are using Auth0, it can be example.au.auth0.com. | +| `client_id?` | Client id in `String` format, provided by your sign-in provider used for custom verifier. | +| `leeway?` | The value used to account for clock skew in JWT expiration times. The value is in seconds, and ideally should be no more than 60 seconds or 120 seconds at max. It takes `String` as a value. | +| `userIdField?` | The field in JWT token which maps to user id. Please make sure you selected correct JWT user id in the developer dashboard. It takes `String` as a value. | +| `isUserIdCaseSensitive?` | Boolean to confirm Whether the user id field is case sensitive or not. | +| `display?` | Allows developers the configure the display of UI. It takes `Display` as a value. | +| `prompt?` | Prompt shown to the user during authentication process. It takes `Prompt` as a value. | +| `max_age?` | Max time allowed without re-authentication. If the last time the user authenticated is greater than this value, then the user must re-authenticate. It takes `String` as a value. | +| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | +| `id_token_hint?` | It denotes the previously issued ID token. It takes `String` as a value. | +| `id_token?` | JWT (ID Token) to be passed for sign-in. | +| `access_token?` | Access token for OAuth flows. It takes `String` as a value. | +| `flow_type?` | Specifies the email passwordless flow type. It takes `EmailFlowType` as a value (`CODE` or `LINK`). | +| `acr_values?` | Authentication Context Class Reference values for the authorization request. | +| `scope?` | The default scope to be used on authentication requests. The default scope defined in the Auth0 client is included along with this scope. It takes `String` as a value. | +| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It takes `String` as a value. | +| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 sign-in page and show the Auth0 sign-in widget. It takes `String` as a value. | +| `state?` | state | +| `response_type?` | Defines which grant to execute for the authorization server. It takes `String` as a value. | +| `nonce?` | nonce | +| `redirect_uri?` | It can be used to specify the default URL, where your custom jwt verifier can redirect your browser to with the result. If you are using Auth0, it must be allowlisted in the Allowed Callback URLs in your Auth0 application. | @@ -362,11 +364,13 @@ enum class EmailFlowType { ### Single verifier Usage + + -Auth0 has a special login flow, called the SPA flow. This flow requires a `client_id` and `domain` to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these configurations in the `ExtraLoginOptions` object in the login function. +Auth0 has a special sign-in flow, called the SPA flow. This flow requires a `client_id` and `domain` to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these configurations in the `ExtraLoginOptions` object in the `connectTo` method. ```kotlin import com.web3auth.core.Web3Auth @@ -412,9 +416,9 @@ val loginCompletableFuture: CompletableFuture = web3Auth.conne - -If you're using any other provider like Firebase/ AWS Cognito or deploying your own Custom JWT -server, you need to put the jwt token into the `idToken` field of the `LoginParams`. For SFA (Single Factor Auth) mode, this enables direct authentication without additional login flows. + +If you're using any other provider like Firebase, AWS identity services, or deploying your own custom JWT +server, you need to put the jwt token into the `idToken` field of the `LoginParams`. For SFA (Single Factor Auth) mode, this enables direct authentication without additional sign-in flows. ```kotlin import com.web3auth.core.Web3Auth @@ -450,8 +454,8 @@ val loginCompletableFuture: CompletableFuture = web3Auth.conne -To use the Email Passwordless login, you need to put the email into the `loginHint` parameter of -the `LoginParams`. By default, the login flow will be `code` flow, if you want to use the +To use the Email Passwordless sign-in, you need to put the email into the `loginHint` parameter of +the `LoginParams`. By default, the sign-in flow will be `code` flow, if you want to use the `link` flow, you need to put `flow_type` into the `extraLoginOptions` parameter. ```kotlin @@ -485,9 +489,9 @@ val loginCompletableFuture: CompletableFuture = web3Auth.conne -To use the SMS Passwordless login, send the phone number as the `loginHint` parameter of the +To use the SMS Passwordless sign-in, send the phone number as the `loginHint` parameter of the `LoginParams`. Please make sure the phone number is in the format of -+\{country_code}-\{phone_number}, i.e. (+91-09xx901xx1). ++\{country_code}-\{phone_number}, that is, (+91-09xx901xx1). ```kotlin import com.web3auth.core.Web3Auth @@ -517,9 +521,11 @@ val loginCompletableFuture: CompletableFuture = web3Auth.conne + + ### Grouped Auth Connection Usage -You can use grouped auth connections to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and Email Passwordless login, or Google and GitHub via Auth0 to access the same address for your user. +You can use grouped auth connections to combine multiple sign-in methods to get the same address for the users regardless of their sign-in providers. For example, combining a Google and Email Passwordless sign-in, or Google and GitHub via Auth0 to access the same address for your user. ```kotlin import com.web3auth.core.Web3Auth diff --git a/embedded-wallets/sdk/android/advanced/dapp-share.mdx b/embedded-wallets/sdk/android/advanced/dapp-share.mdx index d9c077d7235..a5a006bc99a 100644 --- a/embedded-wallets/sdk/android/advanced/dapp-share.mdx +++ b/embedded-wallets/sdk/android/advanced/dapp-share.mdx @@ -6,9 +6,9 @@ description: 'Web3Auth Android SDK - dapp share | Embedded Wallets' ## Embedded Wallets infrastructure at a glance -As described in the [Embedded Wallets infrastructure](/embedded-wallets/infrastructure/), to enable the non custodiality of Embedded Wallets, we split the private key into multiple parts, that is, into `shares`. These shares are a part of the offchain multisig, where multiple shares are stored in different places and can be used to reconstruct the private key dynamically in the user's frontend application. Typically, there are 3 shares: +As described in the [Embedded Wallets infrastructure](/embedded-wallets/infrastructure/), to enable non-custodial key management in Embedded Wallets, we split the private key into multiple parts, that is, into `shares`. These shares are a part of the offchain multisig, where multiple shares are stored in different places and can be used to reconstruct the private key dynamically in the user's frontend application. Typically, there are 3 shares: -1. **`ShareA` is managed by a login service via node operators:** This share is further split amongst a network of nodes and retrieved via conventional authentication flows. +1. **`ShareA` is managed by a sign-in service via node operators:** This share is further split amongst a network of nodes and retrieved via conventional authentication flows. 2. **`ShareB` is stored on the user's device:** Implementation is device and system specific. For example, on mobile devices, the share could be stored in device storage secured via biometrics. 3. **`ShareC` is a recovery share:** An extra share to be kept by the user, possibly kept on a separate device, downloaded or based on user input with enough entropy (such as, password, security questions, hardware device). @@ -16,15 +16,15 @@ Similar to existing 2FA systems, a user needs to prove ownership of at least 2 o ## The user experience in mobile platforms -The user experience on mobile platforms is very different from the web platforms. This is because the user has to be redirected to a browser where they can login using their socials and then back to the app once they have been successfully authenticated. This user experience shifts the context between two applications, whereas, in the web platforms, the context remains within the browser only. +The user experience on mobile platforms differs significantly from the web platforms. This is because the user has to be redirected to a browser where they can sign in using their social accounts and then return to the app once they have been successfully authenticated. This user experience shifts the context between two applications, whereas, in the web platforms, the context remains within the browser only. -For the dapp share login flow, we need to reconstruct the Shares `A` and `B`. `Share B` is managed by the login service and is provided on successful authentication. Whereas in web platforms, `Share A` is stored in the browser context. We can still store it in the browser context for mobile devices, but this has a few risks like users accidentally deleting browser data. This is a bigger problem in mobile devices since the user doesn't realize that the browser is being used to login within the app and clearing the browser data can cause their logins to fail. Hence, to tackle this issue, Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after successful login by the user. +For the dapp share sign-in flow, we need to reconstruct the Shares `A` and `B`. `Share B` is managed by the sign-in service and is provided on successful authentication. Whereas in web platforms, `Share A` is stored in the browser context. We can still store it in the browser context for mobile devices, but this has a few risks like users deleting browser data by mistake. This is a bigger problem in mobile devices since the user doesn't realize that the browser is being used to sign in within the app and clearing the browser data can cause sign-in to fail. Hence, to tackle this issue, Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after the user signs in successfully. ## Dapp share in Android -Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after successful login by the user. +Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after the user signs in successfully. -After a successful login from a user, the user details are returned as a response to the application in mobile devices. +After a successful sign-in from a user, the user details are returned as a response to the application in mobile devices. #### Sample response in Android @@ -38,22 +38,22 @@ After a successful login from a user, the user details are returned as a respons "userId": "w3a-heroes@web3auth.com", "authConnection": "google", "groupedAuthConnectionId": "w3a-google-sapphire", - "dappShare": "", // 24 words of seed phrase will be sent only incase of custom auth connections + "dappShare": "", // 24 words of seed phrase will be sent only in case of custom auth connections "idToken": "", - "oAuthIdToken": "", // will be sent only incase of custom auth connections - "oAuthAccessToken": "", // will be sent only incase of custom auth connections + "oAuthIdToken": "", // will be sent only in case of custom auth connections + "oAuthAccessToken": "", // will be sent only in case of custom auth connections "isMfaEnabled": false // Returns whether the user has enabled MFA or not } } ``` -If you notice, the reponses has a field called `dappShare` which is a 24 words seed phrase that can be used to reconstruct the private key. This dappShare is a suplement to the `Share A` and represents half of the private key. The application can store the dapp share in their own application local storage safely. +If you notice, the responses have a field called `dappShare` which is a 24 words seed phrase that can be used to reconstruct the private key. This dapp share is a supplement to the `Share A` and represents half of the private key. The application can store the dapp share in their own application local storage. -Now, while logging in, the user can use their social accounts to obtain one share, and the application provides the dapp share, removing the need to store the share in the browser context and enabling user to sign in without repeating the full flow. This can be done by passing over the stored dapp share value in the login function. +Now, while signing in, the user can use their social accounts to obtain one share, and the application provides the dapp share, removing the need to store the share in the browser context and enabling user to sign in without repeating the full flow. This can be done by passing over the stored dapp share value in the `connectTo` method. :::note -One major thing to note here is that the `dappShare` is only available for custom auth connections and not the standard web3auth auth connections. This is done to make sure that an application only has access to the corresponding share to the private key of their application's user. Hence, to use dApp Share, one has to use the custom authentication feature of Web3Auth. Also, the dApp Share is only returned to users who have enabled 2FA to their account. +One major thing to note here is that the `dappShare` is only available for custom auth connections and not the standard Web3Auth auth connections. This is done to make sure that an application only has access to the corresponding share to the private key of their application's user. Hence, to use dapp share, one has to use the custom authentication feature of Web3Auth. Also, the dapp share is only returned to users who have enabled 2FA to their account. ::: diff --git a/embedded-wallets/sdk/android/advanced/mfa.mdx b/embedded-wallets/sdk/android/advanced/mfa.mdx index ba4a7291363..8cb18d8fbf3 100644 --- a/embedded-wallets/sdk/android/advanced/mfa.mdx +++ b/embedded-wallets/sdk/android/advanced/mfa.mdx @@ -18,7 +18,7 @@ These backup factors simplify the user experience when recovering their account ## Enable using the multi-factor authentication level -For a dapp, we provide various options to set up MFA. You can customize the MFA screen by passing the `mfaLevel` parameter in `login` method. You can enable or disable a backup factor and change their order. Currently, there are four values for MFA level. +For a dapp, we provide various options to set up MFA. You can customize the MFA screen by passing the `mfaLevel` parameter in the `connectTo` method. You can enable or disable a backup factor and change their order. Currently, there are four values for MFA level. :::caution Note @@ -28,12 +28,12 @@ If you are using default verifiers, your users may have set up MFA on other dapp ### Multi-factor authentication level options -| MFA Level | Description | -| --------- | ---------------------------------------------------------- | -| DEFAULT | Shows the MFA screen every third login. | -| OPTIONAL | Shows the MFA screen on every login, but user can skip it. | -| MANDATORY | Makes it mandatory to set up MFA after first login. | -| NONE | Skips the MFA setup screen. | +| MFA Level | Description | +| --------- | ------------------------------------------------------------ | +| DEFAULT | Shows the MFA screen every third sign-in. | +| OPTIONAL | Shows the MFA screen on every sign-in, but user can skip it. | +| MANDATORY | Makes it mandatory to set up MFA after first sign-in. | +| NONE | Skips the MFA setup screen. | ### Usage @@ -49,7 +49,7 @@ val loginResponse = web3Auth.connectTo( ## Explicitly enable multi-factor authentication -The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will used during custom verifiers. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT verifiers, you need to pass the JWT token in `loginParams` as well. +The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will used during custom verifiers. If you are using default sign-in providers, you don't need to pass `LoginParams`. If you are using custom JWT verifiers, you need to pass the JWT token in `loginParams` as well. -| Parameter | Description | -| ---------------------- | ------------------------------------------------------------------------ | -| `deviceShareFactor?` | MFA setting for deviceShareFactor. It accepts `MfaSetting` as a value. | -| `backUpShareFactor?` | MFA setting for backUpShareFactor. It accepts `MfaSetting` as a value. | -| `socialBackupFactor?` | MFA setting for socialBackupFactor. It accepts `MfaSetting` as a value. | -| `passwordFactor?` | MFA setting for passwordFactor. It accepts `MfaSetting` as a value. | -| `passkeysFactor?` | MFA setting for passkeysFactor. It accepts `MfaSetting` as a value. | -| `authenticatorFactor?` | MFA setting for authenticatorFactor. It accepts `MfaSetting` as a value. | +| Parameter | Description | +| ---------------------- | ----------------------------------------------------------------------------- | +| `deviceShareFactor?` | MFA setting for deviceShareFactor. It accepts `MfaSetting` as a value. | +| `backUpShareFactor?` | MFA setting for backUpShareFactor. It accepts `MfaSetting` as a value. | +| `socialBackupFactor?` | MFA setting for socialBackupFactor. It accepts `MfaSetting` as a value. | +| `passwordFactor?` | MFA setting for the password factor. It accepts `MfaSetting` as a value. | +| `passkeysFactor?` | MFA setting for the passkeys factor. It accepts `MfaSetting` as a value. | +| `authenticatorFactor?` | MFA setting for the authenticator factor. It accepts `MfaSetting` as a value. | diff --git a/embedded-wallets/sdk/android/advanced/smart-accounts.mdx b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx index 002c7556fbd..fee5e58037a 100644 --- a/embedded-wallets/sdk/android/advanced/smart-accounts.mdx +++ b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx @@ -24,7 +24,7 @@ You can customize the wallet UI behavior for smart account flows using `walletSe | Parameter | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirmationStrategy?` | Controls how transaction confirmations are presented. Accepts `ConfirmationStrategy` as a value. Default is `ConfirmationStrategy.DEFAULT`. | -| `whiteLabel?` | Optional whitelabel configuration to apply specifically to the wallet services UI. Accepts `WhiteLabelData` as a value. When set, it is merged with the project-level whitelabel config. | +| `whiteLabel?` | Optional whitelabel configuration to apply specifically to the Wallet Services UI. Accepts `WhiteLabelData` as a value. When set, it is merged with the project-level whitelabel config. | ### `ConfirmationStrategy` diff --git a/embedded-wallets/sdk/android/advanced/whitelabel.mdx b/embedded-wallets/sdk/android/advanced/whitelabel.mdx index cf691b544f3..d821f25e3dd 100644 --- a/embedded-wallets/sdk/android/advanced/whitelabel.mdx +++ b/embedded-wallets/sdk/android/advanced/whitelabel.mdx @@ -20,7 +20,7 @@ Embedded Wallets supports whitelabeling with application branding for a consiste -## Customizing the Web3Auth login screens +## Customizing the Web3Auth sign-in screens For defining custom UI, branding, and translations for your brand during Embedded Wallets instantiation, you just need to specify an additional parameter within the `Web3AuthOptions` object called `whiteLabel`. This parameter takes object called `WhiteLabelData`. @@ -39,12 +39,12 @@ For defining custom UI, branding, and translations for your brand during Embedde | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appName?` | Display name for the app in the UI. | -| `logoLight?` | App logo to be used in dark mode. It accepts url in `String` as a value. | -| `logoDark?` | App logo to be used in light mode. It accepts url in `String` as a value. | +| `logoLight?` | App logo to be used in dark mode. It accepts a URL in `String` as a value. | +| `logoDark?` | App logo to be used in light mode. It accepts a URL in `String` as a value. | | `defaultLanguage?` | Language which will be used by Web3Auth, app will use browser language if not specified. Default language is `Language.EN`. Checkout `Language` for supported languages. | -| `mode?` | Theme mode for the login modal. Choose between `ThemeModes.AUTO`, `ThemeModes.LIGHT` or `ThemeModes.DARK` background modes. Default value is `ThemeModes.AUTO`. | -| `theme?` | Used to customize the theme of the login modal. It accepts `HashMap` as a value. | -| `appUrl?` | Url to be used in the Modal. It accepts url in `String` as a value. | +| `mode?` | Theme mode for the sign-in modal. Choose between `ThemeModes.AUTO`, `ThemeModes.LIGHT` or `ThemeModes.DARK` background modes. Default value is `ThemeModes.AUTO`. | +| `theme?` | Used to customize the theme of the sign-in modal. It accepts `HashMap` as a value. | +| `appUrl?` | URL to be used in the Modal. It accepts a URL in `String` as a value. | | `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are null, the default Web3Auth logo will be used for the loader. Default value is false. | diff --git a/embedded-wallets/sdk/android/usage/README.mdx b/embedded-wallets/sdk/android/usage/README.mdx index 254f3951914..7f5beadb093 100644 --- a/embedded-wallets/sdk/android/usage/README.mdx +++ b/embedded-wallets/sdk/android/usage/README.mdx @@ -4,7 +4,7 @@ sidebar_label: Overview description: 'Web3Auth Android SDK Functions | Embedded Wallets' --- -Embedded Wallets provides a comprehensive set of functions to handle authentication, user management, and blockchain interactions in your Android applications. These functions allow you to implement features like user login, Multi-Factor Authentication (MFA), private key retrieval, and Wallet Services with minimal effort. Each function is designed to handle a specific aspect of Embedded Wallets' functionality, making it easy to integrate into your Android projects. +Embedded Wallets provides a comprehensive set of functions to handle authentication, user management, and blockchain interactions in your Android applications. These functions allow you to implement features like user sign-in, Multi-Factor Authentication (MFA), private key retrieval, and Wallet Services with minimal effort. Each function is designed to handle a specific aspect of Embedded Wallets' functionality, making it easy to integrate into your Android projects. ## List of functions @@ -16,10 +16,10 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Authentication functions -| Function Name | Description | -| --------------------------------- | --------------------------------------------------------------------------------------------------- | -| [`connectTo()`](./connect-to.mdx) | Logs in the user with the selected auth connection. Supports both PnP and SFA authentication modes. | -| [`logout()`](./logout.mdx) | Logs out the user from the current session. | +| Function Name | Description | +| --------------------------------- | ---------------------------------------------------------------------------------------------------- | +| [`connectTo()`](./connect-to.mdx) | Signs in the user with the selected auth connection. Supports both PnP and SFA authentication modes. | +| [`logout()`](./logout.mdx) | Signs out the user from the current session. | ### User management functions @@ -44,10 +44,10 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Wallet Services functions -| Function Name | Description | -| ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | -| [`showWalletUI()`](./launch-wallet-services.mdx) | Launches the templated wallet UI in WebView with automatic chain configuration from dashboard. | -| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions with simplified parameters. | +| Function Name | Description | +| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | +| [`showWalletUI()`](./launch-wallet-services.mdx) | Launches the prebuilt Wallet Services UI in WebView with automatic chain configuration from dashboard. | +| [`request()`](./request.mdx) | Opens prebuilt transaction screens for signing EVM transactions with simplified parameters. | ## `getWeb3AuthResponse()` @@ -63,4 +63,4 @@ val response = web3Auth.getWeb3AuthResponse() ::: -For most use cases, prefer the typed accessors (`getPrivateKey()`, `getEd25519PrivateKey()`, `getUserInfo()`) which provide a more ergonomic API with clear error messages. +For most use cases, prefer the typed methods (`getPrivateKey()`, `getEd25519PrivateKey()`, `getUserInfo()`) which provide a more ergonomic API with clear error messages. diff --git a/embedded-wallets/sdk/android/usage/connect-to.mdx b/embedded-wallets/sdk/android/usage/connect-to.mdx index 69f3f95a6d8..0892109e6d6 100644 --- a/embedded-wallets/sdk/android/usage/connect-to.mdx +++ b/embedded-wallets/sdk/android/usage/connect-to.mdx @@ -1,5 +1,5 @@ --- -title: Logging in a user +title: Sign in a user sidebar_label: Sign in a user description: 'Web3Auth Android SDK - connectTo Function | Embedded Wallets' --- @@ -8,8 +8,8 @@ import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' To sign in a user, use the `connectTo` method. -It triggers the login flow and opens a browser modal where the user can authenticate. -Pass supported auth connections to `connectTo` for specific social logins such as GOOGLE, APPLE, and FACEBOOK, or use whitelabel login. +It triggers the sign-in flow and opens a browser modal where the user can authenticate. +Pass supported auth connections to `connectTo` for specific social sign-in providers such as GOOGLE, APPLE, and FACEBOOK, or use whitelabel sign-in. ## Parameters @@ -25,19 +25,19 @@ The `connectTo` method takes `LoginParams` as a required input. -| Parameter | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `authConnection` | It sets the OAuth login method to be used. You can use any of the supported values are `GOOGLE`, `FACEBOOK`, `REDDIT`, `DISCORD`, `TWITCH`, `APPLE`, `LINE`, `GITHUB`, `KAKAO`, `LINKEDIN`, `TWITTER`, `WEIBO`, `WECHAT`, `EMAIL_PASSWORDLESS`, `CUSTOM`, `SMS_PASSWORDLESS`, and `FARCASTER`. | -| `authConnectionId?` | The connection ID for custom authentication. This is optional for social logins but required for custom JWT-based authentication. | -| `groupedAuthConnectionId?` | Used for aggregate verifiers. When multiple auth connections are grouped under a single verifier, this specifies the aggregate verifier ID. | -| `loginHint?` | Provides a hint for the login process. For email passwordless, this should be the email address. For SMS passwordless, this should be the phone number. | -| `idToken?` | JWT token for SFA (Single Factor Auth) login. When provided, the login will use SFA mode. | -| `extraLoginOptions?` | It can be used to set the OAuth login options for corresponding `authConnection`. Default value for the field is `null`, and it accepts `ExtraLoginOptions` as a value. | -| `appState?` | It can be used to keep track of the app state when user will be redirected to app after login. Default is `null`, and accepts `String` as a value. | -| `mfaLevel?` | Customize the MFA screen shown to the user during OAuth authentication. Default value for field is `MFALevel.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | -| `dappShare?` | Custom verifier logins can get a dapp share returned to them post successful login. This is useful if the dapps want to use this share to allow users to login seamlessly. It accepts `String` as a value. | -| `curve?` | It will be used to determine the public key encoded in the jwt token which returned in `getUserInfo` function after user login. This parameter won't change format of private key returned by Web3Auth. Private key returned by `getPrivateKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivateKey` method. The default value is `Curve.SECP256K1`. | -| `dappUrl?` | URL of the dapp. This is used for analytics and debugging purposes. | +| Parameter | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `authConnection` | It sets the OAuth sign-in method to be used. You can use any of the supported values are `GOOGLE`, `FACEBOOK`, `REDDIT`, `DISCORD`, `TWITCH`, `APPLE`, `LINE`, `GITHUB`, `KAKAO`, `LINKEDIN`, `TWITTER`, `WEIBO`, `WECHAT`, `EMAIL_PASSWORDLESS`, `CUSTOM`, `SMS_PASSWORDLESS`, and `FARCASTER`. | +| `authConnectionId?` | The connection ID for custom authentication. This is optional for social sign-in providers but required for custom JWT-based authentication. | +| `groupedAuthConnectionId?` | Used for aggregate verifiers. When multiple auth connections are grouped under a single verifier, this specifies the aggregate verifier ID. | +| `loginHint?` | Provides a hint for the sign-in process. For email passwordless, this should be the email address. For SMS passwordless, this should be the phone number. | +| `idToken?` | JWT token for SFA (Single Factor Auth) sign-in. When provided, sign-in uses SFA mode. | +| `extraLoginOptions?` | It can be used to set the OAuth sign-in options for corresponding `authConnection`. Default value for the field is `null`, and it accepts `ExtraLoginOptions` as a value. | +| `appState?` | It can be used to keep track of the app state when user will be redirected to app after sign-in. Default is `null`, and accepts `String` as a value. | +| `mfaLevel?` | Customize the MFA screen shown to the user during OAuth authentication. Default value for field is `MFALevel.DEFAULT`, which shows MFA screen every third sign-in. It accepts `MFALevel` as a value. | +| `dappShare?` | Custom verifier sign-in can return a dapp share after successful authentication. This is useful if the dapps want to use this share to allow users to sign in seamlessly. It accepts `String` as a value. | +| `curve?` | It will be used to determine the public key encoded in the jwt token which returned in `getUserInfo` function after the user signs in. This parameter won't change format of private key returned by Web3Auth. Private key returned by `getPrivateKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivateKey` method. The default value is `Curve.SECP256K1`. | +| `dappUrl?` | URL of the dapp. This is used for analytics and debugging purposes. | @@ -103,19 +103,19 @@ enum class AuthConnection { `connectTo` returns a `CompletableFuture`. The response contains: -| Field | Type | Description | -| ----------------------- | --------------- | ------------------------------------------------------------------------------------------- | -| `privateKey` | `String?` | secp256k1 private key (EVM). Use `getPrivateKey()` for a safe accessor. | -| `ed25519PrivKey` | `String?` | Ed25519 private key (Solana, Near, etc.). Use `getEd25519PrivateKey()` for a safe accessor. | -| `userInfo` | `UserInfo?` | User profile information. See [getUserInfo](../getUserInfo) for field details. | -| `coreKitKey` | `String?` | SFA key returned when `useSFAKey = true`. | -| `coreKitEd25519PrivKey` | `String?` | SFA Ed25519 key returned when `useSFAKey = true`. | -| `factorKey` | `String?` | Factor key for MFA flows. | -| `sessionId` | `String?` | Current session identifier. | -| `signatures` | `List?` | Session token signatures for advanced use cases. | -| `error` | `String?` | Non-null when the session returned an error. | +| Field | Type | Description | +| ----------------------- | --------------- | ------------------------------------------------------------------------------------------ | +| `privateKey` | `String?` | secp256k1 private key (EVM). Use `getPrivateKey()` for safe retrieval. | +| `ed25519PrivKey` | `String?` | Ed25519 private key (Solana, Near, etc.). Use `getEd25519PrivateKey()` for safe retrieval. | +| `userInfo` | `UserInfo?` | User profile information. See [getUserInfo](../get-user-info) for field details. | +| `coreKitKey` | `String?` | SFA key returned when `useSFAKey = true`. | +| `coreKitEd25519PrivKey` | `String?` | SFA Ed25519 key returned when `useSFAKey = true`. | +| `factorKey` | `String?` | Factor key for MFA flows. | +| `sessionId` | `String?` | Current session identifier. | +| `signatures` | `List?` | Session token signatures for advanced use cases. | +| `error` | `String?` | Non-null when the session returned an error. | -Prefer the typed accessors `getPrivateKey()` and `getEd25519PrivateKey()` over reading `privateKey` directly — they correctly handle the `useSFAKey` flag and throw `IllegalStateException` instead of returning null when no key is available. +Prefer the typed methods `getPrivateKey()` and `getEd25519PrivateKey()` over reading `privateKey` directly; they correctly handle the `useSFAKey` flag and throw `IllegalStateException` instead of returning null when no key is available. ## Usage @@ -142,6 +142,8 @@ val loginCompletableFuture: CompletableFuture = web3Auth.conne ## Examples + + = web3Auth.conne + + diff --git a/embedded-wallets/sdk/android/usage/enable-mfa.mdx b/embedded-wallets/sdk/android/usage/enable-mfa.mdx index 665e2b2ba70..0a691224848 100644 --- a/embedded-wallets/sdk/android/usage/enable-mfa.mdx +++ b/embedded-wallets/sdk/android/usage/enable-mfa.mdx @@ -7,7 +7,7 @@ description: 'Web3Auth Android SDK - enableMFA Function | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will used during custom verifiers. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT verifiers, you need to pass the JWT token in `loginParams` as well. +The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will used during custom verifiers. If you are using default sign-in providers, you don't need to pass `LoginParams`. If you are using custom JWT verifiers, you need to pass the JWT token in `loginParams` as well. ## Usage @@ -61,7 +61,7 @@ class MainActivity : AppCompatActivity() { :::warning -`enableMFA` does **not** accept an `idToken` in `LoginParams`. Passing `idToken` will cause the SDK to throw an `ENABLE_MFA_NOT_ALLOWED` error. For custom JWT verifiers, pass an empty `LoginParams` with the `authConnection` only — the SDK automatically uses the session's auth connection to re-authenticate. +`enableMFA` does **not** accept an `idToken` in `LoginParams`. Passing `idToken` will cause the SDK to throw an `ENABLE_MFA_NOT_ALLOWED` error. For custom JWT verifiers, pass an empty `LoginParams` with the `authConnection` only; the SDK automatically uses the session's auth connection to re-authenticate. ::: diff --git a/embedded-wallets/sdk/android/usage/get-user-info.mdx b/embedded-wallets/sdk/android/usage/get-user-info.mdx index 5d130ab330c..3a9ae569749 100644 --- a/embedded-wallets/sdk/android/usage/get-user-info.mdx +++ b/embedded-wallets/sdk/android/usage/get-user-info.mdx @@ -4,7 +4,7 @@ sidebar_label: Get user info description: 'Web3Auth Android SDK - getUserInfo Function | Embedded Wallets' --- -You can use the `getUserInfo` method to retrieve various details about the user, such as their login type, whether multi-factor authentication (MFA) is enabled, profile image, name, and other relevant information. +You can use the `getUserInfo` method to retrieve various details about the user, such as their sign-in method, whether multi-factor authentication (MFA) is enabled, profile image, name, and other relevant information. :::note @@ -20,20 +20,20 @@ val userInfo = web3Auth.getUserInfo() ## `UserInfo` Fields -| Field | Type | Description | -| ------------------------- | ---------- | ----------------------------------------------------------------------------------------------- | -| `email` | `String` | Email address of the user. Empty string if not available. | -| `name` | `String` | Display name of the user. Empty string if not available. | -| `profileImage` | `String` | URL of the user's profile image. Empty string if not available. | -| `authConnectionId` | `String` | The auth connection ID (verifier name) used to log in. | -| `groupedAuthConnectionId` | `String` | The grouped auth connection ID if aggregate verifiers are used. Empty string if not applicable. | -| `userId` | `String` | The user's unique ID within the auth connection (e.g. email for email-based, sub for OAuth). | -| `authConnection` | `String` | The auth connection type used (e.g. `"google"`, `"custom"`). | -| `dappShare` | `String` | DApp share for custom verifiers. Empty string for default verifiers. | -| `idToken` | `String` | JWT issued by Web3Auth after authentication. | -| `oAuthIdToken` | `String` | JWT issued by the OAuth provider. Only present for custom verifiers. | -| `oAuthAccessToken` | `String` | Access token issued by the OAuth provider. Only present for custom verifiers. | -| `isMfaEnabled` | `Boolean?` | Whether the user has MFA enabled. `null` if the information is not available in the session. | +| Field | Type | Description | +| ------------------------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| `email` | `String` | Email address of the user. Empty string if not available. | +| `name` | `String` | Display name of the user. Empty string if not available. | +| `profileImage` | `String` | URL of the user's profile image. Empty string if not available. | +| `authConnectionId` | `String` | The auth connection ID (verifier name) used to sign in. | +| `groupedAuthConnectionId` | `String` | The grouped auth connection ID if aggregate verifiers are used. Empty string if not applicable. | +| `userId` | `String` | The user's unique ID within the auth connection (for example, email for email-based, sub for OAuth). | +| `authConnection` | `String` | The auth connection type used (for example, `"google"`, `"custom"`). | +| `dappShare` | `String` | dapp share for custom verifiers. Empty string for default verifiers. | +| `idToken` | `String` | JWT issued by Web3Auth after authentication. | +| `oAuthIdToken` | `String` | JWT issued by the OAuth provider. Only present for custom verifiers. | +| `oAuthAccessToken` | `String` | Access token issued by the OAuth provider. Only present for custom verifiers. | +| `isMfaEnabled` | `Boolean?` | Whether the user has MFA enabled. `null` if the information is not available in the session. | ### Interface diff --git a/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx b/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx index 2c84778b752..d0e96328e48 100644 --- a/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx +++ b/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx @@ -7,7 +7,7 @@ description: 'Web3Auth Android SDK - showWalletUI Function | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The `showWalletUI` method launches a WebView which allows you to use the templated wallet UI services. +The `showWalletUI` method launches a WebView which allows you to use the prebuilt Wallet Services UI. The method automatically uses the chain configuration from your project settings and no longer requires a manual `ChainConfig` parameter. ### Supported features @@ -21,7 +21,7 @@ The method automatically uses the chain configuration from your project settings :::note Access to Wallet Services is gated. -You can use this feature in `sapphire_devnet` for free. +You can use this feature on `sapphire_devnet` without a paid plan. The minimum [pricing plan](https://web3auth.io/pricing.html) to use this feature in a production environment is the **Scale Plan**. ::: diff --git a/embedded-wallets/sdk/android/usage/manage-mfa.mdx b/embedded-wallets/sdk/android/usage/manage-mfa.mdx index 470f0003211..6f3fb827a60 100644 --- a/embedded-wallets/sdk/android/usage/manage-mfa.mdx +++ b/embedded-wallets/sdk/android/usage/manage-mfa.mdx @@ -7,7 +7,7 @@ description: 'Web3Auth Android SDK - manageMFA Function | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The `manageMFA` method is used to trigger manage MFA flow for users, allowing users to update their MFA settings. The method takes `LoginParams` which will used during custom verifiers. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT verifiers, you need to pass the JWT token in `loginParams` as well. +The `manageMFA` method is used to trigger manage MFA flow for users, allowing users to update their MFA settings. The method takes `LoginParams` which will used during custom verifiers. If you are using default sign-in providers, you don't need to pass `LoginParams`. If you are using custom JWT verifiers, you need to pass the JWT token in `loginParams` as well. ## Usage diff --git a/embedded-wallets/sdk/android/usage/request.mdx b/embedded-wallets/sdk/android/usage/request.mdx index 935d0e25909..423ef687eb0 100644 --- a/embedded-wallets/sdk/android/usage/request.mdx +++ b/embedded-wallets/sdk/android/usage/request.mdx @@ -4,7 +4,7 @@ sidebar_label: Send requests description: 'Web3Auth Android SDK - request Function | Embedded Wallets' --- -The `request` method facilitates the use of templated transaction screens for signing transactions. The method will return [SignResponse](#signresponse). It can be used to sign transactions for any EVM chain and screens can be whitelabeled to your branding. +The `request` method facilitates the use of prebuilt transaction screens for signing transactions. The method will return [SignResponse](#signresponse). It can be used to sign transactions for any EVM chain and screens can be customized to your branding. Please check the list of [JSON RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/), noting that the request method currently supports only the signing methods. @@ -20,7 +20,7 @@ Please check the list of [JSON RPC methods](https://docs.metamask.io/wallet/refe | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `method` | JSON RPC method name in `String`. Supports signing methods and smart account operations (see supported methods below). | | `requestParams` | Parameters for the corresponding method. The parameters should be in the list and correct sequence. Take a look at [RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/) to know more. | -| `path?` | The path where the signing service is located. Default value is `"wallet/request"`. This is an internal routing path for the wallet services infrastructure. | +| `path?` | The path where the signing service is located. Default value is `"wallet/request"`. This is an internal routing path for the Wallet Services infrastructure. | | `appState?` | It can be used to keep track of the app state. Default is `null`, and accepts `String` as a value. | :::warning diff --git a/src/utils/w3a-sdk-map.js b/src/utils/w3a-sdk-map.js index 81f3410abf7..3310cb8e17d 100644 --- a/src/utils/w3a-sdk-map.js +++ b/src/utils/w3a-sdk-map.js @@ -13,14 +13,14 @@ export const flutter = 'Flutter' export const unity = 'Unity' export const unreal = 'Unreal Engine' -export const pnpWebVersion = `11.0.x` -export const pnpAndroidVersion = `10.0.1` -export const pnpIOSVersion = `11.1.0` -export const pnpRNVersion = `8.1.x` -export const pnpNodeVersion = `5.0.x` -export const pnpFlutterVersion = `6.1.2` -export const pnpUnityVersion = `7.0.x` -export const pnpUnrealVersion = `4.1.x` +export const pnpWebVersion = `11` +export const pnpAndroidVersion = `10` +export const pnpIOSVersion = `11` +export const pnpRNVersion = `9` +export const pnpNodeVersion = `5` +export const pnpFlutterVersion = `6` +export const pnpUnityVersion = `7` +export const pnpUnrealVersion = `4` export function getPnPVersion(platform) { if (platform === web) {