> For the complete documentation index, see [llms.txt](/llms.txt). # Advanced configuration The Embedded Wallets SDK offers configuration options to customize authentication flows, UI appearance, blockchain integrations, and security features for your dapp. ## Configuration structure Pass options to the `Web3Auth` constructor during setup: ```swift import Web3Auth web3Auth = try await Web3Auth( options: Web3AuthOptions( clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets dashboard web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET redirectUrl: "com.yourapp.bundleid://auth" ) ) ``` ### `Web3AuthOptions` The constructor takes a `Web3AuthOptions` struct as input. **Table** **Basic parameters:** | Parameter | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | Your Web3Auth Client ID from the [Dashboard](https://developer.metamask.io/). It's a mandatory field of type `String`. | | `web3AuthNetwork` | Web3Auth Network: `.SAPPHIRE_MAINNET`, `.SAPPHIRE_DEVNET`, `.MAINNET`, `.CYAN`, `.AQUA`, or `.TESTNET`. Mandatory field of type `Web3AuthNetwork`. | | `redirectUrl` | URL that Web3Auth will redirect API responses upon successful authentication. It's a mandatory field of type `String`. | | `sessionTime?` | Session duration in seconds. Default is `86400 * 30` (30 days). Maximum is 30 days. | | `useSFAKey?` | Use SFA key to get single factor auth key. Default is `false`. Useful for wallet pre-generation and SFA mode. | | `defaultChainId?` | Default chain ID to use. Default is `"0x1"` (Ethereum mainnet). | | `enableLogging?` | Enable SDK logging. Default is `false`. | **Advanced parameters:** | Parameter | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `whiteLabel?` | Whitelabel options for custom UI, branding, and translations. Takes `WhiteLabelData` as a value. | | `authConnectionConfig?` | Auth connection config for custom auth connections. Takes `[AuthConnectionConfig]` as a value. | | `mfaSettings?` | Configure MFA settings for authentication. Takes `MfaSettings` as a value. | | `chains?` | Custom chain configuration for blockchain networks. Takes `[Chains]` as a value. See [Chains configuration](#chains-configuration) below. | | `walletServicesConfig?` | Configuration for Wallet Services including whitelabel options. Takes `WalletServicesConfig` as a value. | **Struct** ```swift public struct Web3AuthOptions: Codable { let clientId: String var redirectUrl: String let authBuildEnv: BuildEnv? var authConnectionConfig: [AuthConnectionConfig]? var whiteLabel: WhiteLabelData? var chains: [Chains]? var defaultChainId: String? let enableLogging: Bool? let sessionTime: Int var web3AuthNetwork: Web3AuthNetwork var useSFAKey: Bool? var walletServicesConfig: WalletServicesConfig? var mfaSettings: MfaSettings? } ``` ## Session management Control how long users stay authenticated and how sessions persist. The session key is stored in the device's encrypted Keychain. **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`). ```swift web3Auth = try await Web3Auth( options: Web3AuthOptions( clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets dashboard web3AuthNetwork: .SAPPHIRE_MAINNET, redirectUrl: "com.yourapp.bundleid://auth", sessionTime: 86400 * 7 // 7 days (in seconds) ) ) ``` ## Chains configuration The `chains` parameter lets you specify custom blockchain networks for the SDK. When set, these chains are 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 `.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 ```swift public struct Chains: Codable { public let chainNamespace: ChainNamespace public let decimals: Int? public let blockExplorerUrl: String? public let chainId: String? public let displayName: String? public let logo: String? public let rpcTarget: String public let ticker: String? public let tickerName: String? } ``` ### Example ```swift web3Auth = try await Web3Auth( options: Web3AuthOptions( clientId: "YOUR_WEB3AUTH_CLIENT_ID", web3AuthNetwork: .SAPPHIRE_MAINNET, redirectUrl: "com.yourapp.bundleid://auth", chains: [ Chains( chainId: "0x89", rpcTarget: "https://rpc.ankr.com/polygon", displayName: "Polygon Mainnet", ticker: "MATIC", tickerName: "Matic", blockExplorerUrl: "https://polygonscan.com" ) ] ) ) ``` ## Wallet Services configuration The `walletServicesConfig` parameter in `Web3AuthOptions` customizes the behavior of the wallet UI (`showWalletUI`) and request signing (`request`). For full configuration options, see the [Wallet Services](/embedded-wallets/sdk/ios/advanced/wallet-services/) section. | Parameter | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy`. Default is `.defaultStrategy`. | | `whiteLabel?` | Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts `WhiteLabelData`. | ```swift web3Auth = try await Web3Auth( options: Web3AuthOptions( clientId: "YOUR_WEB3AUTH_CLIENT_ID", web3AuthNetwork: .SAPPHIRE_MAINNET, redirectUrl: "com.yourapp.bundleid://auth", walletServicesConfig: WalletServicesConfig( confirmationStrategy: .modal ) ) ) ``` ## 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/ios/advanced/custom-authentication/) section. ## UI customization Customize the Embedded Wallets sign-in screens to match your dapp's design. For complete customization options, see [Whitelabeling and UI customization](/embedded-wallets/sdk/ios/advanced/whitelabel/). ## Multi-Factor Authentication Add security layers to protect user accounts with two-factor authentication. For detailed configuration options and implementation examples, see [Multi-Factor Authentication](/embedded-wallets/sdk/ios/advanced/mfa/). **Key configuration options:** - `mfaSettings` - Configure MFA settings for different authentication flows - `mfaLevel` - Control when users are prompted to set up MFA