diff --git a/embedded-wallets/authentication/custom-connections/auth0.mdx b/embedded-wallets/authentication/custom-connections/auth0.mdx index a1ee80fcd91..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', @@ -123,40 +123,39 @@ 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 web3Auth.setResultUrl(intent?.data) ``` -##### Logging in +##### Signing 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(...))` function to authenticate the user when they click the sign-in 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, + authConnection = AuthConnection.CUSTOM, + authConnectionId = "web3auth-auth0-demo", extraLoginOptions = ExtraLoginOptions( - domain = "https://YOUR_AUTH0_DOMAIN", - verifierIdField = "sub" + domain = "https://YOUR_AUTH0_DOMAIN" ) ) // focus-end @@ -164,13 +163,13 @@ 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 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 { @@ -208,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 55dcf953f66..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. @@ -116,29 +120,29 @@ 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 web3Auth.setResultUrl(intent?.data) ``` -##### Logging in +##### Signing 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(...))` function to authenticate the user when they click the sign-in button. ```kotlin private fun signIn() { @@ -155,17 +159,15 @@ private fun signIn() { val idToken = result.token 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( - 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) { @@ -187,13 +189,13 @@ 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 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 @@ -238,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/_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/_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/connect-blockchain/solana/android.mdx b/embedded-wallets/connect-blockchain/solana/android.mdx index d9ed0b3fbb7..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 @@ -131,42 +131,43 @@ 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 -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/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..d6a9ec73e4d 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`: @@ -145,13 +157,12 @@ 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) -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 sign-in +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 sign-in +val loginCompletableFuture = web3Auth.login( + LoginParams( + Provider.JWT, + extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token") + ) +) +``` + + + + + +```kotlin +// Simple social sign-in (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 sign-in (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 signed-in users | +| `launchWalletServices()` | v6 | Open the prebuilt Wallet Services UI (v10: `showWalletUI()`) | +| `request()` | v6.1 | Sign transactions with confirmation screens | +| SMS Passwordless sign-in | v7.2 | `AuthConnection.SMS_PASSWORDLESS` with `loginHint` | +| Farcaster sign-in | 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 2e16eaba064..11441a91cfa 100644 --- a/embedded-wallets/sdk/android/README.mdx +++ b/embedded-wallets/sdk/android/README.mdx @@ -9,11 +9,11 @@ import Tabs from '@theme/Tabs' ## Overview -MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play) provides authentication for Android applications with social logins, external wallets, and more. Our Android SDK, written in Kotlin, simplifies how you connect users to their preferred wallets and manage authentication state natively. +MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play) provides authentication for Android applications with social sign-in, external wallets, and more. Our Android SDK, written in Kotlin, simplifies how you connect users to their preferred wallets and manage authentication state natively. ## 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 @@ -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.1' } ``` @@ -69,7 +69,7 @@ Open your app's `AndroidManifest.xml` file and add the following permission. Ens 2.2 Configure `AndroidManifest.xml` File -Ensure your main activity `launchMode` is set to **singleTop** in your `AndroidManifest.xml`: +Ensure your main activity `launchMode` is set to `singleTop` in your `AndroidManifest.xml`: ```xml ``` -### 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() { @@ -154,15 +154,16 @@ 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", + ), + this ) // focus-end @@ -172,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?) { @@ -187,11 +188,17 @@ 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 -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. ::: @@ -200,7 +207,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 @@ -239,11 +246,11 @@ See the [advanced configuration sections](./advanced/) to learn more about each ```kotlin 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" - ) + ), + this ) ``` @@ -254,13 +261,12 @@ val web3Auth = Web3Auth( ```kotlin 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 - redirectUrl = "YOUR_APP_SCHEME://auth" - loginConfig = hashMapOf("google" to LoginConfigItem( - verifier = "verifier-name", // Get it from MetaMask Developer Dashboard - typeOfLogin = TypeOfLogin.GOOGLE, + clientId = "YOUR_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET + redirectUrl = "YOUR_APP_SCHEME://auth", + 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( @@ -271,7 +277,8 @@ val web3Auth = Web3Auth( passkeysFactor = MfaSetting(true, 5, true), authenticatorFactor = MfaSetting(true, 6, true), ) - ) + ), + this ) ``` @@ -279,13 +286,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 sign-in experience frictionless. + +```kotlin +// SFA sign-in 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 sign-in 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 +318,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 +338,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,14 +347,14 @@ 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()) -// 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 0bee077b845..8166706cc4e 100644 --- a/embedded-wallets/sdk/android/advanced/README.mdx +++ b/embedded-wallets/sdk/android/advanced/README.mdx @@ -16,15 +16,16 @@ 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", + ), + this ) // focus-end @@ -46,25 +47,28 @@ 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` | -| `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. | +| 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 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`. | -| 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 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. | @@ -72,18 +76,19 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. ```kotlin 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 whiteLabel: WhiteLabelData? = null, - val loginConfig: HashMap? = null, - val useCoreKitKey: Boolean? = false, - val chainNamespace: ChainNamespace? = ChainNamespace.EIP155, - val mfaSettings: MfaSettings? = null, - val sessionTime: Int? = 86400 + var redirectUrl: String, + @SerializedName("network") val web3AuthNetwork: Web3AuthNetwork, + @SerializedName("buildEnv") var authBuildEnv: BuildEnv = BuildEnv.PRODUCTION, + var whiteLabel: WhiteLabelData? = null, + var authConnectionConfig: List? = emptyList(), + val useSFAKey: Boolean? = false, + var chains: Chains? = null, + var mfaSettings: MfaSettings? = null, + val sessionTime: Int = 30 * 86400, + val walletServicesConfig: WalletServicesConfig? = null, + var defaultChainId: String? = "0x1", + var enableLogging: Boolean = false ) ``` @@ -96,30 +101,85 @@ 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: 7 days (`86400 * 7`). + - Default: 30 days (`86400 * 30`). ```kotlin 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", + ), + 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 (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 (for example, `"ETH"`). | +| `tickerName` | `String?` | No | Full name of the native token (for example, `"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 ) ``` ## 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 @@ -129,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 9059ffc2efe..2ef75b07f1a 100644 --- a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx @@ -32,19 +32,15 @@ Learn more about the [auth provider setup](/embedded-wallets/authentication) and ## Configuration -:::warning +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. -::: - -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 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. | ```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 +89,7 @@ data class LoginConfigItem( private var showOnMobile: Boolean? = true, ) -enum class TypeOfLogin { +enum class AuthConnection { @SerializedName("google") GOOGLE, @SerializedName("facebook") @@ -122,10 +118,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 } ``` @@ -134,6 +132,8 @@ enum class TypeOfLogin { ### Usage + + = web3Auth.login( - LoginParams(Provider.GOOGLE) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) ) // focus-end ``` @@ -180,28 +181,29 @@ 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 ) ) // focus-end - ) + ), + this ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.Facebook) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.FACEBOOK) ) // focus-end @@ -214,26 +216,27 @@ 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, - clientId = getString (R.string.auth0_project_id) // Auth0's client id + 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 - ) + ), + this ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.JWT) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.CUSTOM) ) // focus-end ``` @@ -245,27 +248,28 @@ 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 - ) + ), + this ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.JWT) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.CUSTOM) ) // focus-end @@ -274,9 +278,11 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login -## Configure extra login options + + +## Configure extra sign-in 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. +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 @@ -290,29 +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 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 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. | @@ -324,15 +331,16 @@ 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, 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, @@ -342,6 +350,13 @@ data class ExtraLoginOptions( private var nonce : String? = null, private var redirect_uri : String? = null ) + +enum class EmailFlowType { + @SerializedName("code") + CODE, + @SerializedName("link") + LINK +} ``` @@ -349,11 +364,13 @@ data class ExtraLoginOptions( ### 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 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, - clientId = getString (R.string.auth0_project_id) // Auth0's client id + 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 - ) + ), + this ) -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 ) @@ -398,38 +416,35 @@ 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. + +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 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 - ) + ), + this ) -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 +453,34 @@ 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 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 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", + ), + this ) -val loginCompletableFuture: CompletableFuture = web3Auth.login( +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - Provider.EMAIL_PASSWORDLESS, - // focus-next-line - extraLoginOptions = ExtraLoginOptions(login_hint = "hello@web3auth.io") + AuthConnection.EMAIL_PASSWORDLESS, + // 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 ) ) ``` @@ -468,28 +488,30 @@ 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: + +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}, that is, (+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", + ), + this ) // 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,54 +521,57 @@ 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 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 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) ) ) // focus-end - ) + ), + this ) // 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..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 @@ -34,31 +34,31 @@ 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 in case 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 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 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..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,19 +28,19 @@ 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 ```kotlin -val loginResponse = web3Auth.login( +val loginResponse = web3Auth.connectTo( LoginParams( - Proider.GOOGLE, + AuthConnection.GOOGLE, // focus-next-line mfaLevel = MFALevel.MANDATORY ) @@ -49,7 +49,7 @@ val loginResponse = web3Auth.login( ## 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. ") + AuthConnection.CUSTOM, + idToken = "your_jwt_token" ) // focus-next-line @@ -170,14 +170,14 @@ You can configure the order of MFA or enable/disable MFA type by passing the `mf -| 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. | @@ -237,13 +237,13 @@ 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), @@ -254,12 +254,13 @@ val web3Auth = Web3Auth( authenticatorFactor = MfaSetting(true, 6, true), ) // focus-end - ) + ), + this ) -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/smart-accounts.mdx b/embedded-wallets/sdk/android/advanced/smart-accounts.mdx new file mode 100644 index 00000000000..fee5e58037a --- /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 468eccd7710..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 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 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 as a string. | +| `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. | @@ -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), - network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), +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 - ThemeModes = ThemeModes.DARK, // LIGHT, DARK, AUTO + 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/usage/README.mdx b/embedded-wallets/sdk/android/usage/README.mdx index 7d8724c5fcc..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,23 +16,24 @@ 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) | 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 -| 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 -| 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. | +| 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 @@ -43,7 +44,23 @@ 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 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()` + +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 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 new file mode 100644 index 00000000000..0892109e6d6 --- /dev/null +++ b/embedded-wallets/sdk/android/usage/connect-to.mdx @@ -0,0 +1,372 @@ +--- +title: Sign 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 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 + +The `connectTo` method takes `LoginParams` as a required input. + + + + + +| 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. | + + + + + +```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 +} +``` + + + + +## Return Value: `Web3AuthResponse` + +`connectTo` returns a `CompletableFuture`. The response contains: + +| 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 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 + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + 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 +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( + 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 +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( + 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 +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( + 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 +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( + 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 +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( + 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 +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( + 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 +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( + 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 +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( + 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 +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/enable-mfa.mdx b/embedded-wallets/sdk/android/usage/enable-mfa.mdx index 0ce1af8dc79..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 @@ -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 c29c182ad0b..28ac6f67539 100644 --- a/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx +++ b/embedded-wallets/sdk/android/usage/get-ed25519-private-key.mdx @@ -1,19 +1,26 @@ --- 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. - -## Usage - -```kotlin -val privateKey = web3Auth.getEd25519PrivKey() -``` +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. :::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 796be042d69..9dc24aabe11 100644 --- a/embedded-wallets/sdk/android/usage/get-private-key.mdx +++ b/embedded-wallets/sdk/android/usage/get-private-key.mdx @@ -1,19 +1,38 @@ --- 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. - -## Usage - -```kotlin -val privateKey = web3Auth.getPrivKey() -``` +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. :::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..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,13 @@ 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 + +`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 @@ -12,23 +18,38 @@ You can use the `getUserInfo` method to retrieve various details about the user, 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 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 + +```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/launch-wallet-services.mdx b/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx index 1af48ba2bb0..d0e96328e48 100644 --- a/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx +++ b/embedded-wallets/sdk/android/usage/launch-wallet-services.mdx @@ -1,17 +1,28 @@ --- -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 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 + +- **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 -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 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**. ::: @@ -21,64 +32,53 @@ 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 ``` + +## 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/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/manage-mfa.mdx b/embedded-wallets/sdk/android/usage/manage-mfa.mdx index a452f1cb2cd..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 @@ -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 } } - ``` diff --git a/embedded-wallets/sdk/android/usage/request.mdx b/embedded-wallets/sdk/android/usage/request.mdx index f09c6e1fe85..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. @@ -18,12 +18,39 @@ 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`. 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 + +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. + +::: + +## 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 @@ -32,16 +59,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 ) @@ -58,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 d6e38316270..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', @@ -746,7 +747,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..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:7.4.0' + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.1' } ``` @@ -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 @@ -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). ::: @@ -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() @@ -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' } ``` @@ -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 diff --git a/src/utils/w3a-sdk-map.js b/src/utils/w3a-sdk-map.js index 0148225dbb3..3310cb8e17d 100644 --- a/src/utils/w3a-sdk-map.js +++ b/src/utils/w3a-sdk-map.js @@ -13,26 +13,14 @@ export const flutter = 'Flutter' export const unity = 'Unity' export const unreal = 'Unreal Engine' -export const pnpWebVersion = `11.0.x` -export const pnpAndroidVersion = `9.1.2` -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 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 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) { @@ -47,6 +35,9 @@ export function getPnPVersion(platform) { if (platform === reactnative) { return pnpRNVersion } + if (platform === node) { + return pnpNodeVersion + } if (platform === flutter) { return pnpFlutterVersion } @@ -56,31 +47,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..17a830538e9 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/", @@ -1042,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/",