diff --git a/embedded-wallets/sdk/android/README.mdx b/embedded-wallets/sdk/android/README.mdx index 209e5d30410..85815afe51d 100644 --- a/embedded-wallets/sdk/android/README.mdx +++ b/embedded-wallets/sdk/android/README.mdx @@ -45,7 +45,7 @@ Then, in your app-level `build.gradle` dependencies section, add the following: dependencies { // ... // focus-next-line - implementation 'com.github.web3auth:web3auth-android-sdk:9.1.2' + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' } ``` @@ -148,14 +148,15 @@ Create a Web3Auth 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 over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) // focus-end @@ -181,7 +182,7 @@ override fun onNewIntent(intent: Intent?) { After instantiating Web3Auth, 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 @@ -194,7 +195,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 @@ -235,7 +236,7 @@ val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_CLIENT_ID", - network = Network.SAPPHIRE_MAINNET, // or Network.SAPPHIRE_DEVNET + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET redirectUrl = "YOUR_APP_SCHEME://auth" ) ) @@ -250,11 +251,11 @@ val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_CLIENT_ID", - network = Network.SAPPHIRE_MAINNET, // or Network.SAPPHIRE_DEVNET + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, // or Web3AuthNetwork.SAPPHIRE_DEVNET redirectUrl = "YOUR_APP_SCHEME://auth" - loginConfig = hashMapOf("google" to LoginConfigItem( - verifier = "verifier-name", // Get it from Web3Auth dashboard - typeOfLogin = TypeOfLogin.GOOGLE, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from Web3Auth dashboard + authConnection = AuthConnection.GOOGLE, clientId = getString(R.string.google_client_id) // Google's client id )), mfaSettings = MfaSettings( @@ -273,13 +274,30 @@ val web3Auth = Web3Auth( +## Single Factor Auth (SFA) Support + +Web3Auth Android SDK includes built-in support for Single Factor Auth (SFA), allowing for seamless authentication when you already have a JWT token from your authentication system. When MFA is disabled, users won't even notice Web3Auth's presence - they'll be automatically authenticated using just your JWT token, making the login experience completely frictionless. + +```kotlin +// SFA login with custom JWT +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_verifier_id", + idToken = "your_jwt_token" + ) +) +``` + +SFA mode is automatically activated when you provide an `idToken` parameter. This enables direct authentication without additional social login steps, perfect for applications that already have their own authentication system. + ## Blockchain Integration Web3Auth is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Web3Auth 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 @@ -288,7 +306,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) @@ -308,7 +326,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 @@ -317,7 +335,7 @@ import org.sol4k.Keypair val connection = Connection(RpcUrl.DEVNET) // Use your Web3Auth instance to get the private key -val ed25519PrivateKey = web3Auth.getEd25519PrivKey() +val ed25519PrivateKey = web3Auth.getEd25519PrivateKey() // Generate the Solana KeyPair val solanaKeyPair = Keypair.fromSecretKey(ed25519PrivateKey.hexToByteArray()) diff --git a/embedded-wallets/sdk/android/advanced/README.mdx b/embedded-wallets/sdk/android/advanced/README.mdx index 6769e3034a3..bf16da0b3f3 100644 --- a/embedded-wallets/sdk/android/advanced/README.mdx +++ b/embedded-wallets/sdk/android/advanced/README.mdx @@ -16,14 +16,15 @@ When setting up Web3Auth, you'll pass in the options to the constructor. This co ```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 over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) // focus-end @@ -50,21 +51,24 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `context` | Android context to launch Web-based authentication, usually is the current activity. It's a mandatory field, and accepts `android.content.Context` as a value. | | `clientId` | Your Web3Auth Client ID. You can get it from Web3Auth [Dashboard](https://dashboard.web3auth.io/) under project details. It's a mandatory field of type `String` | -| `network` | Defines the Web3Auth Network. It's a mandatory field of type Network. | -| `redirectUrl` | URL that Web3Auth will redirect API responses upon successful authentication from browser. It's a mandatory field of type `Uri`. | +| `web3AuthNetwork` | Defines the Web3Auth Network. It's a mandatory field of type `Web3AuthNetwork`. | +| `redirectUrl` | URL that Web3Auth will redirect API responses upon successful authentication from browser. It's a mandatory field of type `String`. | | `sessionTime?` | It 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. | +| `useSFAKey?` | Use SFA Key to get single factor auth key. It's an optional field with default value as `false`. Useful for Wallet Pregeneration and SFA mode. | +| `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. | +| `defaultChainId?` | Default chain ID to use. It's an optional field with default value as `null`. The first chain in the list will be used if not provided. | +| `enableLogging?` | Setting to true will enable logs. It's an optional field with default value as `false`. | -| Parameter | Description | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `whiteLabel?` | WhiteLabel options for web3auth. It helps you define custom UI, branding, and translations for your brand app. It takes `WhiteLabelData` as a value. | -| `loginConfig?` | Login config for the custom verifiers. It takes `HashMap` as a value. | -| `mfaSettings?` | Allows developers to configure the Mfa settings for authentication. It takes `MfaSettings` as a value. | +| Parameter | Description | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `whiteLabel?` | WhiteLabel options for web3auth. It helps you define custom UI, branding, and translations for your brand app. It takes `WhiteLabelData` as a value. | +| `authConnectionConfig?` | Auth connection config for the custom auth connections. It takes `List` as a value. | +| `mfaSettings?` | Allows developers to configure the MFA settings for authentication. It takes `MfaSettings` as a value. | +| `walletServicesConfig?` | Configuration for wallet services including whitelabel options. It takes `WalletServicesConfig` as a value. | @@ -74,16 +78,19 @@ The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. data class Web3AuthOptions( var context: Context, val clientId: String, - val network: Network, - var buildEnv: BuildEnv? = BuildEnv.PRODUCTION, - @Transient var redirectUrl: Uri, - var sdkUrl: String = getSdkUrl(buildEnv), + val web3AuthNetwork: Web3AuthNetwork, + var authBuildEnv: BuildEnv? = BuildEnv.PRODUCTION, + var redirectUrl: String, + var sdkUrl: String = getSdkUrl(authBuildEnv), val whiteLabel: WhiteLabelData? = null, - val loginConfig: HashMap? = null, - val useCoreKitKey: Boolean? = false, - val chainNamespace: ChainNamespace? = ChainNamespace.EIP155, + val authConnectionConfig: List? = null, + val useSFAKey: Boolean? = false, + val chains: Chains? = null, val mfaSettings: MfaSettings? = null, - val sessionTime: Int? = 86400 + val sessionTime: Int = 86400, + val walletServicesConfig: WalletServicesConfig? = null, + val defaultChainId: String? = null, + val enableLogging: Boolean? = false ) ``` @@ -106,9 +113,9 @@ var web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, sessionTime = 86400 * 7, // 7 days (in seconds) - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) ``` diff --git a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx index 26801b8409b..bbf16888320 100644 --- a/embedded-wallets/sdk/android/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/android/advanced/custom-authentication.mdx @@ -32,19 +32,11 @@ Visit the [Auth Provider Setup](/embedded-wallets/authentication) page to learn ## Configuration -:::warning +To use custom authentication (Using Social providers or Login providers like Auth0, AWS Cognito, Firebase etc. or even your own custom JWT login) you can add the configuration using `authConnectionConfig` parameter during the initialization. -_**"Auth Connection"**_ is called _**"Verifier"**_ in the Android SDK. It is the older terminology which we will be updating in the upcoming releases. +The `authConnectionConfig` parameter is a list of `AuthConnectionConfig` instances, each defining a specific authentication connection. -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 Social providers or Login providers like Auth0, AWS Cognito, Firebase etc. or even your own custom JWT login) you can add the configuration using `loginConfig` parameter during the initialization. - -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 Web3Auth Dashboard. It's a mandatory field, and accepts `String` as a 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. e.g. Google's Client ID or Web3Auth's client Id if using 'jwt' as TypeOfLogin. It's a mandatory field, and accepts `String` as a value. | -| `name?` | Display name for the verifier. 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. | -| `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 `String` as a value. | -| `logoHover?` | Logo to be shown on mouse hover. It accepts `String` as a value. | -| `logoLight?` | Light logo for dark background. It accepts `String` as a value. | -| `logoDark?` | Dark logo for light background. It accepts `String` as a value. | -| `mainOption?` | Show login button on the main list. It accepts `Boolean` as a value. Default value is false. | -| `showOnModal?` | Whether to show the login button on modal or not. Default value is true. | -| `showOnDesktop?` | Whether to show the login button on desktop. Default value is true. | -| `showOnMobile?` | Whether to show the login button on mobile. Default value is true. | +| Parameter | Description | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `authConnectionId` | The name of the auth connection that you have registered on the Web3Auth Dashboard. It's a mandatory field, and accepts `String` as a value. | +| `authConnection` | Type of login of this auth connection, this value will affect the login flow that is adapted. For example, if you choose `google`, a Google sign-in flow will be used. If you choose `custom`, you should be providing your own JWT token, no sign-in flow will be presented. It's a mandatory field, and accepts `AuthConnection` as a value. | +| `clientId` | Client id provided by your login provider used for custom auth connection. e.g. Google's Client ID or Web3Auth's client Id if using 'custom' as AuthConnection. It's a mandatory field, and accepts `String` as a value. | +| `name?` | Display name for the auth connection. If null, the default name is used. It accepts `String` as a value. | +| `description?` | Description for the button. If provided, it renders as a full length button. else, icon button. It accepts `String` as a value. | +| `groupedAuthConnectionId?` | The field in JWT token which maps to grouped auth connection id. Please make sure you selected correct JWT auth connection id in the developer dashboard. It accepts `String` as a value. | +| `logoHover?` | Logo to be shown on mouse hover. It accepts `String` as a value. | +| `logoLight?` | Light logo for dark background. It accepts `String` as a value. | +| `logoDark?` | Dark logo for light background. It accepts `String` as a value. | +| `mainOption?` | Show login button on the main list. It accepts `Boolean` as a value. Default value is false. | +| `showOnModal?` | Whether to show the login button on modal or not. Default value is true. | +| `showOnDesktop?` | Whether to show the login button on desktop. Default value is true. | +| `showOnMobile?` | Whether to show the login button on mobile. Default value is true. | ```kotlin -data class LoginConfigItem( - var verifier: String, - private var typeOfLogin: TypeOfLogin, +data class AuthConnectionConfig( + var authConnectionId: String, + private var authConnection: AuthConnection, private var name: String? = null, private var description: String? = null, private var clientId: String, - private var verifierSubIdentifier: String? = null, + private var groupedAuthConnectionId: String? = null, private var logoHover: String? = null, private var logoLight: String? = null, private var logoDark: String? = null, @@ -93,7 +85,7 @@ data class LoginConfigItem( private var showOnMobile: Boolean? = true, ) -enum class TypeOfLogin { +enum class AuthConnection { @SerializedName("google") GOOGLE, @SerializedName("facebook") @@ -122,10 +114,12 @@ enum class TypeOfLogin { WECHAT, @SerializedName("email_passwordless") EMAIL_PASSWORDLESS, - @SerializedName("email_password") - EMAIL_PASSWORD, - @SerializedName("jwt") - JWT + @SerializedName("custom") + CUSTOM, // for jwt + @SerializedName("sms_passwordless") + SMS_PASSWORDLESS, + @SerializedName("farcaster") + FARCASTER } ``` @@ -149,17 +143,18 @@ enum class TypeOfLogin { ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf("google" to LoginConfigItem( - verifier = "verifier-name", // Get it from Web3Auth dashboard - typeOfLogin = TypeOfLogin.GOOGLE, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from Web3Auth dashboard + authConnection = AuthConnection.GOOGLE, clientId = getString(R.string.google_client_id) // Google's client id )) // focus-end @@ -167,8 +162,8 @@ val web3Auth = Web3Auth( ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.GOOGLE) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) ) // focus-end ``` @@ -180,18 +175,19 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf( - "facebook" to LoginConfigItem( - verifier = "verifier-name", // Get it from Web3Auth dashboard - typeOfLogin = TypeOfLogin.FACEBOOK, + authConnectionConfig = listOf( + AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from Web3Auth dashboard + authConnection = AuthConnection.FACEBOOK, clientId = getString(R.string.facebook_client_id) // Facebook's client id ) ) @@ -200,8 +196,8 @@ val web3Auth = Web3Auth( ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.Facebook) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.FACEBOOK) ) // focus-end @@ -214,17 +210,18 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // Get it from Web3Auth dashboard - typeOfLogin = TypeOfLogin.JWT, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from Web3Auth dashboard + authConnection = AuthConnection.CUSTOM, clientId = getString (R.string.auth0_project_id) // Auth0's client id )) // focus-end @@ -232,8 +229,8 @@ val web3Auth = Web3Auth( ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.JWT) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.CUSTOM) ) // focus-end ``` @@ -245,18 +242,19 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf( - "jwt" to LoginConfigItem( - verifier = "verifier-name", // Get it from Web3Auth dashboard - typeOfLogin = TypeOfLogin.JWT, + authConnectionConfig = listOf( + AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from Web3Auth dashboard + authConnection = AuthConnection.CUSTOM, ) ) // focus-end @@ -264,8 +262,8 @@ val web3Auth = Web3Auth( ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( - LoginParams(Provider.JWT) +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.CUSTOM) ) // focus-end @@ -290,29 +288,30 @@ Additional to the `LoginConfig` you can pass extra options to the `login` functi -| Parameter | Description | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `additionalParams?` | Additional params in `HashMap` format for OAuth login, use id_token(JWT) to authenticate with web3auth. | -| `domain?` | Your custom authentication domain in `String` format. For example, if you are using Auth0, it can be example.au.auth0.com. | -| `client_id?` | Client id in `String` format, provided by your login provider used for custom verifier. | -| `leeway?` | The value used to account for clock skew in JWT expirations. The value is in the seconds, and ideally should no more than 60 seconds or 120 seconds at max. It takes `String` as a value. | -| `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 takes `String` as a 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 takes `String` as a value. | -| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | -| `id_token_hint?` | It denotes the previously issued ID token. It takes `String` as a value. | -| `id_token?` | JWT (ID Token) to be passed for login. | -| `login_hint?` | Used to specify the user's email address or phone number for Email/SMS Passwordless login flows. Takes a `String` value. For the SMS, the format should be: `+{country_code}-{phone_number}` (e.g. `+1-1234567890`) | -| `acr_values?` | acc_values | -| `scope?` | The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It takes `String` as a value. | -| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It takes `String` as a value. | -| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget. It takes `String` as a value. | -| `state?` | state | -| `response_type?` | Defines which grant to execute for the authorization server. It takes `String` as a value. | -| `nonce?` | nonce | -| `redirect_uri?` | It can be used to specify the default url, where your custom jwt verifier can redirect your browser to with the result. If you are using Auth0, it must be whitelisted in the Allowed Callback URLs in your Auth0's application. | +| Parameter | Description | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `additionalParams?` | Additional params in `HashMap` format for OAuth login, use id_token(JWT) to authenticate with web3auth. | +| `domain?` | Your custom authentication domain in `String` format. For example, if you are using Auth0, it can be example.au.auth0.com. | +| `client_id?` | Client id in `String` format, provided by your login provider used for custom verifier. | +| `leeway?` | The value used to account for clock skew in JWT expirations. The value is in the seconds, and ideally should no more than 60 seconds or 120 seconds at max. It takes `String` as a value. | +| `userIdField?` | The field in JWT token which maps to user id. Please make sure you selected correct JWT user id in the developer dashboard. It takes `String` as a value. | +| `isUserIdCaseSensitive?` | Boolean to confirm Whether the user id field is case sensitive or not. | +| `display?` | Allows developers the configure the display of UI. It takes `Display` as a value. | +| `prompt?` | Prompt shown to the user during authentication process. It takes `Prompt` as a value. | +| `max_age?` | Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It takes `String` as a value. | +| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | +| `id_token_hint?` | It denotes the previously issued ID token. It takes `String` as a value. | +| `id_token?` | JWT (ID Token) to be passed for login. | +| `access_token?` | Access token for OAuth flows. It takes `String` as a value. | +| `flow_type?` | Specifies the email passwordless flow type. It takes `EmailFlowType` as a value (`CODE` or `LINK`). | +| `acr_values?` | acc_values | +| `scope?` | The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It takes `String` as a value. | +| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It takes `String` as a value. | +| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget. It takes `String` as a value. | +| `state?` | state | +| `response_type?` | Defines which grant to execute for the authorization server. It takes `String` as a value. | +| `nonce?` | nonce | +| `redirect_uri?` | It can be used to specify the default url, where your custom jwt verifier can redirect your browser to with the result. If you are using Auth0, it must be whitelisted in the Allowed Callback URLs in your Auth0's application. | @@ -324,15 +323,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 +342,13 @@ data class ExtraLoginOptions( private var nonce : String? = null, private var redirect_uri : String? = null ) + +enum class EmailFlowType { + @SerializedName("code") + CODE, + @SerializedName("link") + LINK +} ``` @@ -366,30 +373,31 @@ Auth0 has a special login flow, called the SPA flow. This flow requires a `clien ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // Get it from Web3Auth dashboard - typeOfLogin = TypeOfLogin.JWT, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from Web3Auth dashboard + authConnection = AuthConnection.CUSTOM, clientId = getString (R.string.auth0_project_id) // Auth0's client id )) // focus-end ) ) -val loginCompletableFuture: CompletableFuture = web3Auth.login( +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - Provider.JWT, + AuthConnection.CUSTOM, // focus-start extraLoginOptions = ExtraLoginOptions( - domain: "https://username.us.auth0.com", // Domain of your Auth0 app - verifierIdField: "sub", // The field in jwt token which maps to verifier id. + domain = "https://username.us.auth0.com", // Domain of your Auth0 app + userIdField = "sub", // The field in jwt token which maps to user id. ) // focus-end ) @@ -400,36 +408,33 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login If you're using any other provider like Firebase/ AWS Cognito or deploying your own Custom JWT -server, you need to put the jwt token into the `id_token` field of the `extraLoginOptions`, -additionally, you need to pass over the `domain` field as well, which is mandatory. If you don't -have a domain, just passover a string in that field. +server, you need to put the jwt token into the `idToken` field of the `LoginParams`. For SFA (Single Factor Auth) mode, this enables direct authentication without additional login flows. ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // Get it from Web3Auth dashboard - typeOfLogin = TypeOfLogin.JWT, + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "auth-connection-id", // Get it from Web3Auth dashboard + authConnection = AuthConnection.CUSTOM, )) // focus-end ) ) -val loginCompletableFuture: CompletableFuture = web3Auth.login( +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - Provider.JWT, + AuthConnection.CUSTOM, // focus-start - extraLoginOptions = ExtraLoginOptions( - id_token: "Your JWT id token", - ) + idToken = "Your JWT id token", // focus-end ) ) @@ -438,29 +443,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 login, you need to put the email into the `loginHint` parameter of +the `LoginParams`. By default, the login flow will be `code` flow, if you want to use the +`link` flow, you need to put `flow_type` into the `extraLoginOptions` parameter. ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) -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 +478,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 make sure the phone number is in the format of + +To use the SMS Passwordless login, send the phone number as the `loginHint` parameter of the +`LoginParams`. Please make sure the phone number is in the format of +\{country_code}-\{phone_number}, i.e. (+91-09xx901xx1). ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ) ) // focus-start -val loginCompletableFuture: CompletableFuture = web3Auth.login( +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( LoginParams( - Provider.SMS_PASSWORDLESS, - extraLoginOptions = ExtraLoginOptions(login_hint = "+91-9911223344") + AuthConnection.SMS_PASSWORDLESS, + loginHint = "+91-9911223344" ) ) // focus-end @@ -499,33 +511,34 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login -### Aggregate Verifier Usage +### Grouped Auth Connection Usage -You can use aggregate verifier to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and Email Passwordless login, or Google and GitHub via Auth0 to access the same address for your user. +You can use grouped auth connections to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and Email Passwordless login, or Google and GitHub via Auth0 to access the same address for your user. ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start - loginConfig = hashMapOf( - "google" to LoginConfigItem( - verifier = "aggregate-sapphire", - verifierSubIdentifier= "w3a-google", - typeOfLogin = TypeOfLogin.GOOGLE, + authConnectionConfig = listOf( + AuthConnectionConfig( + authConnectionId = "aggregate-sapphire", + groupedAuthConnectionId = "w3a-google", + authConnection = AuthConnection.GOOGLE, name = "Aggregate Login", clientId = getString(R.string.web3auth_google_client_id) ), - "jwt" to LoginConfigItem( - verifier = "aggregate-sapphire", - verifierSubIdentifier= "w3a-a0-email-passwordless", - typeOfLogin = TypeOfLogin.JWT, + AuthConnectionConfig( + authConnectionId = "aggregate-sapphire", + groupedAuthConnectionId = "w3a-a0-email-passwordless", + authConnection = AuthConnection.CUSTOM, name = "Aggregate Login", clientId = getString(R.string.web3auth_auth0_client_id) ) @@ -536,17 +549,17 @@ val web3Auth = Web3Auth( // focus-start // Google Login -web3Auth.login(LoginParams(Provider.GOOGLE)) +web3Auth.connectTo(LoginParams(AuthConnection.GOOGLE)) // focus-end // focus-start // Auth0 Login -web3Auth.login(LoginParams( - Provider.JWT, +web3Auth.connectTo(LoginParams( + AuthConnection.CUSTOM, extraLoginOptions = ExtraLoginOptions( domain = "https://web3auth.au.auth0.com", - verifierIdField = "email", - isVerifierIdCaseSensitive = false + userIdField = "email", + isUserIdCaseSensitive = false ) )) // focus-end diff --git a/embedded-wallets/sdk/android/advanced/dapp-share.mdx b/embedded-wallets/sdk/android/advanced/dapp-share.mdx index 72a6d4bd73c..5d11a099111 100644 --- a/embedded-wallets/sdk/android/advanced/dapp-share.mdx +++ b/embedded-wallets/sdk/android/advanced/dapp-share.mdx @@ -34,14 +34,14 @@ After a successful login from a user, the user details are returned as a respons "email": "w3a-heroes@web3auth.com", "name": "Web3Auth Heroes", "profileImage": "https://lh3.googleusercontent.com/a/Ajjjsdsmdjmnm...", - "verifier": "torus", - "verifierId": "w3a-heroes@web3auth.com", - "typeOfLogin": "google", - "aggregateVerifier": "w3a-google-sapphire", - "dappShare": "", // 24 words of seed phrase will be sent only incase of custom verifiers + "authConnectionId": "torus", + "userId": "w3a-heroes@web3auth.com", + "authConnection": "google", + "groupedAuthConnectionId": "w3a-google-sapphire", + "dappShare": "", // 24 words of seed phrase will be sent only incase of custom auth connections "idToken": "", - "oAuthIdToken": "", // will be sent only incase of custom verifiers - "oAuthAccessToken": "", // will be sent only incase of custom verifiers + "oAuthIdToken": "", // will be sent only incase of custom auth connections + "oAuthAccessToken": "", // will be sent only incase of custom auth connections "isMfaEnabled": false // Returns whether the user has enabled MFA or not } } @@ -53,12 +53,12 @@ Now, while logging in, the user can use their social accounts to obtain one shar :::note -One major thing to note here is that the `dappShare` is only available for custom verifiers and not the standard web3auth verifiers. This is done to make sure that an application only has access to the corresponding share to the private key of their application's user. Hence, to use dApp Share, one has to use the custom authentication feature of Web3Auth. Also, the dApp Share is only returned to users who have enabled 2FA to their account. +One major thing to note here is that the `dappShare` is only available for custom auth connections and not the standard web3auth auth connections. This is done to make sure that an application only has access to the corresponding share to the private key of their application's user. Hence, to use dApp Share, one has to use the custom authentication feature of Web3Auth. Also, the dApp Share is only returned to users who have enabled 2FA to their account. ::: ```kotlin -web3Auth.login(LoginParams(selectedLoginProvider, dappShare = "<24 words seed phrase>")) +web3Auth.connectTo(LoginParams(selectedLoginProvider, dappShare = "<24 words seed phrase>")) ``` ## Example @@ -73,10 +73,10 @@ class MainActivity : AppCompatActivity() { private lateinit var web3Auth: Web3Auth private fun signIn() { - val selectedLoginProvider = Provider.GOOGLE + val selectedLoginProvider = AuthConnection.GOOGLE // Can be GOOGLE, FACEBOOK, TWITCH etc. val loginCompletableFuture: CompletableFuture = - web3Auth.login(LoginParams(selectedLoginProvider, + web3Auth.connectTo(LoginParams(selectedLoginProvider, // focus-next-line dappShare = "<24 words seed phrase>")) loginCompletableFuture.whenComplete { loginResponse, error -> diff --git a/embedded-wallets/sdk/android/advanced/mfa.mdx b/embedded-wallets/sdk/android/advanced/mfa.mdx index c929d0cbc00..5d877d5b224 100644 --- a/embedded-wallets/sdk/android/advanced/mfa.mdx +++ b/embedded-wallets/sdk/android/advanced/mfa.mdx @@ -34,9 +34,9 @@ If you are using default verifiers, your users may have set up MFA on other dApp ### Usage ```kotlin -val loginResponse = web3Auth.login( +val loginResponse = web3Auth.connectTo( LoginParams( - Proider.GOOGLE, + AuthConnection.GOOGLE, // focus-next-line mfaLevel = MFALevel.MANDATORY ) @@ -104,8 +104,8 @@ class MainActivity : AppCompatActivity() { private lateinit var web3Auth: Web3Au private fun enableMFA() { val loginParams = LoginParams( - Provider.JWT, - extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token") + AuthConnection.CUSTOM, + idToken = "your_jwt_token" ) // focus-next-line @@ -166,13 +166,13 @@ 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. | +| 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. | @@ -233,13 +233,14 @@ data class MfaSetting( ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // focus-start mfaSettings = MfaSettings( deviceShareFactor = MfaSetting(true, 1, true), @@ -253,9 +254,9 @@ val web3Auth = Web3Auth( ) ) -val loginResponse = web3Auth.login( +val loginResponse = web3Auth.connectTo( LoginParams( - Proider.GOOGLE, + AuthConnection.GOOGLE, // focus-next-line mfaLevel = MFALevel.MANDATORY ) diff --git a/embedded-wallets/sdk/android/advanced/whitelabel.mdx b/embedded-wallets/sdk/android/advanced/whitelabel.mdx index fbb1df11a65..9dd16157839 100644 --- a/embedded-wallets/sdk/android/advanced/whitelabel.mdx +++ b/embedded-wallets/sdk/android/advanced/whitelabel.mdx @@ -36,16 +36,16 @@ For defining custom UI, branding, and translations for your brand during Web3Aut -| Parameter | Description | -| --- | --- | -| `appName?` | Display name for the app in the UI. | -| `logoLight?` | App logo to be used in dark mode. It accepts url in `String` as a value. | -| `logoDark?` | App logo to be used in light mode. It accepts url in `String` as a value. | +| Parameter | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `appName?` | Display name for the app in the UI. | +| `logoLight?` | App logo to be used in dark mode. It accepts url in `String` as a value. | +| `logoDark?` | App logo to be used in light mode. It accepts url in `String` as a value. | | `defaultLanguage?` | Language which will be used by Web3Auth, app will use browser language if not specified. Default language is `Language.EN`. Checkout `Language` for supported languages. | -| `mode?` | Theme mode for the login modal. Choose between `ThemeModes.AUTO`, `ThemeModes.LIGHT` or `ThemeModes.DARK` background modes. Default value is `ThemeModes.AUTO`. | -| `theme?` | Used to customize the theme of the login modal. It accepts `HashMap` as a value. | -| `appUrl?` | Url to be used in the Modal. It accepts url in `String` as a value. | -| `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are null, the default Web3Auth logo will be used for the loader. Default value is false. | +| `mode?` | Theme mode for the login modal. Choose between `ThemeModes.AUTO`, `ThemeModes.LIGHT` or `ThemeModes.DARK` background modes. Default value is `ThemeModes.AUTO`. | +| `theme?` | Used to customize the theme of the login modal. It accepts `HashMap` as a value. | +| `appUrl?` | Url to be used in the Modal. It accepts url in `String` as a value. | +| `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are null, the default Web3Auth logo will be used for the loader. Default value is false. | @@ -76,8 +76,8 @@ web3Auth = Web3Auth ( Web3AuthOptions ( context = this, clientId = getString (R.string.web3auth_project_id), - network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", // Optional whitelabel object // focus-start whiteLabel = WhiteLabelData ( @@ -86,7 +86,7 @@ web3Auth = Web3Auth ( logoLight = null, logoDark = null, defaultLanguage = Language.EN, // EN, DE, JA, KO, ZH, ES, FR, PT, NL - ThemeModes = ThemeModes.DARK, // LIGHT, DARK, AUTO + mode = ThemeModes.DARK, // LIGHT, DARK, AUTO useLogoLoader = true, theme = hashMapOf ( "primary" to "#229954" diff --git a/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx new file mode 100644 index 00000000000..b8ea6c0af3c --- /dev/null +++ b/embedded-wallets/sdk/android/migration-guides/android-v9-to-v10.mdx @@ -0,0 +1,414 @@ +--- +title: Migrating from v9.x to v10.x +sidebar_label: v9.x to v10.x +description: 'Web3Auth Android SDK - Migrating from v9.x to v10.x | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +This migration guide provides a step-by-step walkthrough for upgrading your Web3Auth Android SDK implementation from v9.x to v10.x. This is a major release with significant API changes, new features, and improvements. + +## Overview of Changes + +Web3Auth Android SDK v10.x introduces several major changes: + +- **Combined PnP and SFA SDK**: Unified authentication flow supporting both Plug and Play (PnP) and Single Factor Auth (SFA) in one SDK +- **Updated Authentication API**: `login()` method replaced with `connectTo()` for better clarity and SFA support +- **Simplified Wallet Services**: Automatic chain configuration from dashboard settings +- **Enhanced Type Safety**: Updated enums and parameter structures +- **Analytics Integration**: Built-in analytics for better insights +- **Performance Improvements**: Optimized parameter handling and reduced configuration complexity + +## Breaking Changes + +### 1. Update Dependencies + +First, update your dependency to the latest version: + +```groovy +dependencies { + // Old + implementation 'com.github.web3auth:web3auth-android-sdk:9.1.2' + + // New + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' +} +``` + +### 2. Import Changes + +Add the new required import for Web3AuthNetwork: + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import com.web3auth.core.types.Network +import com.web3auth.core.types.Provider +import com.web3auth.core.types.LoginConfigItem +import com.web3auth.core.types.TypeOfLogin +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import com.web3auth.core.types.AuthConnection +import com.web3auth.core.types.AuthConnectionConfig +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork +``` + + + + +### 3. Enum Changes + +Several enums have been renamed for better clarity: + +| v9.x | v10.x | +| ----------------- | ----------------------- | +| `Provider` | `AuthConnection` | +| `TypeOfLogin` | `AuthConnection` | +| `Network` | `Web3AuthNetwork` | +| `LoginConfigItem` | `AuthConnectionConfig` | +| `Provider.JWT` | `AuthConnection.CUSTOM` | + +### 4. Web3AuthOptions Configuration + +The configuration object has been updated with new parameter names: + + + + + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_CLIENT_ID", + network = Network.SAPPHIRE_MAINNET, + redirectUrl = Uri.parse("your-app://auth"), + loginConfig = hashMapOf("google" to LoginConfigItem( + verifier = "verifier-name", + typeOfLogin = TypeOfLogin.GOOGLE, + clientId = "google-client-id" + )), + buildEnv = BuildEnv.PRODUCTION + ) +) +``` + + + + + +```kotlin +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_CLIENT_ID", + web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, + redirectUrl = "your-app://auth", // Now a String instead of Uri + authConnectionConfig = listOf(AuthConnectionConfig( + authConnectionId = "verifier-name", + authConnection = AuthConnection.GOOGLE, + clientId = "google-client-id" + )), + authBuildEnv = BuildEnv.PRODUCTION // Renamed from buildEnv + ) +) +``` + + + + +### 5. Authentication Method Changes + +The main authentication method has been renamed and enhanced: + + + + + +```kotlin +// Simple social login +val loginCompletableFuture = web3Auth.login( + LoginParams(Provider.GOOGLE) +) + +// Email passwordless +val loginCompletableFuture = web3Auth.login( + LoginParams( + Provider.EMAIL_PASSWORDLESS, + extraLoginOptions = ExtraLoginOptions(login_hint = "user@example.com") + ) +) + +// JWT login +val loginCompletableFuture = web3Auth.login( + LoginParams( + Provider.JWT, + extraLoginOptions = ExtraLoginOptions(id_token = "your_jwt_token") + ) +) +``` + + + + + +```kotlin +// Simple social login (PnP mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) +) + +// Email passwordless (PnP mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.EMAIL_PASSWORDLESS, + loginHint = "user@example.com" // Simplified parameter + ) +) + +// JWT login (SFA mode) +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_auth_connection_id", + idToken = "your_jwt_token" // Dedicated parameter for SFA + ) +) +``` + + + + +### 6. Private Key Method Names + +The private key retrieval methods have been renamed for clarity: + + + + + +```kotlin +val privateKey = web3Auth.getPrivKey() +val ed25519Key = web3Auth.getEd25519PrivKey() +``` + + + + + +```kotlin +val privateKey = web3Auth.getPrivateKey() +val ed25519Key = web3Auth.getEd25519PrivateKey() +``` + + + + +### 7. Wallet Services Simplification + +Wallet services methods have been simplified with automatic chain configuration: + + + + + +```kotlin +// Launch wallet services +val chainConfig = ChainConfig( + chainId = "0x1", + rpcTarget = "https://rpc.ethereum.org", + ticker = "ETH", + chainNamespace = ChainNamespace.EIP155 +) + +val launchWalletCF = web3Auth.launchWalletServices(chainConfig) + +// Request signing +val signCF = web3Auth.request( + chainConfig = chainConfig, + method = "personal_sign", + requestParams = params +) +``` + + + + + +```kotlin +// Launch wallet services (automatic chain config from dashboard) +val launchWalletCF = web3Auth.showWalletUI() + +// Request signing (automatic chain config from dashboard) +val signCF = web3Auth.request( + method = "personal_sign", + requestParams = params +) +``` + + + + +## New Features + +### 1. Single Factor Auth (SFA) Support + +v10.x introduces built-in SFA support. You can now use SFA by providing an `idToken`: + +```kotlin +// SFA login with custom JWT +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_verifier_id", + idToken = "your_jwt_token" + ) +) + +// SFA with aggregate verifier +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "aggregate_verifier_id", + groupedAuthConnectionId = "sub_verifier_id", + idToken = "your_jwt_token" + ) +) +``` + +### 2. Enhanced Parameter Handling + +v10.x provides better parameter organization: + +```kotlin +val loginCompletableFuture = web3Auth.connectTo( + LoginParams( + authConnection = AuthConnection.EMAIL_PASSWORDLESS, + loginHint = "user@example.com", // Direct parameter + dappUrl = "https://your-dapp.com", // For analytics + appState = "custom_state" // App state tracking + ) +) +``` + +### 3. Automatic Chain Configuration + +Chain configuration is now managed automatically from your Web3Auth Dashboard: + +1. Configure chains in your [Web3Auth Dashboard](https://dashboard.web3auth.io) +2. The SDK automatically uses these configurations +3. No need to manually pass `ChainConfig` to wallet services + +## Migration Steps + +### Step 1: Update Dependencies + +```groovy +// In your app-level build.gradle +dependencies { + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' +} +``` + +### Step 2: Update Imports + +Replace old imports with new ones as shown in the [Import Changes](#2-import-changes) section. + +### Step 3: Update Initialization + +1. Replace `network` with `web3AuthNetwork` +2. Replace `redirectUrl` Uri with String +3. Update `loginConfig` to `authConnectionConfig` +4. Replace `buildEnv` with `authBuildEnv` + +### Step 4: Update Authentication Calls + +1. Replace `login()` with `connectTo()` +2. Replace `Provider` with `AuthConnection` +3. Update parameter names in `LoginParams` + +### Step 5: Update Private Key Calls + +1. Replace `getPrivKey()` with `getPrivateKey()` +2. Replace `getEd25519PrivKey()` with `getEd25519PrivateKey()` + +### Step 6: Update Wallet Services + +1. Replace `launchWalletServices()` with `showWalletUI()` +2. Remove `ChainConfig` parameters from both `showWalletUI()` and `request()` + +### Step 7: Configure Dashboard + +Ensure your Web3Auth Dashboard has the necessary chain configurations since they're now automatically managed. + +## Troubleshooting + +### Common Issues + +1. **Chain Configuration Missing**: Ensure your Web3Auth Dashboard has the required chains configured +2. **Import Errors**: Make sure to import `Web3AuthNetwork` from the correct package +3. **Parameter Mismatch**: Double-check that you're using the new parameter names + +### Migration Checklist + +- Dependencies updated to v10.x +- Imports updated with new package references +- `Web3AuthOptions` configuration updated +- `login()` calls replaced with `connectTo()` +- Private key method names updated +- Wallet services methods updated +- Dashboard chain configuration verified +- Testing completed for all authentication flows + +## Support + +If you encounter any issues during migration, please: + +1. Check this migration guide thoroughly +2. Review the [updated documentation](/embedded-wallets/sdk/android) +3. Visit our [Support Forum](https://web3auth.io/community/c/help-pnp/pnp-sdk/android/16) +4. Check the [GitHub repository](https://github.com/Web3Auth/web3auth-android-sdk) for known issues + +The v10.x release provides a more robust, feature-rich, and developer-friendly experience while maintaining the core Web3Auth functionality you rely on. diff --git a/embedded-wallets/sdk/android/usage/README.mdx b/embedded-wallets/sdk/android/usage/README.mdx index 164c4537983..371447b49cb 100644 --- a/embedded-wallets/sdk/android/usage/README.mdx +++ b/embedded-wallets/sdk/android/usage/README.mdx @@ -16,10 +16,10 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Authentication Functions -| Function Name | Description | -| ------------- | -------------------------------------------------- | -| `login()` | Logs in the user with the selected login provider. | -| `logout()` | Logs out the user from the current session. | +| Function Name | Description | +| ------------- | --------------------------------------------------------------------------------------------------- | +| `connectTo()` | Logs in the user with the selected auth connection. Supports both PnP and SFA authentication modes. | +| `logout()` | Logs out the user from the current session. | ### User Management Functions @@ -29,10 +29,10 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Private Key Functions -| Function Name | Description | -| --- | --- | -| `getPrivKey()` | Retrieve the user's secp256k1 private key for EVM-compatible chains. | -| `getEd25519PrivKey()` | Retrieve the user's ed25519 private key for chains like Solana, Near, Algorand. | +| Function Name | Description | +| ------------------------ | ------------------------------------------------------------------------------- | +| `getPrivateKey()` | Retrieve the user's secp256k1 private key for EVM-compatible chains. | +| `getEd25519PrivateKey()` | Retrieve the user's ed25519 private key for chains like Solana, Near, Algorand. | ### Security Functions @@ -43,7 +43,7 @@ For detailed usage, configuration options, and code examples, refer to the dedic ### Wallet Services Functions -| Function Name | Description | -| ------------------------ | ----------------------------------------------------------------- | -| `launchWalletServices()` | Launches the templated wallet UI in WebView. | -| `request()` | Opens templated transaction screens for signing EVM transactions. | +| Function Name | Description | +| ---------------- | ---------------------------------------------------------------------------------------------- | +| `showWalletUI()` | Launches the templated wallet UI in WebView with automatic chain configuration from dashboard. | +| `request()` | Opens templated transaction screens for signing EVM transactions with simplified parameters. | diff --git a/embedded-wallets/sdk/android/usage/connectTo.mdx b/embedded-wallets/sdk/android/usage/connectTo.mdx new file mode 100644 index 00000000000..3a4b8448f1c --- /dev/null +++ b/embedded-wallets/sdk/android/usage/connectTo.mdx @@ -0,0 +1,348 @@ +--- +title: Logging in a User +sidebar_label: connectTo +description: 'Web3Auth Android SDK - connectTo Function | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +To login a user, you can use the `connectTo` method. It will trigger the login flow and navigate the user to a browser modal allowing the user to login into the service. You can pass in the supported auth connections to the connectTo method for specific social logins such as GOOGLE, APPLE, FACEBOOK, etc., and do whitelabel login. + +## Parameters + +The `connectTo` method takes in `LoginParams` as a required input. + + + + + +| Parameter | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `authConnection` | It sets the OAuth login method to be used. You can use any of the supported values are `GOOGLE`, `FACEBOOK`, `REDDIT`, `DISCORD`, `TWITCH`, `APPLE`, `LINE`, `GITHUB`, `KAKAO`, `LINKEDIN`, `TWITTER`, `WEIBO`, `WECHAT`, `EMAIL_PASSWORDLESS`, `CUSTOM`, `SMS_PASSWORDLESS`, and `FARCASTER`. | +| `authConnectionId?` | The connection ID for custom authentication. This is optional for social logins but required for custom JWT-based authentication. | +| `groupedAuthConnectionId?` | Used for aggregate verifiers. When multiple auth connections are grouped under a single verifier, this specifies the aggregate verifier ID. | +| `loginHint?` | Provides a hint for the login process. For email passwordless, this should be the email address. For SMS passwordless, this should be the phone number. | +| `idToken?` | JWT token for SFA (Single Factor Auth) login. When provided, the login will use SFA mode. | +| `extraLoginOptions?` | It can be used to set the OAuth login options for corresponding `authConnection`. Default value for the field is `null`, and it accepts `ExtraLoginOptions` as a value. | +| `appState?` | It can be used to keep track of the app state when user will be redirected to app after login. Default is `null`, and accepts `String` as a value. | +| `mfaLevel?` | Customize the MFA screen shown to the user during OAuth authentication. Default value for field is `MFALevel.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | +| `dappShare?` | Custom verifier logins can get a dapp share returned to them post successful login. This is useful if the dapps want to use this share to allow users to login seamlessly. It accepts `String` as a value. | +| `curve?` | It will be used to determine the public key encoded in the jwt token which returned in `getUserInfo` function after user login. This parameter won't change format of private key returned by Web3Auth. Private key returned by `getPrivateKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivateKey` method. The default value is `Curve.SECP256K1`. | +| `dappUrl?` | URL of the dapp. This is used for analytics and debugging purposes. | + + + + + +```kotlin +data class LoginParams( + val authConnection: AuthConnection, + val authConnectionId: String? = null, + val groupedAuthConnectionId: String? = null, + val appState: String? = null, + val mfaLevel: MFALevel? = null, + val extraLoginOptions: ExtraLoginOptions? = null, + var dappShare: String? = null, + val curve: Curve? = Curve.SECP256K1, + var dappUrl: String? = null, + var loginHint: String? = null, + val idToken: String? = null, +) + +enum class AuthConnection { + @SerializedName("google") + GOOGLE, + @SerializedName("facebook") + FACEBOOK, + @SerializedName("reddit") + REDDIT, + @SerializedName("discord") + DISCORD, + @SerializedName("twitch") + TWITCH, + @SerializedName("apple") + APPLE, + @SerializedName("line") + LINE, + @SerializedName("github") + GITHUB, + @SerializedName("kakao") + KAKAO, + @SerializedName("linkedin") + LINKEDIN, + @SerializedName("twitter") + TWITTER, + @SerializedName("weibo") + WEIBO, + @SerializedName("wechat") + WECHAT, + @SerializedName("email_passwordless") + EMAIL_PASSWORDLESS, + @SerializedName("custom") + CUSTOM, //for jwt + @SerializedName("sms_passwordless") + SMS_PASSWORDLESS, + @SerializedName("farcaster") + FARCASTER +} +``` + + + + +## Usage + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) +) +// focus-end +``` + +## Examples + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.GOOGLE) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.FACEBOOK) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.DISCORD) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.TWITCH) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.EMAIL_PASSWORDLESS, + loginHint = "hello@web3auth.io" + ) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.SMS_PASSWORDLESS, + loginHint = "+91-9911223344" + ) +) +// focus-end +``` + + + + + +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams(AuthConnection.FARCASTER) +) +// focus-end +``` + + + + + +```kotlin title="Usage" +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + web3AuthNetwork = Web3AuthNetwork.MAINNET, + redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", + ) +) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.connectTo( + LoginParams( + AuthConnection.CUSTOM, + authConnectionId = "your_auth_connection_id", + idToken = "your_jwt_token" + ) +) +// focus-end +``` + + + diff --git a/embedded-wallets/sdk/android/usage/getEd25519PrivKey.mdx b/embedded-wallets/sdk/android/usage/getEd25519PrivateKey.mdx similarity index 57% rename from embedded-wallets/sdk/android/usage/getEd25519PrivKey.mdx rename to embedded-wallets/sdk/android/usage/getEd25519PrivateKey.mdx index 4af0c9009d8..93a6968b37a 100644 --- a/embedded-wallets/sdk/android/usage/getEd25519PrivKey.mdx +++ b/embedded-wallets/sdk/android/usage/getEd25519PrivateKey.mdx @@ -1,15 +1,15 @@ --- title: Ed25519 Private Key -sidebar_label: getEd25519PrivKey -description: 'Web3Auth Android SDK - getEd25519PrivKey Function | Embedded Wallets' +sidebar_label: getEd25519PrivateKey +description: 'Web3Auth Android SDK - getEd25519PrivateKey Function | Embedded Wallets' --- -To retrieve the secp256k1 private key of the user., use `getEd25519PrivKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. +To retrieve the Ed25519 private key of the user, use `getEd25519PrivateKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. ## Usage ```kotlin -val privateKey = web3Auth.getEd25519PrivKey() +val privateKey = web3Auth.getEd25519PrivateKey() ``` :::note diff --git a/embedded-wallets/sdk/android/usage/getPrivKey.mdx b/embedded-wallets/sdk/android/usage/getPrivKey.mdx deleted file mode 100644 index 1a0f053f436..00000000000 --- a/embedded-wallets/sdk/android/usage/getPrivKey.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Secp256k1 Private Key -sidebar_label: getPrivKey -description: 'Web3Auth Android SDK - getPrivKey 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() -``` - -:::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). - -::: diff --git a/embedded-wallets/sdk/android/usage/getPrivateKey.mdx b/embedded-wallets/sdk/android/usage/getPrivateKey.mdx new file mode 100644 index 00000000000..dee3e55b91c --- /dev/null +++ b/embedded-wallets/sdk/android/usage/getPrivateKey.mdx @@ -0,0 +1,19 @@ +--- +title: Secp256k1 Private Key +sidebar_label: getPrivateKey +description: 'Web3Auth Android SDK - getPrivateKey Function | Embedded Wallets' +--- + +To retrieve the secp256k1 private key of the user, use `getPrivateKey` method. The method returns an EVM compatible private key which can be used to sign transactions on EVM compatible chains. + +## Usage + +```kotlin +val privateKey = web3Auth.getPrivateKey() +``` + +:::note + +Web3Auth supports two widely used cryptographic curves, Secp256k1 and Ed25519, making it chain-agnostic and compatible with multiple blockchain networks. [Learn more about how to connect different blockchains](/embedded-wallets/connect-blockchain). + +::: diff --git a/embedded-wallets/sdk/android/usage/launchWalletServices.mdx b/embedded-wallets/sdk/android/usage/launchWalletServices.mdx deleted file mode 100644 index 6bc3421497c..00000000000 --- a/embedded-wallets/sdk/android/usage/launchWalletServices.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Launch Wallet Services -sidebar_label: launchWalletServices -description: 'Web3Auth Android SDK - launchWalletServices 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. - -:::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**. - -::: - -![Wallet Services](/img/embedded-wallets/wallet-services/mobile-wallet-services.png) - -## Parameters - - - - - -| 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. (eg: `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` & `chainId`. | -| `rpcTarget` | RPC Target URL for the selected `chainNamespace` & `chainId`. | -| `ticker?` | Default currency ticker of the network (e.g: `ETH`) | -| `tickerName?` | Name for currency ticker (e.g: `Ethereum`) | - - - - - -```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, -) -``` - - - - -## Usage - -```kotlin -val chainConfig = ChainConfig( - chainId = "0x1", - rpcTarget = "https://rpc.ethereum.org", - ticker = "ETH", - chainNamespace = ChainNamespace.EIP155 -) - -// focus-start -val completableFuture = web3Auth.launchWalletServices( - chainConfig -) -// focus-end -``` diff --git a/embedded-wallets/sdk/android/usage/login.mdx b/embedded-wallets/sdk/android/usage/login.mdx deleted file mode 100644 index ced7ce8edc6..00000000000 --- a/embedded-wallets/sdk/android/usage/login.mdx +++ /dev/null @@ -1,316 +0,0 @@ ---- -title: Logging in a User -sidebar_label: login -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, etc., 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 `String` as a value. | -| `mfaLevel?` | Customize the MFA screen shown to the user during OAuth authentication. Default value for field is `MFALevel.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | -| `dappShare?` | Custom verifier logins can get a dapp share returned to them post successful login. This is useful if the dapps want to use this share to allow users to login seamlessly. It accepts `String` as a value. | -| `curve?` | It will be used to determine the public key encoded in the jwt token which returned in `getUserInfo` function after user login. This parameter won't change format of private key returned by 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 over your Web3Auth Client ID from Developer Dashboard - 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 over your Web3Auth Client ID from Developer Dashboard - 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 over your Web3Auth Client ID from Developer Dashboard - 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 over your Web3Auth Client ID from Developer Dashboard - 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 over your Web3Auth Client ID from Developer Dashboard - 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 over your Web3Auth Client ID from Developer Dashboard - 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 over your Web3Auth Client ID from Developer Dashboard 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 over your Web3Auth Client ID from Developer Dashboard - 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 over your Web3Auth Client ID from Developer Dashboard - 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 = "your_jwt_token") - ) -) -// focus-end -``` - - - diff --git a/embedded-wallets/sdk/android/usage/request.mdx b/embedded-wallets/sdk/android/usage/request.mdx index 15864a9281a..b9352469adc 100644 --- a/embedded-wallets/sdk/android/usage/request.mdx +++ b/embedded-wallets/sdk/android/usage/request.mdx @@ -14,12 +14,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 @@ -28,16 +55,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 ) @@ -54,6 +73,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/embedded-wallets/sdk/android/usage/showWalletUI.mdx b/embedded-wallets/sdk/android/usage/showWalletUI.mdx new file mode 100644 index 00000000000..11452567aca --- /dev/null +++ b/embedded-wallets/sdk/android/usage/showWalletUI.mdx @@ -0,0 +1,76 @@ +--- +title: Show Wallet UI +sidebar_label: showWalletUI +description: 'Web3Auth Android SDK - showWalletUI Function | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +The `showWalletUI` method launches a WebView which allows you to use the templated wallet UI services. The method automatically uses the chain configuration from your project settings and no longer requires 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**. + +::: + +![Wallet Services](/img/embedded-wallets/wallet-services/mobile-wallet-services.png) + +:::warning + +The chain configuration is now automatically retrieved from your project settings in the Web3Auth Dashboard. Make sure your project has the appropriate chains configured in the dashboard. + +::: + +## Usage + +```kotlin +// focus-start +val completableFuture = web3Auth.showWalletUI() +// focus-end +``` + +You can also specify a custom path: + +```kotlin +// focus-start +val completableFuture = web3Auth.showWalletUI("custom-wallet-path") +// focus-end +``` + +## Smart Accounts Configuration + +When smart accounts are enabled in your Web3Auth Dashboard, the wallet UI will automatically provide account abstraction features: + +### Dashboard Configuration + +1. Navigate to your project in the [Web3Auth Dashboard](https://dashboard.web3auth.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/ew-sidebar.js b/ew-sidebar.js index 30eabd456e2..181a7623eda 100644 --- a/ew-sidebar.js +++ b/ew-sidebar.js @@ -503,6 +503,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", @@ -514,14 +515,14 @@ const sidebar = { label: "Usage", items: [ "sdk/android/usage/README", - "sdk/android/usage/login", + "sdk/android/usage/connectTo", "sdk/android/usage/getUserInfo", - "sdk/android/usage/getPrivKey", - "sdk/android/usage/getEd25519PrivKey", + "sdk/android/usage/getPrivateKey", + "sdk/android/usage/getEd25519PrivateKey", "sdk/android/usage/logout", "sdk/android/usage/enableMFA", "sdk/android/usage/manageMFA", - "sdk/android/usage/launchWalletServices", + "sdk/android/usage/showWalletUI", "sdk/android/usage/request", ], }, diff --git a/src/pages/tutorials/android-wallet.mdx b/src/pages/tutorials/android-wallet.mdx index 6bb635e769f..129c41f2df3 100644 --- a/src/pages/tutorials/android-wallet.mdx +++ b/src/pages/tutorials/android-wallet.mdx @@ -61,7 +61,7 @@ Once, you have added the JitPack repository, then in your app-level `build.gradl dependencies { // ... // focus-next-line - implementation 'com.github.web3auth:web3auth-android-sdk:7.4.0' + implementation 'com.github.web3auth:web3auth-android-sdk:10.0.0' } ``` @@ -78,9 +78,9 @@ class Web3AuthHelperImpl( private val web3Auth: Web3Auth ): Web3AuthHelper { - // Performs the login to authenticate the user with Web3Auth netowrk. - override suspend fun login(loginParams: LoginParams): CompletableFuture { - return web3Auth.login(loginParams) + // Connects to authenticate the user with Web3Auth network. + override suspend fun connectTo(loginParams: LoginParams): CompletableFuture { + return web3Auth.connectTo(loginParams) } // Logout of the current active session. @@ -90,7 +90,12 @@ class Web3AuthHelperImpl( // Returns the Ethereum compatible private key. override fun getPrivateKey(): String { - return web3Auth.getPrivkey() + return web3Auth.getPrivateKey() + } + + // Returns the Ed25519 private key for Solana and other chains. + override fun getEd25519PrivateKey(): String { + return web3Auth.getEd25519PrivateKey() } // Returns the user information such as name, email, profile image, and etc. @@ -112,7 +117,17 @@ class Web3AuthHelperImpl( } override suspend fun isUserAuthenticated(): Boolean { - return web3Auth.getPrivkey().isNotEmpty() + return web3Auth.getPrivateKey().isNotEmpty() + } + + // Shows the Wallet UI with smart account support + override suspend fun showWalletUI(): CompletableFuture { + return web3Auth.showWalletUI() + } + + // Makes a blockchain request + override suspend fun request(method: String, params: JsonArray): CompletableFuture { + return web3Auth.request(method, params) } } ``` @@ -120,6 +135,10 @@ class Web3AuthHelperImpl( Once we have the created `Web3AuthHelper`, the next is to initialize the `Web3Auth` instance in the Koin module and make it a singleton component. ```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + val appModule = module { // focus-start single { @@ -138,8 +157,8 @@ private fun getWeb3AuthHelper(context: Context): Web3AuthHelper { 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" ) ) // focus-end @@ -150,7 +169,7 @@ private fun getWeb3AuthHelper(context: Context): Web3AuthHelper { ### Session Management -To check whether the user is authenticated, you can use the `getPrivateKey` or `getEd25519PrivKey` method. For a user already authenticated, 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`, important to interact with the blockchain. Along with that, we'll retrieve user info, and navigate them to `HomeScreen`. In case of no active session, we'll navigate to `LoginScreen` to authenticate again. [Learn more about Web3Auth session management](/embedded-wallets/features/session-management). +To check whether the user is authenticated, you can use the `getPrivateKey` or `getEd25519PrivateKey` method. For a user already authenticated, 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`, important to interact with the blockchain. Along with that, we'll retrieve user info, and navigate them to `HomeScreen`. In case of no active session, we'll navigate to `LoginScreen` to authenticate again. [Learn more about Web3Auth session management](/embedded-wallets/features/session-management). Since we are using the MVVM architecture, we'll create a `ViewModel` class to encapsulate the business logic for Web3Auth and Ethereum chain interaction. @@ -214,9 +233,9 @@ class MainViewModel(private val web3AuthHelper: Web3AuthHelper) : ViewModel() { ### Authentication -If the user is not authenticated, we can utilize the `login` method to authenticate the user. For the Wallet, we will add an Email Passwordless login. We'll create a helper function, `login` inside `MainViewModel`. The login method is pretty straightforward in Web3Auth and takes `LoginParams` as input. After successfully logging in, we'll generate and prepare the `Credentials`, important to interact with the blockchain. Along with that, we'll retrieve user info, and navigate them to `HomeScreen`. +If the user is not authenticated, we can utilize the `connectTo` method to authenticate the user. For the Wallet, we will add an Email Passwordless login. We'll create a helper function, `login` inside `MainViewModel`. The connectTo method is pretty straightforward in Web3Auth and takes `LoginParams` as input. After successfully authenticating, we'll generate and prepare the `Credentials`, important to interact with the blockchain. Along with that, we'll retrieve user info, and navigate them to `HomeScreen`. -Learn more about [Web3Auth LoginParams](/embedded-wallets/sdk/android/usage/login#parameters). +Learn more about [Web3Auth LoginParams](/embedded-wallets/sdk/android/usage/connectTo#parameters). ```kotlin class MainViewModel(private val web3AuthHelper: Web3AuthHelper) : ViewModel() { @@ -225,14 +244,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 = 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() @@ -432,20 +451,20 @@ val appModule = module { // Additional code // focus-next-line - factory { EthereumUseCaseImpl(Web3j.build(HttpService(chainConfigList.first().rpcTarget))) } + factory { EthereumUseCaseImpl(Web3j.build(HttpService(chainsList.first().rpcTarget))) } // Additonal code ``` ## Set up Supported Chains -After having our blockchain UseCase in place, the next step on the list is to define the supported chains. To keep things simple, we'll simply create a new file `ChainConfigList` with an array of ChainConfig to define the supported chains. +After having our blockchain UseCase in place, the next step on the list is to define the supported chains. To keep things simple, we'll simply create a new file `ChainsList` with an array of Chains to define the supported chains. For the guide, we have added the support for Ethereum Sepolia, and Arbitrum Sepolia. If you wish to support more chains in your wallet, you can simply add the config with the required details in the list below. Along with that, you can also add the desired chain using the add custom chain feature in the app. ```kotlin -var chainConfigList = arrayOf( - ChainConfig( +var chainsList = arrayOf( + Chains( chainNamespace = ChainNamespace.EIP155, decimals = 18, blockExplorerUrl = "https://sepolia.etherscan.io/", @@ -455,7 +474,7 @@ var chainConfigList = arrayOf( ticker = "ETH", tickerName = "Ethereum" ), - ChainConfig( + Chains( chainNamespace = ChainNamespace.EIP155, decimals = 18, blockExplorerUrl = "https://sepolia.etherscan.io/", @@ -489,25 +508,25 @@ class MainViewModel(private val web3AuthHelper: Web3AuthHelper) : ViewModel() { private val _isAccountLoaded: MutableStateFlow = MutableStateFlow(false) val isAccountLoaded: StateFlow = _isAccountLoaded - // _balance holds the user's balance for the selected ChainConfig. + // _balance holds the user's balance for the selected Chains. private val _balance: MutableStateFlow = MutableStateFlow("0.0") val balance: StateFlow = _balance - // Currently selected ChainConfig by the user. By default, it would be the first ChainConfig + // Currently selected Chains by the user. By default, it would be the first Chains // in the list. - private val _selectedChain: MutableStateFlow = MutableStateFlow(chainConfigList[0]) - val selectedChain: StateFlow = _selectedChain + private val _selectedChain: MutableStateFlow = MutableStateFlow(chainsList[0]) + val selectedChain: StateFlow = _selectedChain // Credentials will be used to retrive user's EOA address, and sign the transactions. lateinit var credentials: Credentials lateinit var userInfo: UserInfo - // EthereumUseCaseImpl to interact with the selected Ethereum ChainConfig. + // EthereumUseCaseImpl to interact with the selected Ethereum Chains. private var ethereumUseCase: EthereumUseCase = EthereumUseCaseImpl( Web3j.build( HttpService( - chainConfigList.first().rpcTarget + chainsList.first().rpcTarget ) ) ) @@ -537,7 +556,7 @@ class MainViewModel(private val web3AuthHelper: Web3AuthHelper) : ViewModel() { // Defined previously } - // Retrieves user's balance for the currently selected ChainConfig. + // Retrieves user's balance for the currently selected Chains. fun getBalance() { viewModelScope.launch { _isAccountLoaded.emit(false) @@ -589,8 +608,8 @@ class MainViewModel(private val web3AuthHelper: Web3AuthHelper) : ViewModel() { } } - // Changes the currently selected ChainConfig. - fun changeChainConfig(config: ChainConfig) { + // Changes the currently selected Chains. + fun changeChainConfig(config: Chains) { _selectedChain.value = config ethereumUseCase = EthereumUseCaseImpl( Web3j.build( @@ -775,7 +794,7 @@ fun AccountView(viewModel: MainViewModel) { expanded = expanded, onDismissRequest = { expanded = false } ) { - chainConfigList.forEach { item -> + chainsList.forEach { item -> DropdownMenuItem( text = { Text(text = item.displayName!!) }, onClick = { @@ -1083,8 +1102,62 @@ fun WriteContractView(viewModel: MainViewModel) { } ``` +## Advanced Features + +### Smart Accounts (ERC-4337) + +Web3Auth Android SDK v10.x includes built-in support for smart accounts. When enabled in your dashboard, users automatically get smart contract wallets with advanced features: + +```kotlin +// Check if smart accounts are enabled +val userInfo = web3AuthHelper.getUserInfo() +if (userInfo.isSmartAccountEnabled) { + val smartAccountAddress = userInfo.smartAccountAddress + Log.d("Smart Account", "Address: $smartAccountAddress") + + // Use smart account for gasless transactions + val userOp = buildUserOperation(smartAccountAddress, transaction) + web3AuthHelper.request("eth_sendUserOperation", userOp) +} +``` + +### Using Web3Auth Wallet Services + +The SDK also provides access to Web3Auth's built-in wallet UI: + +```kotlin +// Show the wallet UI with smart account support +fun showWallet() { + viewModelScope.launch { + try { + web3AuthHelper.showWalletUI().await() + // Wallet UI will handle transactions, gas sponsorship, and more + } catch (e: Exception) { + Log.e("Wallet", "Error showing wallet: ${e.message}") + } + } +} + +// Request signatures through wallet services +fun requestSignature(method: String, params: JsonArray) { + viewModelScope.launch { + val result = web3AuthHelper.request(method, params).await() + if (result.success) { + Log.d("Signature", result.result ?: "") + } + } +} +``` + ## Conclusion -Voila, you have build a Ethereum Web3 wallet. This guide only gives you an overview of how to create your wallet with Ethereum ecosystem support. The general idea of the guide can be used for any of the blockchain ecosystem. +Voila, you have built an Ethereum Web3 wallet using Web3Auth Android SDK v10.x! This guide gives you an overview of how to create your wallet with Ethereum ecosystem support, including the latest features like smart accounts and simplified wallet services. The general idea of the guide can be used for any blockchain ecosystem. + +### Key Takeaways + +- **Simplified Authentication**: The new `connectTo` method supports both PnP and SFA modes +- **Smart Account Support**: Automatic ERC-4337 account abstraction when enabled +- **Improved Developer Experience**: Cleaner APIs and better type safety +- **Built-in Wallet UI**: Access to Web3Auth's wallet services without additional configuration If you are interested in learning more about Web3Auth, please checkout our [documentation for Android](/embedded-wallets/sdk/android). You can find the code used for the guide on our [examples repo](https://github.com/Web3Auth/web3auth-android-examples/tree/main/android-playground). diff --git a/src/utils/w3a-sdk-map.js b/src/utils/w3a-sdk-map.js index 97d7c1365bc..84940f06eed 100644 --- a/src/utils/w3a-sdk-map.js +++ b/src/utils/w3a-sdk-map.js @@ -14,25 +14,13 @@ export const unity = 'Unity' export const unreal = 'Unreal Engine' export const pnpWebVersion = `10.0.x` -export const pnpAndroidVersion = `9.1.2` +export const pnpAndroidVersion = `10.0.x` export const pnpIOSVersion = `11.1.0` export const pnpRNVersion = `8.1.x` export const pnpFlutterVersion = `6.1.2` export const pnpUnityVersion = `7.0.x` export const pnpUnrealVersion = `4.1.x` -export const sfaWebVersion = `9.2.x` -export const sfaAndroidVersion = `4.0.1` -export const sfaIOSVersion = `9.1.0` -export const sfaRNVersion = `2.0.x` -export const sfaFlutterVersion = `6.0.0` -export const sfaNodeJSVersion = `7.4.x` -export const tkeyJSVersion = `15.x.x` -export const tkeyAndroidVersion = `0.0.5` -export const tkeyIOSVersion = `0.0.4` -export const mpcCoreKitJSVersion = `3.4.x` -export const mpcCoreKitReactNativeVersion = `1.0.0` - export function getPnPVersion(platform) { if (platform === web) { return pnpWebVersion @@ -55,28 +43,4 @@ export function getPnPVersion(platform) { if (platform === unreal) { return pnpUnrealVersion } -} - -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 - } -} +} \ No newline at end of file