> For the complete documentation index, see [llms.txt](/llms.txt). # Advanced configuration The Embedded Wallets 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[​](#configuration-structure "Direct link to Configuration structure") When setting up Embedded Wallets, you'll pass in the options to the constructor. This consists of: ``` 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`[​](#web3authoptions "Direct link to web3authoptions") The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. - Basic Parameters - Advanced Parameters - Interface | Parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | context | Android context to launch web-based authentication, usually is the current activity. It's a mandatory field, and accepts android.content.Context as a value. | | clientId | Your Embedded Wallets Client ID. You can get it from Embedded Wallets [dashboard](https://developer.metamask.io/) under project details. It's a mandatory field of type String | | web3AuthNetwork | Defines the Embedded Wallets Network. It's a mandatory field of type Web3AuthNetwork. | | redirectUrl | URL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type String. | | sessionTime? | Allows developers to configure the session management time. Session time is in seconds, default is 86400 * 30 (30 days). sessionTime can be max 30 days. | | useSFAKey? | Use SFA key to get single factor auth key. It's an optional field with default value as false. Useful for pre-generated wallets and SFA mode. | | chains? | Custom chain configuration for blockchain networks. It takes Chains as a value. See [Chains configuration](#chains-configuration) below. | | defaultChainId? | Default chain ID to use. It's an optional field with a default value of "0x1" (Ethereum mainnet). The first chain from the project config will be used if the project has chains configured. | | enableLogging? | Setting to true will enable logs. It's an optional field with default value as false. | | Parameter | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | whiteLabel? | Whitelabel options for Embedded Wallets. It helps you define custom UI, branding, and translations for your brand app. It takes WhiteLabelData as a value. | | 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. | ``` data class Web3AuthOptions( val clientId: String, var redirectUrl: String, @SerializedName("network") val web3AuthNetwork: Web3AuthNetwork, @SerializedName("buildEnv") var authBuildEnv: BuildEnv = BuildEnv.PRODUCTION, var whiteLabel: WhiteLabelData? = null, var authConnectionConfig: List? = emptyList(), val useSFAKey: Boolean? = false, var chains: Chains? = null, var mfaSettings: MfaSettings? = null, val sessionTime: Int = 30 * 86400, val walletServicesConfig: WalletServicesConfig? = null, var defaultChainId: String? = "0x1", var enableLogging: Boolean = false ) ``` ## Session management[​](#session-management "Direct link 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`). ``` 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[​](#chains-configuration "Direct link to 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[​](#chains-fields "Direct link to 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[​](#interface "Direct link to Interface") ``` 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[​](#example "Direct link to Example") ``` 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[​](#custom-authentication-methods "Direct link to 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[​](#ui-customization "Direct link to 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[​](#multi-factor-authentication "Direct link to 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[​](#wallet-services-configuration "Direct link to Wallet Services Configuration") The `walletServicesConfig` parameter in `Web3AuthOptions` allows you to customize the behavior of the wallet UI (`showWalletUI`) and request signing (`request`). For full configuration options, see the [Smart Accounts](/embedded-wallets/sdk/android/advanced/smart-accounts/) section. | Parameter | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | confirmationStrategy? | Controls how transaction confirmations are displayed. Accepts ConfirmationStrategy enum. Default is ConfirmationStrategy.DEFAULT. | | whiteLabel? | Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts WhiteLabelData as value. | ``` val web3Auth = Web3Auth( Web3AuthOptions( clientId = "YOUR_WEB3AUTH_CLIENT_ID", web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET, redirectUrl = "YOUR_APP_SCHEME://auth", walletServicesConfig = WalletServicesConfig( confirmationStrategy = ConfirmationStrategy.MODAL ) ), this ) ```