> For the complete documentation index, see [llms.txt](/llms.txt). # Advanced configuration The Web3Auth by MetaMask, Embedded Wallet SDK provides extensive configuration options that allow you to customize authentication flows, UI appearance, blockchain integrations, and security features to meet your application's specific requirements. ## Configuration structure When setting up Embedded Wallets, you'll pass in the options to the constructor. This consists of: ```kotlin import com.web3auth.core.Web3Auth import com.web3auth.core.types.Web3AuthOptions import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork var web3Auth = Web3Auth( Web3AuthOptions( clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ), this ) // Handle user signing in when app is in background web3Auth.setResultUrl(intent?.data) ``` ### `Web3AuthOptions` The `Web3Auth` constructor takes a `Web3AuthOptions` object and an Android `Context` (usually the current activity) as input. **Basic Parameters** | Parameter | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | Your Embedded Wallets Client ID. You can get it from Embedded Wallets [dashboard](https://developer.metamask.io/) under project details. It's a mandatory field of type `String` | | `web3AuthNetwork` | Defines the Embedded Wallets Network. It's a mandatory field of type `Web3AuthNetwork`. | | `redirectUrl` | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type `String`. | | `sessionTime?` | Session duration in seconds. Default is 30 days (`86400 * 30`), which is also the maximum. If you leave it unset, `initialize()` uses the session time configured in your dashboard project instead. | | `useSFAKey?` | Use SFA key to get single factor auth key. It's an optional field with default value as `false`. Useful for pre-generated wallets and SFA mode. | | `chains?` | Custom chain configuration for blockchain networks. It takes `Chains` as a value. See [Chains configuration](#chains-configuration) below. | | `defaultChainId?` | Default chain ID to use. It's an optional field with a default value of `"0x1"` (Ethereum mainnet). The first chain from the project config will be used if the project has chains configured. | | `enableLogging?` | Setting to true will enable logs. It's an optional field with default value as `false`. | | `authBuildEnv?` | Auth environment to use. Accepts `BuildEnv.PRODUCTION` (default), `BuildEnv.STAGING`, or `BuildEnv.TESTING`. Use `PRODUCTION` unless the MetaMask team instructs otherwise. | **Advanced Parameters** | Parameter | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `whiteLabel?` | Whitelabel options for Embedded Wallets. It helps you define custom UI, branding, and translations for your brand app. It takes `WhiteLabelData` as a value. | | `authConnectionConfig?` | Auth connection config for the custom auth connections. It takes `List` as a value. | | `mfaSettings?` | Allows developers to configure the MFA settings for authentication. It takes `MfaSettings` as a value. | | `walletServicesConfig?` | Configuration for Wallet Services including whitelabel options. It takes `WalletServicesConfig` as a value. | **Interface** ```kotlin data class Web3AuthOptions( val clientId: String, var redirectUrl: String, var originData: Map? = null, @SerializedName("buildEnv") var authBuildEnv: BuildEnv = BuildEnv.PRODUCTION, var sdkUrl: String = getSdkUrl(authBuildEnv), var storageServerUrl: String? = null, var sessionSocketUrl: String? = null, var citadelServerUrl: String? = null, var authConnectionConfig: List? = emptyList(), var whiteLabel: WhiteLabelData? = null, var dashboardUrl: String? = getDashboardUrl(authBuildEnv), var accountAbstractionConfig: String? = null, var walletSdkUrl: String? = getWalletSdkUrl(authBuildEnv), var includeUserDataInToken: Boolean? = true, var chains: Chains? = null, var defaultChainId: String? = "0x1", var enableLogging: Boolean = false, var sessionTime: Int? = null, @SerializedName("network") val web3AuthNetwork: Web3AuthNetwork, val useSFAKey: Boolean? = false, var walletServicesConfig: WalletServicesConfig? = null, var mfaSettings: MfaSettings? = null, var sessionNamespace: String? = null, var wsEmbedDappClientId: String? = null, var useAAWithExternalWallet: Boolean? = null, ) ``` The SDK derives the service URLs (`sdkUrl`, `walletSdkUrl`, `dashboardUrl`, `storageServerUrl`, `sessionSocketUrl`, and `citadelServerUrl`) from `authBuildEnv`. Don't override them unless the MetaMask team instructs you to. ## Session management Control how long users stay authenticated and how sessions persist. The session key is stored in the device's encrypted Keystore. **Key Configuration Options:** - `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to sign in again. - Minimum: 1 second (`1`). - Maximum: 30 days (`86400 * 30`). - Default: 30 days (`86400 * 30`). If you leave `sessionTime` unset, `initialize()` uses the session time configured in your dashboard project instead. ```kotlin var web3Auth = Web3Auth( Web3AuthOptions( clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, sessionTime = 86400 * 7, // 7 days (in seconds) redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth", ), this ) ``` ## Chains Configuration The `chains` parameter lets you specify a custom blockchain network for the SDK. When set, this chain is used by Wallet Services (`showWalletUI`, `request`) in addition to any chains configured in the project dashboard. ### `Chains` Fields | Field | Type | Required | Description | | ------------------ | ---------------- | -------- | --------------------------------------------------------------------------------------------------- | | `chainId` | `String` | Yes | Chain ID in hex format (for example, `"0x1"` for Ethereum mainnet, `"0x89"` for Polygon). | | `rpcTarget` | `String` | Yes | RPC endpoint URL for the chain. | | `chainNamespace` | `ChainNamespace` | No | Namespace of the chain. Accepts `ChainNamespace.EIP155`, `SOLANA`, or `OTHER`. Default is `EIP155`. | | `decimals` | `Int?` | No | Number of decimals for the native token. Default is `18`. | | `blockExplorerUrl` | `String?` | No | URL of the block explorer for this chain. | | `displayName` | `String?` | No | Human-readable name for the chain. | | `logo` | `String?` | No | URL of the chain's logo image. | | `ticker` | `String?` | No | Ticker symbol for the native token (for example, `"ETH"`). | | `tickerName` | `String?` | No | Full name of the native token (for example, `"Ethereum"`). | ### Interface ```kotlin data class Chains( val chainNamespace: ChainNamespace = ChainNamespace.EIP155, val decimals: Int? = 18, val blockExplorerUrl: String? = null, val chainId: String, val displayName: String? = null, val logo: String? = null, val rpcTarget: String, val ticker: String? = null, val tickerName: String? = null, ) ``` ### Example ```kotlin val web3Auth = Web3Auth( Web3AuthOptions( clientId = "YOUR_WEB3AUTH_CLIENT_ID", web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "YOUR_APP_SCHEME://auth", chains = Chains( chainId = "0x89", rpcTarget = "https://rpc.ankr.com/polygon", displayName = "Polygon Mainnet", ticker = "MATIC", tickerName = "Matic", blockExplorerUrl = "https://polygonscan.com" ) ), this ) ``` ## Custom authentication methods Control the sign-in options presented to your users. For detailed configuration options and implementation examples, see the [custom authentication](/embedded-wallets/sdk/android/advanced/custom-authentication/) section. ## UI customization Customize the brand experience by customizing the Embedded Wallets sign-in screens to match your application's design. For complete customization options, refer to the [Whitelabeling & UI Customization](/embedded-wallets/sdk/android/advanced/whitelabel/) section. ## Multi-Factor Authentication Add additional security layers to protect user accounts with two-factor authentication. For detailed configuration options and implementation examples, see the [Multi-Factor Authentication](/embedded-wallets/sdk/android/advanced/mfa/) section. **Key Configuration Options:** - `mfaSettings` - Configure MFA settings for different authentication flows - `mfaLevel` - Control when users are prompted to set up MFA ## Wallet Services Configuration The `walletServicesConfig` parameter in `Web3AuthOptions` allows you to customize the behavior of the wallet UI (`showWalletUI`) and request signing (`request`). During `initialize()`, the SDK merges the Wallet UI settings from your dashboard into this config; values you set in code take precedence. For full configuration options, see the [Smart Accounts](/embedded-wallets/sdk/android/advanced/smart-accounts/) section. | Parameter | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy` enum. Default is `null`, which uses the dashboard's confirmation modal setting, or `DEFAULT` if none is set. | | `whiteLabel?` | Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as value. | | `enableKeyExport?` | Whether users can export their private key from the wallet UI. Default is `null`, which uses the dashboard's key export setting. | ```kotlin val web3Auth = Web3Auth( Web3AuthOptions( clientId = "YOUR_WEB3AUTH_CLIENT_ID", web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "YOUR_APP_SCHEME://auth", walletServicesConfig = WalletServicesConfig( confirmationStrategy = ConfirmationStrategy.MODAL ) ), this ) ```