From 910f265a90a658fced3ad7cc7bc32e840391607a Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Thu, 2 Jul 2026 20:35:29 +0400 Subject: [PATCH 01/24] fix --- embedded-wallets/sdk/ios/README.mdx | 170 +++--- embedded-wallets/sdk/ios/advanced/README.mdx | 176 ++++-- .../ios/advanced/custom-authentication.mdx | 547 +++++++++--------- .../sdk/ios/advanced/dapp-share.mdx | 78 +-- embedded-wallets/sdk/ios/advanced/mfa.mdx | 156 ++--- .../sdk/ios/advanced/smart-accounts.mdx | 176 ++++++ .../sdk/ios/advanced/whitelabel.mdx | 42 +- .../ios/migration-guides/ios-v11-to-v12.mdx | 270 +++++++++ embedded-wallets/sdk/ios/usage/README.mdx | 20 +- embedded-wallets/sdk/ios/usage/connectTo.mdx | 295 ++++++++++ embedded-wallets/sdk/ios/usage/enable-mfa.mdx | 34 +- .../sdk/ios/usage/get-ed25519-private-key.mdx | 13 - .../sdk/ios/usage/get-private-key.mdx | 13 - .../sdk/ios/usage/get-user-info.mdx | 18 +- .../sdk/ios/usage/getEd25519PrivateKey.mdx | 15 + .../sdk/ios/usage/getPrivateKey.mdx | 15 + .../sdk/ios/usage/launch-wallet-services.mdx | 88 --- embedded-wallets/sdk/ios/usage/login.mdx | 272 --------- embedded-wallets/sdk/ios/usage/manage-mfa.mdx | 27 +- embedded-wallets/sdk/ios/usage/request.mdx | 60 +- .../sdk/ios/usage/showWalletUI.mdx | 45 ++ ew-sidebar.js | 9 +- vercel.json | 26 +- 23 files changed, 1558 insertions(+), 1007 deletions(-) create mode 100644 embedded-wallets/sdk/ios/advanced/smart-accounts.mdx create mode 100644 embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx create mode 100644 embedded-wallets/sdk/ios/usage/connectTo.mdx delete mode 100644 embedded-wallets/sdk/ios/usage/get-ed25519-private-key.mdx delete mode 100644 embedded-wallets/sdk/ios/usage/get-private-key.mdx create mode 100644 embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx create mode 100644 embedded-wallets/sdk/ios/usage/getPrivateKey.mdx delete mode 100644 embedded-wallets/sdk/ios/usage/launch-wallet-services.mdx delete mode 100644 embedded-wallets/sdk/ios/usage/login.mdx create mode 100644 embedded-wallets/sdk/ios/usage/showWalletUI.mdx diff --git a/embedded-wallets/sdk/ios/README.mdx b/embedded-wallets/sdk/ios/README.mdx index f9897800f66..cabee68369b 100644 --- a/embedded-wallets/sdk/ios/README.mdx +++ b/embedded-wallets/sdk/ios/README.mdx @@ -42,7 +42,7 @@ Install the Web3Auth iOS SDK using one of the following methods: https://github.com/Web3Auth/web3auth-swift-sdk ``` - From the **Dependency Rule** dropdown, select **Exact Version** and enter **11.1.0** as the version. + From the **Dependency Rule** dropdown, select **Exact Version** and enter **12.0.1** as the version. 3. When finished, Xcode will automatically begin resolving and downloading your dependencies in the background. @@ -53,7 +53,7 @@ To install the Embedded Wallets SDK using CocoaPods, follow the steps: 1. Open the Podfile, and add the Embedded Wallets pod: ```sh -pod 'Web3Auth', '~> 11.1.0' +pod 'Web3Auth', '~> 12.0.1' ``` 2. Once added, use `pod install` command to download the Embedded Wallets dependency. @@ -67,48 +67,34 @@ To use Embedded Wallets for iOS you need to allowlist your `bundleId` in your Em ## Initialize Embedded Wallets -### Configure Redirection +The iOS SDK uses an async initializer. The constructor fetches project configuration and restores any active session automatically. There is no separate `initialize()` call. -To use Web3Auth for iOS you need to allowlist your `bundleId` in your Web3Auth project. - -- Go to [Embedded Wallets developer dashboard](https://developer.metamask.io), and create or open an existing Embedded Wallets project. -- Allowlist `{bundleId}://auth` in the developer dashboard. This step is mandatory for the redirect to work. - -### 1. Create an Embedded Wallets instance +### Create and initialize an Embedded Wallets instance Import and configure Web3Auth in your application: ```swift import Web3Auth -class ViewController: UIViewController { +class ViewModel: ObservableObject { var web3Auth: Web3Auth? - override func viewDidLoad() { - super.viewDidLoad() - - // Configure Web3Auth - web3Auth = Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard - network: .sapphire_mainnet, // or .sapphire_devnet - redirectUrl: "com.yourapp.bundleid://auth" - )) - } -} -``` - -### 2. Initialize the Embedded Wallets instance - -Initialize the Web3Auth instance: - -```swift -override func viewDidLoad() { - super.viewDidLoad() - - Task { + func setup() async { do { - try await web3Auth?.initialize() - print("Web3Auth initialized successfully") + // focus-start + web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from MetaMask Developer Dashboard + web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET + redirectUrl: "com.yourapp.bundleid://auth" + ) + ) + // focus-end + + // Check for an active session + if web3Auth?.web3AuthResponse != nil { + // User is already logged in + } } catch { print("Error initializing Web3Auth: \(error)") } @@ -116,27 +102,11 @@ override func viewDidLoad() { } ``` -### 3. Handle URL callbacks - -Configure your application to handle URL callbacks in your `SceneDelegate`: - -```swift -import Web3Auth - -func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { - guard let url = URLContexts.first?.url else { return } - Web3Auth().setResultUrl(url: url) -} -``` +:::note -For applications using `AppDelegate`: +The async constructor throws if the project configuration fetch fails or if a stored session token is invalid. Wrap it in `do/catch` and treat any error as a failed initialization rather than an absent session. -```swift -func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool { - Web3Auth().setResultUrl(url: url) - return true -} -``` +::: ## Advanced configuration @@ -164,11 +134,13 @@ See the [advanced configuration sections](./advanced/) to learn more about each ```swift -web3Auth = Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, // or .sapphire_devnet - redirectUrl: "com.yourapp.bundleid://auth" -)) +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET + redirectUrl: "com.yourapp.bundleid://auth" + ) +) ``` @@ -176,56 +148,63 @@ web3Auth = Web3Auth(W3AInitParams( ```swift -web3Auth = Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, // or .sapphire_devnet - redirectUrl: "com.yourapp.bundleid://auth", - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.google, - clientId: "YOUR_GOOGLE_CLIENT_ID", - ) - ], - mfaSettings: MfaSettings( - deviceShareFactor: MfaSetting( - enable: true, - priority: 1 - ), - backUpShareFactor: MfaSetting( - enable: true, - priority: 2 - ), - socialBackupFactor: MfaSetting( - enable: true, - priority: 3 - ), - passwordFactor: MfaSetting( - enable: true, - priority: 4 +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET + redirectUrl: "com.yourapp.bundleid://auth", + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection: .GOOGLE, + clientId: "YOUR_GOOGLE_CLIENT_ID" + ) + ], + mfaSettings: MfaSettings( + deviceShareFactor: MfaSetting(enable: true, priority: 1), + backUpShareFactor: MfaSetting(enable: true, priority: 2), + socialBackupFactor: MfaSetting(enable: true, priority: 3), + passwordFactor: MfaSetting(enable: true, priority: 4) ) ) -)) +) ``` +## Single Factor Auth (SFA) support + +The iOS SDK includes built-in support for Single Factor Auth (SFA), allowing seamless authentication when you already have a JWT token from your own authentication system. When MFA is disabled, users are authenticated directly using your JWT token, making the login experience completely frictionless. + +```swift +// SFA login with custom JWT +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .CUSTOM, + authConnectionId: "your-auth-connection-id", + idToken: "your_jwt_token" + ) +) +``` + +SFA mode is activated automatically when you provide an `idToken` parameter. + ## Blockchain integration Embedded Wallets is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Embedded Wallets offers robust support for both **Solana** and **Ethereum**. ### Ethereum integration -For Ethereum integration, you can get the private key and use it with web3.swift or other Ethereum libraries: +For Ethereum integration, you can get the private key using the `getPrivateKey` method and use it with web3.swift or other Ethereum libraries: ```swift import web3 import Web3Auth // Use your Web3Auth instance to get the private key -val privateKey = web3Auth.getPrivKey() +let privateKey = web3Auth.getPrivateKey() // Generate the Ethereum Account let account = try EthereumAccount(privateKey) @@ -235,16 +214,14 @@ let address = account.address // Create a client let client = EthereumHttpClient( - // Please avoid using public RPC URL in production, use services - // like Infura. - url: URL.init(string: rpcUrl)!, + // Please avoid using public RPC URL in production, use services like Infura. + url: URL(string: rpcUrl)!, // Replace with the chain id of the network you want to connect to network: .custom(chainId) ) // Get the balance let balanceResponse = try await client.eth_getBalance( - // Use the address from previous step address: address, block: .Latest ) @@ -255,13 +232,13 @@ let balance = toEther(wei: balanceResponse) ### Solana integration -For Solana integration, you can get the Ed25519 private key: +For Solana integration, you can get the Ed25519 private key using the `getEd25519PrivateKey` method and use it with SolanaSwift or any other Solana libraries: ```swift import SolanaSwift // Use your Web3Auth instance to get the private key -let ed25519PrivateKey = web3Auth.getEd25519PrivKey() +let ed25519PrivateKey = try web3Auth.getEd25519PrivateKey() // Generate the KeyPair let keyPair = try KeyPair(secretKey: Data(hex: ed25519PrivateKey)) @@ -278,10 +255,9 @@ let solanaJSONRPCClient = JSONRPCAPIClient(endpoint: endpoint) // Get the balance let balanceResponse = try await solanaJSONRPCClient.getBalance( - // Use userAccount from above account: userAccount ) -// We are dividing the balance by 10^9, because Solana's token decimals is set to be 9; -let userBalance = return balanceResponse.convertToBalance(decimals: 9) +// Solana's token decimals is set to be 9 +let userBalance = balanceResponse.convertToBalance(decimals: 9) ``` diff --git a/embedded-wallets/sdk/ios/advanced/README.mdx b/embedded-wallets/sdk/ios/advanced/README.mdx index 4e002af430e..fd5d4c2026b 100644 --- a/embedded-wallets/sdk/ios/advanced/README.mdx +++ b/embedded-wallets/sdk/ios/advanced/README.mdx @@ -17,17 +17,19 @@ When setting up Web3Auth, you'll pass in the options to the constructor. This co import Web3Auth // focus-start -web3Auth = Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard - network: .sapphire_mainnet, // or .sapphire_devnet - redirectUrl: "com.yourapp.bundleid://auth" -)) +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from MetaMask Developer Dashboard + web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET + redirectUrl: "com.yourapp.bundleid://auth" + ) +) // focus-end ``` -### `W3AInitParams` +### `Web3AuthOptions` -The Web3Auth Constructor takes an object with `W3AInitParams` as input. +The Web3Auth constructor takes a `Web3AuthOptions` struct as input. -| Parameter | Description | -| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `clientId` | Your Web3Auth Client ID from the [Dashboard](https://developer.metamask.io/). It's a mandatory field of type `String`. | -| `network` | Web3Auth Network: `.sapphire_mainnet`, `.sapphire_devnet`, `.mainnet`, `.cyan`, `.aqua` or `.testnet`. Mandatory field of type `Network`. | -| `redirectUrl` | URL that Web3Auth will redirect API responses upon successful authentication. It's a mandatory field of type `String`. | -| `whiteLabel?` | Whitelabel options for custom UI, branding, and translations. Takes `W3AWhiteLabelData`` as a value. | -| `loginConfig?` | Login config for custom verifiers. Takes `[String: W3ALoginConfig]` as a value. | -| `mfaSettings?` | Configure MFA settings for authentication. Takes `MfaSettings` as a value. | -| `sessionTime?` | Configure session management time in seconds. Default is 86400 seconds (1 day). Max 30 days. | +**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 pregeneration 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. | ```swift -public struct W3AInitParams { - public let clientId: String - public let network: Network - public let redirectUrl: String - public let whiteLabel: W3AWhiteLabelData? - public let loginConfig: [String: W3ALoginConfig]? - public let useCoreKitKey: Bool? - public let chainNamespace: ChainNamespace? - public let mfaSettings: MfaSettings? - public let sessionTime: Int? - - public init( - clientId: String, - network: Network, - redirectUrl: String, - whiteLabel: W3AWhiteLabelData? = nil, - loginConfig: [String: W3ALoginConfig]? = nil, - useCoreKitKey: Bool? = nil, - chainNamespace: ChainNamespace? = .eip155, - mfaSettings: MfaSettings? = nil, - sessionTime: Int? = 86400 - ) +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? } ``` @@ -91,15 +97,95 @@ Control how long users stay authenticated and how sessions persist. The session - `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to sign in again. - Minimum: 1 second (`1`). - Maximum: 30 days (`86400 * 30`). - - Default: 7 days (`86400 * 7`). + - Default: 30 days (`86400 * 30`). + +```swift +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from MetaMask Developer 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 -web3Auth = Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard - network: .sapphire_mainnet, // or .sapphire_devnet - sessionTime: 86400 * 7, // 7 days (in seconds) - redirectUrl: "com.yourapp.bundleid://auth" -)) +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` allows you to customize the behavior of the wallet UI (`showWalletUI`) and request signing (`request`). For full configuration options, see the [Smart Accounts](./smart-accounts.mdx) 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 diff --git a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx index 7c7b5b4d574..9daec2c50a2 100644 --- a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx @@ -1,7 +1,7 @@ --- -title: Using custom authentication in PnP iOS SDK +title: Using custom authentication in iOS SDK sidebar_label: Custom authentication -description: 'Web3Auth PnP iOS SDK - Using Custom Authentication | Embedded Wallets' +description: 'Web3Auth iOS SDK - Using Custom Authentication | Embedded Wallets' --- import TabItem from '@theme/TabItem' @@ -22,7 +22,7 @@ To enable this, you need to [create a connection](/embedded-wallets/dashboard/au ::: -To configure a connection, you need to provide the particular details of the connection into our Embedded Wallets dashboard. This enables us to map a `authConnectionId` with your connection details. This `authConnectionId` helps us to identify the connection details while initializing the SDK. You can configure multiple connections for the same project, and you can also update the connection details anytime. +To configure a connection, you need to provide the particular details of the connection into our Embedded Wallets dashboard. This enables us to map an `authConnectionId` with your connection details. This `authConnectionId` helps us to identify the connection details while initializing the SDK. You can configure multiple connections for the same project, and you can also update the connection details anytime. :::tip @@ -32,21 +32,13 @@ Learn more about the [auth provider setup](/embedded-wallets/authentication) and ## Configuration -:::warning +To use custom authentication (using supported social providers or login providers like Auth0, AWS Cognito, Firebase, or your own custom JWT login), you can add the configuration using the `authConnectionConfig` parameter during the initialization. -**"Auth Connection"** is called **"Verifier"** in the Android SDK. It is the older terminology which we will be updating in the upcoming releases. - -Consequentially, you will see the terms **"Verifier ID"** and **"Aggregate Verifier"** used in the codebase and documentation referring to **"Auth Connection ID"** and **"Grouped Auth Connection"** respectively. - -::: - -To use custom authentication (using supported Social providers or Sign-in providers like Auth0, AWS Cognito, Firebase, or your own custom JWT sign-in), you can add the configuration using the `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 `W3ALoginConfig` struct. +The `authConnectionConfig` parameter is an array of `AuthConnectionConfig` instances, each defining a specific authentication connection. ### Parameters -After creating the verifier, you can use the following parameters in the `W3ALoginConfig`. +After creating the auth connection from the [Embedded Wallets developer dashboard](https://developer.metamask.io), you can use the following parameters in the `AuthConnectionConfig`. -| Parameter | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `verifier` | The name of the verifier that you have registered on the Embedded Wallets dashboard. It's a mandatory field, and it accepts a string value. | -| `typeOfLogin` | Type of login of this verifier, this value will affect the login flow that is adapted. For example, if you choose `google`, a Google sign-in flow will be used. If you choose `jwt`, you should be providing your own JWT token, no sign-in flow will be presented. It's a mandatory field, and accepts `TypeOfLogin` as a value. | -| `clientId` | Client ID provided by your login provider used for custom verifier. for example, Google's Client ID or Web3Auth's client ID if using JWT as `TypeOfLogin`. It's a mandatory field, and it accepts a string value. | -| `name?` | Display name for the verifier. If null, the default name is used. It accepts a string value. | -| `description?` | Description for the button. If provided, it renders as a full length button. else, icon button. It accepts a string value. | -| `verifierSubIdentifier?` | The field in JWT token which maps to verifier ID. Please make sure you selected correct JWT verifier ID in the developer dashboard. It accepts a string value. | -| `logoHover?` | Logo to be shown on mouse hover. It accepts a string value. | -| `logoLight?` | Light logo for dark background. It accepts a string value. | -| `logoDark?` | Dark logo for light background. It accepts a string value. | -| `mainOption?` | Show login button on the main list. It accepts a boolean value; default 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. It accepts a boolean value; default is true. | -| `showOnMobile?` | Whether to show the login button on mobile. It accepts a boolean value; default is true. | +| Parameter | Description | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `authConnectionId` | The name of the auth connection that you have registered on the Embedded Wallets dashboard. It's a mandatory field, and accepts `String` as a value. | +| `authConnection` | Type of login of this auth connection. 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. For example, Google's Client ID or Web3Auth's Client ID if using `.CUSTOM` as `AuthConnection`. It's a mandatory field, and accepts `String` as a value. | +| `name?` | Display name for the auth connection. If nil, 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 the correct JWT auth connection ID in the developer dashboard. It accepts `String` as a value. | +| `logoHover?` | Logo to be shown on mouse hover. It accepts `String` as a value. | +| `logoLight?` | Light logo for dark background. It accepts `String` as a value. | +| `logoDark?` | Dark logo for light background. It accepts `String` as a value. | +| `mainOption?` | Show login button on the main list. It accepts `Bool` as a value. Default is false. | +| `showOnModal?` | Whether to show the login button on modal or not. Default is true. | +| `showOnDesktop?` | Whether to show the login button on desktop. Default is true. | +| `showOnMobile?` | Whether to show the login button on mobile. Default is true. | ```swift -public struct W3ALoginConfig: Codable { - let verifier: String - let typeOfLogin: TypeOfLogin - let clientId: String - let name: String? - let description: String? - let verifierSubIdentifier: String? - let logoHover: String? - let logoLight: String? - let logoDark: String? - let mainOption: Bool? - let showOnModal: Bool? - let showOnDesktop: Bool? - let showOnMobile: Bool? +public struct AuthConnectionConfig: Codable { + let authConnectionId: String + let authConnection: AuthConnection + let name: String? + let description: String? + let clientId: String + let groupedAuthConnectionId: String? + let logoHover: String? + let logoLight: String? + let logoDark: String? + let mainOption: Bool? + let showOnModal: Bool? + let showOnDesktop: Bool? + let showOnMobile: Bool? + let jwtParameters: ExtraLoginOptions? + let isDefault: Bool? } -public enum TypeOfLogin: String, Codable { - case google - case facebook - case reddit - case discord - case twitch - case apple - case github - case linkedin - case twitter - case weibo - case line - case email_password - case passwordless - case jwt +public enum AuthConnection: String, Codable { + case GOOGLE = "google" + case FACEBOOK = "facebook" + case REDDIT = "reddit" + case DISCORD = "discord" + case TWITCH = "twitch" + case APPLE = "apple" + case LINE = "line" + case GITHUB = "github" + case KAKAO = "kakao" + case LINKEDIN = "linkedin" + case TWITTER = "twitter" + case WEIBO = "weibo" + case WECHAT = "wechat" + case EMAIL_PASSWORDLESS = "email_passwordless" + case CUSTOM = "custom" + case SMS_PASSWORDLESS = "sms_passwordless" + case FARCASTER = "farcaster" } - ``` @@ -134,20 +130,24 @@ public enum TypeOfLogin: String, Codable { import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.google, - clientId: "YOUR_GOOGLE_CLIENT_ID", - ) - ] - // focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection: .GOOGLE, + clientId: "YOUR_GOOGLE_CLIENT_ID" + ) + ] + // focus-end + ) ) + +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .GOOGLE)) ``` @@ -158,21 +158,24 @@ let web3Auth = try await Web3Auth( import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.facebook, - clientId: "YOUR_FACEBOOK_CLIENT_ID", - ) - ] - // focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection: .FACEBOOK, + clientId: "YOUR_FACEBOOK_CLIENT_ID" + ) + ] + // focus-end + ) ) +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .FACEBOOK)) ``` @@ -183,20 +186,24 @@ let web3Auth = try await Web3Auth( import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId:"YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.jwt, - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - ) - ] - // focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection: .CUSTOM, + clientId: "YOUR_WEB3AUTH_CLIENT_ID" + ) + ] + // focus-end + ) ) + +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .CUSTOM)) ``` @@ -205,7 +212,7 @@ let web3Auth = try await Web3Auth( ## Configure extra sign-in options -Additional to the sign-in config during initialization, you can pass extra options to the `login` function to configure the sign-in flow for cases requiring additional info for enabling sign-in. The `ExtraLoginOptions` accepts the following parameters. +Additional to the auth connection config during initialization, you can pass extra options to the `connectTo` function to configure the login flow for cases requiring additional info. The `ExtraLoginOptions` accepts the following parameters. ### Parameters @@ -219,29 +226,30 @@ Additional to the sign-in config during initialization, you can pass extra optio -| Parameter | Description | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `additionalParams?` | Additional params in `[String:String]` format for OAuth login, use id_token(JWT) to authenticate with Web3Auth. | -| `domain?` | Your custom authentication domain as string. For example, if you are using Auth0, it can be `example.au.auth0.com`. | -| `client_id?` | Client ID as string, 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 integer value. | -| `verifierIdField?` | The field in JWT token which maps to verifier ID. Please make sure you selected correct JWT verifier ID in the developer dashboard. It accepts a string value. | -| `isVerifierIdCaseSensitive?` | Boolean to confirm Whether the verifier ID field is case sensitive or not. | -| `display?` | Allows developers the configure the display of UI. It accepts a string value. | -| `prompt?` | Prompt shown to the user during authentication process. It accepts a string value. | -| `max_age?` | Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It accepts a string value. | -| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | -| `id_token_hint?` | It denotes the previously issued ID token. It accepts a string value. | -| `id_token?` | JWT (ID token) to be passed for login. | -| `login_hint?` | It is used to send the user's email address during email passwordless login. It accepts a string value. | -| `acr_values?` | acr_values | -| `scope?` | The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It accepts a string value. | -| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It accepts a string value. | -| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget. It accepts a string value. | -| `state?` | State | -| `response_type?` | Defines which grant to execute for the authorization server. It accepts a string value. | -| `nonce?` | Nonce | -| `redirect_uri?` | It can be used to specify the default URL, where your custom JWT verifier can redirect your browser to with the result. If you are using Auth0, it must be allowlisted in the Allowed Callback URLs in your Auth0's application. | +| Parameter | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `additionalParams?` | Additional params in `[String: String]` format for OAuth login, use id_token (JWT) to authenticate with Web3Auth. | +| `domain?` | Your custom authentication domain as string. For example, if you are using Auth0, it can be `example.au.auth0.com`. | +| `client_id?` | Client ID as string, provided by your login provider used for custom auth connection. | +| `leeway?` | The value used to account for clock skew in JWT expirations. The value is in seconds, and ideally should be no more than 60 seconds or 120 seconds at max. It takes integer value. | +| `userIdField?` | The field in JWT token which maps to user ID. Please make sure you selected the correct JWT user ID in the developer dashboard. It accepts a string value. | +| `isUserIdCaseSensitive?` | Boolean to confirm whether the user ID field is case sensitive or not. | +| `display?` | Allows developers to configure the display of UI. It accepts a string value. | +| `prompt?` | Prompt shown to the user during authentication process. It accepts a string value. | +| `max_age?` | Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It accepts a string value. | +| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | +| `id_token_hint?` | It denotes the previously issued ID token. It accepts a string value. | +| `id_token?` | JWT (ID token) to be passed for login. | +| `access_token?` | Access token for OAuth flows. It accepts a string value. | +| `flow_type?` | Specifies the email passwordless flow type. Accepts `EmailFlowType` (`.code` or `.link`). | +| `acr_values?` | acr_values | +| `scope?` | The default scope to be used on authentication requests. It accepts a string value. | +| `audience?` | The audience, presented as the aud claim in the access token. It accepts a string value. | +| `connection?` | The name of the connection configured for your application. If nil, it will redirect to the Auth0 login page. It accepts a string value. | +| `state?` | state | +| `response_type?` | Defines which grant to execute for the authorization server. It accepts a string value. | +| `nonce?` | nonce | +| `redirect_uri?` | It can be used to specify the default URL where your custom JWT verifier can redirect your browser to with the result. If you are using Auth0, it must be allowlisted in the Allowed Callback URLs in your Auth0's application. | @@ -249,24 +257,31 @@ Additional to the sign-in config during initialization, you can pass extra optio ```swift public struct ExtraLoginOptions: Codable { - let display: String? - let prompt: String? - let max_age: String? - let ui_locales: String? - let id_token_hint: String? - let id_token: String? - let login_hint: String? - let acr_values: String? - let scope: String? - let audience: String? - let connection: String? - let domain: String? - let client_id: String? - let redirect_uri: String? - let leeway: Int? - let verifierIdField: String? - let isVerifierIdCaseSensitive: Bool? - let additionalParams: [String : String]? + let display: String? + let prompt: String? + let max_age: String? + let ui_locales: String? + let id_token_hint: String? + let id_token: String? + var login_hint: String? + let acr_values: String? + let scope: String? + let audience: String? + let connection: String? + let domain: String? + let client_id: String? + let redirect_uri: String? + let leeway: Int? + let userIdField: String? + let isUserIdCaseSensitive: Bool? + let additionalParams: [String: String]? + let access_token: String? + let flow_type: EmailFlowType? +} + +public enum EmailFlowType: String, Codable { + case code = "code" + case link = "link" } ``` @@ -274,7 +289,7 @@ public struct ExtraLoginOptions: Codable { -### Single verifier example +### Single auth connection example -Auth0 has a special sign-in flow, called the SPA flow. This flow requires a `client_id` and `domain` -to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these -configurations in the `ExtraLoginOptions` object in the sign-in function. + +Auth0 has a special login flow called the SPA flow. This flow requires a `client_id` and `domain` to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these configurations in the `ExtraLoginOptions` object in the login function. ```swift -import +import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId:"YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - // Optional loginConfig object - //focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.jwt, - clientId: "YOUR_AUTH0_CLIENT_ID", - ) - ] - //focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection: .CUSTOM, + clientId: "YOUR_AUTH0_CLIENT_ID" + ) + ] + // focus-end + ) ) - // focus-start -let result = try await web3Auth.login( - W3ALoginParams( - .JWT, - extraLoginOptions: .init( - // Domain of your auth0 app - domain:"https://username.us.auth0.com", - // The field in jwt token which maps to verifier id - verifierIdField: "sub", +// focus-start +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .CUSTOM, + extraLoginOptions: ExtraLoginOptions( + 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 ``` @@ -328,37 +340,36 @@ let result = try await web3Auth.login( -If you're using any other provider like Firebase, AWS Cognito or deploying your own Custom JWT -server, you need to put the JWT token into the `id_token` field of the `extraLoginOptions`, -additionally, you need to pass over the `domain` field as well, which is mandatory. If you don't -have a domain, just passover a string in that field. + +If you're using any other provider like Firebase, AWS Cognito, or deploying your own custom JWT server, you need to put the JWT token into the `idToken` field of `LoginParams`. For SFA (Single Factor Auth) mode, this enables direct authentication without additional login flows. ```swift import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId:"YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .testnet, - // Optional loginConfig object - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.jwt, - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - ) - ] - //focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnection: .CUSTOM, + clientId: "YOUR_WEB3AUTH_CLIENT_ID" + ) + ] + // focus-end + ) ) - // focus-start -let result = await web3Auth.login( - W3ALoginParams( - Web3AuthProvider.JWT, - extraLoginOptions: .init(domain:"your-domain", id_token: "your_jwt_token") - ) +// focus-start +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .CUSTOM, + authConnectionId: "your-auth-connection-id", + idToken: "your_jwt_token" // Direct SFA authentication + ) ) // focus-end ``` @@ -366,26 +377,30 @@ let result = await web3Auth.login( -To use the email passwordless sign-in, you need to put the email into the `login_hint` parameter of -the `ExtraLoginOptions`. By default, the sign-in flow will be `code` flow, if you want to use the -`link` flow, you need to put `flow_type` into the `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`. ```swift import Web3Auth -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - - // focus-start -let result = try await web3Auth.login( - W3ALoginParams( - Web3AuthProvider.EMAIL_PASSWORDLESS, - extraLoginOptions: .init(loginHint: "hello@web3auth.io") -)) +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-start +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .EMAIL_PASSWORDLESS, + loginHint: "hello@web3auth.io", + extraLoginOptions: ExtraLoginOptions( + flow_type: .code // Use .code for OTP flow or .link for magic link flow + ) + ) +) // focus-end ``` @@ -393,79 +408,83 @@ let result = try await web3Auth.login( -To use the SMS Passwordless sign-in, send the phone number as the `login_hint` parameter of the `ExtraLoginOptions`. Please ensure the phone number takes the format: -+\{country_code}-\{phone_number}, that is, (+91-09xx901xx1). +To use the SMS Passwordless login, send the phone number as the `loginHint` parameter of `LoginParams`. Please ensure the phone number takes the format: `+{country_code}-{phone_number}`, for example `+91-9911223344`. ```swift import Web3Auth -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - - // focus-start -let result = try await web3Auth.login(W3ALoginParams( - Web3AuthProvider.SMS_PASSWORDLESS, - // The phone number should be in format of +{country_code}-{phone_number} - extraLoginOptions: .init(loginHint: "+91-9911223344") -)) - // focus-end +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-start +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .SMS_PASSWORDLESS, + loginHint: "+91-9911223344" + ) +) +// focus-end ``` -### Aggregate verifier example +### Grouped auth connection example -You can use aggregate verifier to combine multiple sign-in methods to get the same address for the users regardless of their sign-in providers. For example, combining a Google and email passwordless sign-in, or Google and GitHub via Auth0 to access the same address for your user. +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. ```swift import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId: clientId, - network: network, - redirectUrl: "web3auth.ios-aggregate-example://auth", - // focus-start - loginConfig: [ - TypeOfLogin.google.rawValue: .init( - verifier: "aggregate-sapphire", - typeOfLogin: .google, - name: "Web3Auth-Aggregate-Verifier-Google-Example", - clientId: "YOUR_GOOGLE_CLIENT_ID", - verifierSubIdentifier: "w3a-google" - ), - TypeOfLogin.jwt.rawValue: .init( - verifier: "aggregate-sapphire", - typeOfLogin: .jwt, - clientId: "YOUR_AUTH0_CLIENT_ID", - verifierSubIdentifier: "w3a-a0-github" - ) - ], - // focus-end -)) - -func loginWithGoogle() async { - // focus-start - let result = try await web3Auth?.login( - W3ALoginParams( - loginProvider: .GOOGLE, + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "aggregate-sapphire", + groupedAuthConnectionId: "w3a-google", + authConnection: .GOOGLE, + name: "Aggregate Login", + clientId: "YOUR_GOOGLE_CLIENT_ID" + ), + AuthConnectionConfig( + authConnectionId: "aggregate-sapphire", + groupedAuthConnectionId: "w3a-a0-email-passwordless", + authConnection: .CUSTOM, + name: "Aggregate Login", + clientId: "YOUR_AUTH0_CLIENT_ID" + ) + ] + // focus-end ) - ) - // focus-end +) + +func loginWithGoogle() async throws { + // focus-next-line + let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .GOOGLE)) } -func loginWithGitHub() async { - // focus-start - let result = try await web3Auth?.login( - W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: ExtraLoginOptions(display: nil, prompt: nil, max_age: nil, ui_locales: nil, id_token_hint: nil, id_token: nil, login_hint: nil, acr_values: nil, scope: nil, audience: nil, connection: "github", domain: "https://web3auth.au.auth0.com", client_id: nil, redirect_uri: nil, leeway: nil, verifierIdField: "email", isVerifierIdCaseSensitive: false, additionalParams: nil), +func loginWithGitHub() async throws { + // focus-start + let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .CUSTOM, + extraLoginOptions: ExtraLoginOptions( + connection: "github", + domain: "https://web3auth.au.auth0.com", + userIdField: "email", + isUserIdCaseSensitive: false + ) + ) ) - ) - // focus-end + // focus-end } ``` diff --git a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx index c8c3970e20c..4bcf2a23f08 100644 --- a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx +++ b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx @@ -1,7 +1,7 @@ --- title: Dapp share sidebar_label: Dapp Share -description: 'Web3Auth PnP iOS SDK - dapp share | Embedded Wallets' +description: 'Web3Auth iOS SDK - dapp share | Embedded Wallets' --- ## Embedded Wallets infrastructure at a glance @@ -34,31 +34,36 @@ 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 } } ``` -Notice, the reponses has a field called `dappShare` which is a 24 words seed phrase that can be used to reconstruct the private key. This dappShare is a suplement to the `Share A` and represents half of the private key. The application can store the dapp share in their own application local storage safely. +Notice, the response has a field called `dappShare` which is a 24 words seed phrase that can be used to reconstruct the private key. This dappShare is a supplement to the `Share A` and represents half of the private key. The application can store the dapp share in their own application local storage safely. While logging in, the user can use their social accounts to obtain one share, and the application provides the dapp share, removing the need to store the share in the browser context and enabling user to sign in without repeating the full flow. This can be done by passing over the stored dapp share value in the login function. :::note -It's important to note 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. ::: ```swift -Web3Auth().login(W3ALoginParams(loginProvider: provider, dappShare = "<24 words seed phrase>")) +try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: selectedAuthConnection, + dappShare: "<24 words seed phrase>" + ) +) ``` ## Example @@ -70,51 +75,54 @@ import Web3Auth class ViewModel: ObservableObject { var web3Auth: Web3Auth? @Published var loggedIn: Bool = false - @Published var user: Web3AuthState? + @Published var userInfo: Web3AuthUserInfo? @Published var isLoading = false @Published var navigationTitle: String = "" func setup() async { guard web3Auth == nil else { return } - await MainActor.run(body: { + await MainActor.run { isLoading = true navigationTitle = "Loading" - }) - web3Auth = await Web3Auth(W3AInitParams( - clientId: clientId, network: network - )) - - await MainActor.run(body: { - if self.web3Auth?.state != nil { - user = web3Auth?.state + } + web3Auth = try? await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) + ) + + await MainActor.run { + if self.web3Auth?.web3AuthResponse != nil { + userInfo = web3Auth?.web3AuthResponse?.userInfo loggedIn = true } isLoading = false navigationTitle = loggedIn ? "UserInfo" : "SignIn" - }) + } } - func login(provider: Web3AuthProvider) { + func login(authConnection: AuthConnection) { Task { do { - let result = try await web3Auth.login( - W3ALoginParams( - // provider can be .GOOGLE, .FACEBOOK, .APPLE etc - loginProvider: provider, - // focus-next-line + let result = try await web3Auth?.connectTo( + loginParams: LoginParams( + // authConnection can be .GOOGLE, .FACEBOOK, .APPLE etc + authConnection: authConnection, + // focus-next-line dappShare: "<24 words seed phrase>" - )) + ) + ) - await MainActor.run(body: { - user = result + await MainActor.run { + userInfo = result?.userInfo loggedIn = true - }) - + } } catch { - print("Error") + print("Error: \(error)") } } } } - ``` diff --git a/embedded-wallets/sdk/ios/advanced/mfa.mdx b/embedded-wallets/sdk/ios/advanced/mfa.mdx index 36612926a1a..4f2efa44458 100644 --- a/embedded-wallets/sdk/ios/advanced/mfa.mdx +++ b/embedded-wallets/sdk/ios/advanced/mfa.mdx @@ -1,7 +1,7 @@ --- -title: Multi-factor authentication in PnP iOS SDK +title: Multi-factor authentication in iOS SDK sidebar_label: Multi-factor authentication -description: 'Web3Auth PnP iOS SDK - Multi Factor Authentication | Embedded Wallets' +description: 'Web3Auth iOS SDK - Multi Factor Authentication | Embedded Wallets' --- import TabItem from '@theme/TabItem' @@ -14,11 +14,11 @@ At Web3Auth, we prioritize your security by offering Multi-Factor Authentication ## Enable using the Multi-Factor Authentication level -For a dapp, we provide various options to set up Multi-Factor Authentication. You can customize the MFA screen by passing the `mfaLevel` parameter in `login` method. You can enable or disable a backup factor and change their order. Currently, there are four values for MFA level. +For a dapp, we provide various options to set up Multi-Factor Authentication. You can customize the MFA screen by passing the `mfaLevel` parameter in `connectTo` method. You can enable or disable a backup factor and change their order. Currently, there are four values for MFA level. :::caution Note -If you are using default verifiers, your users may have set up MFA on other dapps that also use default Web3Auth verifiers. In this case, the MFA screen will continue to appear if the user has enabled MFA on other dapps. This is because MFA cannot be turned off once it is enabled. +If you are using default auth connections, your users may have set up MFA on other dapps that also use default Web3Auth auth connections. In this case, the MFA screen will continue to appear if the user has enabled MFA on other dapps. This is because MFA cannot be turned off once it is enabled. ::: @@ -36,30 +36,32 @@ If you are using default verifiers, your users may have set up MFA on other dapp ```swift import Web3Auth -let web3auth = Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) -let result = try await web3Auth.login( - W3ALoginParams( - loginProvider: .GOOGLE, - // focus-next-line - mfaLevel: .MANDATORY - ) +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .GOOGLE, + // focus-next-line + mfaLevel: .MANDATORY + ) ) ``` ## Explicitly enable MFA -The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `W3ALoginParams` which will used during custom verifiers. If you are using default login providers, you don't need to pass `W3ALoginParams`. If you are using custom JWT verifiers, you need to pass the valid JWT token in `W3ALoginParams` as well. +The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will be used during custom auth connections. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT auth connections, you need to pass the valid JWT token in `LoginParams` as well. @@ -67,7 +69,7 @@ The `enableMFA` method is used to trigger MFA setup flow for users. The method t ```swift do { - // focus-next-line + // focus-next-line let isMFAEnabled = try await web3Auth.enableMFA() } catch { print(error.localizedDescription) @@ -81,18 +83,18 @@ do { ```swift do { - let loginParams = W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: .init(id_token: "your_jwt_token") - ) - - let isMFAEnabled = try await web3Auth.enableMFA(loginParams) + let loginParams = LoginParams( + authConnection: .CUSTOM, + authConnectionId: "your-auth-connection-id", + idToken: "your_jwt_token" + ) + // focus-next-line + let isMFAEnabled = try await web3Auth.enableMFA(loginParams) } catch { - print(error.localizedDescription) - // Handle Error + print(error.localizedDescription) + // Handle Error } - ``` @@ -140,23 +142,23 @@ You can configure the order of MFA or enable/disable MFA type by passing the `mf ```swift - public struct MfaSettings: Codable { - public init(deviceShareFactor: MfaSetting?, backUpShareFactor: MfaSetting?, socialBackupFactor: MfaSetting?, passwordFactor: MfaSetting?, passkeysFactor: MfaSetting?, authenticatorFactor: MfaSetting?) { - self.deviceShareFactor = deviceShareFactor - self.backUpShareFactor = backUpShareFactor - self.socialBackupFactor = socialBackupFactor - self.passwordFactor = passwordFactor - self.passkeysFactor = passkeysFactor - self.authenticatorFactor = authenticatorFactor - } - - let deviceShareFactor: MfaSetting? - let backUpShareFactor: MfaSetting? - let socialBackupFactor: MfaSetting? - let passwordFactor: MfaSetting? - let passkeysFactor: MfaSetting? - let authenticatorFactor: MfaSetting? +public struct MfaSettings: Codable { + public init(deviceShareFactor: MfaSetting?, backUpShareFactor: MfaSetting?, socialBackupFactor: MfaSetting?, passwordFactor: MfaSetting?, passkeysFactor: MfaSetting?, authenticatorFactor: MfaSetting?) { + self.deviceShareFactor = deviceShareFactor + self.backUpShareFactor = backUpShareFactor + self.socialBackupFactor = socialBackupFactor + self.passwordFactor = passwordFactor + self.passkeysFactor = passkeysFactor + self.authenticatorFactor = authenticatorFactor } + + let deviceShareFactor: MfaSetting? + let backUpShareFactor: MfaSetting? + let socialBackupFactor: MfaSetting? + let passwordFactor: MfaSetting? + let passkeysFactor: MfaSetting? + let authenticatorFactor: MfaSetting? +} ``` @@ -180,26 +182,24 @@ You can configure the order of MFA or enable/disable MFA type by passing the `mf | ------------ | ------------------------------------------------------------------------------- | | `enable` | Enable/Disable MFA. It accepts `Bool` as a value. | | `priority?` | Priority of MFA. It accepts `Int` as a value, where valid range is from 1 to 4. | -| `mandatory?` | Mandatory/Optional MFA. It acccepts `Bool` as a value. | +| `mandatory?` | Mandatory/Optional MFA. It accepts `Bool` as a value. | ```swift - - public struct MfaSetting: Codable { - public init(enable: Bool, priority: Int?, mandatory: Bool? = nil) { - self.enable = enable - self.priority = priority - self.mandatory = mandatory - } - - let enable: Bool - let priority: Int? - let mandatory: Bool? +public struct MfaSetting: Codable { + public init(enable: Bool, priority: Int?, mandatory: Bool? = nil) { + self.enable = enable + self.priority = priority + self.mandatory = mandatory } + let enable: Bool + let priority: Int? + let mandatory: Bool? +} ``` @@ -210,29 +210,29 @@ You can configure the order of MFA or enable/disable MFA type by passing the `mf ```swift import Web3Auth -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth", - // focus-start - whiteLabel: W3AWhiteLabelData( - mfaSettings: MfaSettings( - deviceShareFactor: MfaSetting(enable: true, priority: 1), - backUpShareFactor: MfaSetting(enable: true, priority: 2), - socialBackupFactor: MfaSetting(enable: true, priority: 3), - passwordFactor: MfaSetting(enable: true, priority: 4), - passkeysFactor: MfaSetting(enable: true, priority: 5), - authenticatorFactor: MfaSetting(enable: true, priority: 6) +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + mfaSettings: MfaSettings( + deviceShareFactor: MfaSetting(enable: true, priority: 1), + backUpShareFactor: MfaSetting(enable: true, priority: 2), + socialBackupFactor: MfaSetting(enable: true, priority: 3), + passwordFactor: MfaSetting(enable: true, priority: 4), + passkeysFactor: MfaSetting(enable: true, priority: 5), + authenticatorFactor: MfaSetting(enable: true, priority: 6) + ) + // focus-end ) - ) - // focus-end -)) +) -let result = try await web3Auth.login( - W3ALoginParams( - loginProvider: .GOOGLE, - // focus-next-line - mfaLevel: .MANDATORY - ) +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .GOOGLE, + // focus-next-line + mfaLevel: .MANDATORY + ) ) ``` diff --git a/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx b/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx new file mode 100644 index 00000000000..e2671be8b7e --- /dev/null +++ b/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx @@ -0,0 +1,176 @@ +--- +title: Smart accounts and Wallet Services configuration +sidebar_label: Smart accounts +description: 'Web3Auth iOS SDK - Smart Accounts and Wallet Services Configuration | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +The iOS SDK provides fine-grained control over the `showWalletUI` and `request` flows through the `walletServicesConfig` parameter in `Web3AuthOptions`. This lets you customize how transaction confirmations are displayed and tailor the wallet UI branding. + +:::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**. + +::: + +## `WalletServicesConfig` + +Pass `walletServicesConfig` in `Web3AuthOptions` to configure how wallet services behave across your application. + +### Parameters + +| Parameter | Description | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy`. Default is `.defaultStrategy`. | +| `whiteLabel?` | Whitelabel configuration for the wallet services UI. When provided, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as a value. | + +### `ConfirmationStrategy` + +`ConfirmationStrategy` controls the UI shown when a user needs to confirm a transaction or signature request. + +| Value | Description | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| `.defaultStrategy` | Shows the default Web3Auth confirmation screen inside the wallet WebView. This is the default value. | +| `.modal` | Shows the confirmation request in a bottom sheet modal on top of your application, rather than navigating to a new full-screen WebView. | +| `.popup` | Shows the confirmation in a small popup window. Useful for minimal UI disruption. | + +### Interface + +```swift +public struct WalletServicesConfig: Codable { + public let confirmationStrategy: ConfirmationStrategy? + public let whiteLabel: WhiteLabelData? + + public init( + confirmationStrategy: ConfirmationStrategy? = nil, + whiteLabel: WhiteLabelData? = nil + ) +} + +public enum ConfirmationStrategy: String, Codable { + case defaultStrategy = "default" + case modal = "modal" + case popup = "popup" +} +``` + +## Setup + +Configure `walletServicesConfig` during SDK initialization: + +```swift +import Web3Auth + +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + walletServicesConfig: WalletServicesConfig( + confirmationStrategy: .modal, + whiteLabel: WhiteLabelData( + appName: "My App", + theme: ["primary": "#0364FF"] + ) + ) + // focus-end + ) +) +``` + +## Usage examples + + + + + +```swift +do { + // focus-next-line + try await web3Auth.showWalletUI() +} catch { + print(error.localizedDescription) + // Handle error +} +``` + + + + + +```swift +do { + var params = [Any]() + params.append("Hello, Web3Auth from iOS!") + params.append(address) // User's EOA address + + // focus-start + let response = try await web3Auth.request( + method: "personal_sign", + requestParams: params + ) + // focus-end + + if let response = response, response.success { + print("Signature: \(response.result!)") + } +} catch { + print(error.localizedDescription) + // Handle error +} +``` + + + + + +```swift +do { + let typedData = """ + { + "types": { + "EIP712Domain": [ + { "name": "name", "type": "string" } + ], + "Mail": [ + { "name": "contents", "type": "string" } + ] + }, + "primaryType": "Mail", + "domain": { "name": "Ether Mail" }, + "message": { "contents": "Hello, Bob!" } + } + """ + + var params = [Any]() + params.append(address) // User's EOA address + params.append(typedData) + + // focus-start + let response = try await web3Auth.request( + method: "eth_signTypedData_v4", + requestParams: params + ) + // focus-end + + if let response = response, response.success { + print("Signature: \(response.result!)") + } +} catch { + print(error.localizedDescription) + // Handle error +} +``` + + + diff --git a/embedded-wallets/sdk/ios/advanced/whitelabel.mdx b/embedded-wallets/sdk/ios/advanced/whitelabel.mdx index c7e8620e612..a2141ae2e68 100644 --- a/embedded-wallets/sdk/ios/advanced/whitelabel.mdx +++ b/embedded-wallets/sdk/ios/advanced/whitelabel.mdx @@ -1,7 +1,7 @@ --- -title: Whitelabel PnP iOS SDK +title: Whitelabel iOS SDK sidebar_label: Whitelabel -description: 'Web3Auth PnP iOS SDK - Whitelabel | Embedded Wallets' +description: 'Web3Auth iOS SDK - Whitelabel | Embedded Wallets' --- import TabItem from '@theme/TabItem' @@ -22,7 +22,7 @@ Web3Auth allows complete whitelabeling with application branding for a consisten ## Customizing the Web3Auth login screens -For defining custom UI, branding, and translations for your brand app, you just need to define an optional object called `W3AWhiteLabelData``. `W3AWhiteLabelData``can be definied during initialization of the SDK in`W3AInitParams` object. +For defining custom UI, branding, and translations for your brand app, you just need to define an optional object called `WhiteLabelData`. `WhiteLabelData` can be defined during initialization of the SDK in `Web3AuthOptions`. @@ -46,8 +46,8 @@ The parameters which can be used to customize the user flow screens are given be | `logoLight?` | App logo to be used in dark mode. It accepts URL as a string. | | `logoDark?` | App logo to be used in light mode. It accepts URL as a string. | | `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 dictonary of `[String:String]` as a value. | +| `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 a dictionary of `[String: String]` as a value. | | `appUrl?` | URL to be used in the modal. It accepts URL as a string. | | `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are nil, the default Web3Auth logo will be used for the loader. Default value is false. | @@ -56,7 +56,7 @@ The parameters which can be used to customize the user flow screens are given be ```swift -public struct W3AWhiteLabelData: Codable { +public struct WhiteLabelData: Codable { let appName: String? let logoLight: String? let logoDark: String? @@ -76,19 +76,21 @@ public struct W3AWhiteLabelData: Codable { ### Example ```swift title="Usage" -web3Auth = await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .testnet, - // focus-start - whiteLabel: W3AWhiteLabelData( - appName: "Web3Auth Stub", - logoLight: "https://images.web3auth.io/web3auth-logo-w.svg", - logoDark: "https://images.web3auth.io/web3auth-logo-w.svg", - defaultLanguage: .en, // en, de, ja, ko, zh, es, fr, pt, nl - mode: .dark - theme: ["primary": "#d53f8c"] +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + whiteLabel: WhiteLabelData( + appName: "Web3Auth Stub", + logoLight: "https://images.web3auth.io/web3auth-logo-w.svg", + logoDark: "https://images.web3auth.io/web3auth-logo-w.svg", + defaultLanguage: .en, // en, de, ja, ko, zh, es, fr, pt, nl + mode: .dark, + theme: ["primary": "#d53f8c"] + ) + // focus-end ) - )) - // focus-end +) ``` diff --git a/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx b/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx new file mode 100644 index 00000000000..4cb9ce68c4a --- /dev/null +++ b/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx @@ -0,0 +1,270 @@ +--- +title: iOS SDK - v11 to v12 +description: 'iOS SDK v11 to v12 migration guide | Embedded Wallets' +sidebar_label: v11 to v12 +--- + +This migration guide covers the breaking changes and enhancements introduced in v12 of the Web3Auth iOS SDK. Version 12 aligns the iOS SDK with the Android SDK v10 changes and introduces a new API surface with cleaner naming conventions. + +## Breaking changes + +### Initialization: `W3AInitParams` renamed to `Web3AuthOptions` + +The initialization struct has been renamed from `W3AInitParams` to `Web3AuthOptions`, and the constructor is now fully async. The separate `initialize()` call has been removed — session restoration happens automatically in the constructor. + +**Network enum renamed**: `Network` is now `Web3AuthNetwork`, and enum cases are now uppercase (for example, `.sapphire_mainnet` becomes `.SAPPHIRE_MAINNET`). + +```swift +// remove-next-line +web3Auth = await Web3Auth(W3AInitParams( +// add-next-line +web3Auth = try await Web3Auth(options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", +// remove-next-line + network: .sapphire_mainnet, +// add-next-line + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" +)) + +// remove-next-line +await web3Auth.initialize() +``` + +The new constructor throws if initialization fails, so wrap it in `do/catch`. + +### URL callbacks removed + +The `setResultUrl(url:)` method has been removed. The SDK now uses `ASWebAuthenticationSession` internally and handles all redirects automatically. Remove any calls to `setResultUrl` and the associated `onOpenURL` handler. + +```swift +// remove-start +.onOpenURL { url in + Web3Auth.setResultUrl(url) +} +// remove-end +``` + +### `login()` renamed to `connectTo()` + +The `login` method and `W3ALoginParams` have been replaced by `connectTo` and `LoginParams`. + +```swift +// remove-next-line +let result = try await web3Auth.login(W3ALoginParams(loginProvider: .GOOGLE)) +// add-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .GOOGLE)) +``` + +### `Web3AuthProvider` renamed to `AuthConnection`; `.JWT` renamed to `.CUSTOM` + +The login provider enum has been renamed from `Web3AuthProvider` to `AuthConnection`. The `.JWT` case is now `.CUSTOM`. + +```swift +// remove-next-line +let params = W3ALoginParams(loginProvider: .JWT, extraLoginOptions: .init(id_token: "...")) +// add-next-line +let params = LoginParams(authConnection: .CUSTOM, authConnectionId: "your-connection-id", idToken: "your_jwt_token") +``` + +### `loginConfig` renamed to `authConnectionConfig`; `W3ALoginConfig` renamed to `AuthConnectionConfig` + +The custom authentication configuration has changed from a dictionary (`[String: W3ALoginConfig]`) to an array (`[AuthConnectionConfig]`). The type itself has been renamed with updated field names. + +| Old field | New field | +| ----------------------- | ------------------------- | +| `verifier` | `authConnectionId` | +| `typeOfLogin` | `authConnection` | +| `verifierSubIdentifier` | `groupedAuthConnectionId` | + +```swift +// remove-start +loginConfig: [ + Web3AuthProvider.JWT.rawValue: .init( + verifier: "your-verifier-name", + typeOfLogin: .google, + clientId: "YOUR_GOOGLE_CLIENT_ID", + verifierSubIdentifier: "sub-verifier" + ) +] +// remove-end +// add-start +authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", + authConnection: .GOOGLE, + clientId: "YOUR_GOOGLE_CLIENT_ID", + groupedAuthConnectionId: "sub-connection" + ) +] +// add-end +``` + +### `ExtraLoginOptions`: `verifierIdField` and `isVerifierIdCaseSensitive` renamed + +```swift +// remove-next-line +ExtraLoginOptions(verifierIdField: "sub", isVerifierIdCaseSensitive: false) +// add-next-line +ExtraLoginOptions(userIdField: "sub", isUserIdCaseSensitive: false) +``` + +### `getPrivKey()` renamed to `getPrivateKey()` + +```swift +// remove-next-line +let privateKey = web3Auth.getPrivKey() +// add-next-line +let privateKey = web3Auth.getPrivateKey() +``` + +### `getEd25519PrivKey()` renamed to `getEd25519PrivateKey()` + +```swift +// remove-next-line +let ed25519Key = web3Auth.getEd25519PrivKey() +// add-next-line +let ed25519Key = try web3Auth.getEd25519PrivateKey() +``` + +### `launchWalletServices(chainConfig:)` renamed to `showWalletUI(path:)` + +The chain configuration is no longer passed directly to the wallet services method. Instead, chain config comes from the project settings in the Web3Auth Dashboard or via the new `chains` parameter in `Web3AuthOptions`. + +```swift +// remove-next-line +try await web3Auth.launchWalletServices(chainConfig: ChainConfig(chainId: "0x89", rpcTarget: "https://rpc.ankr.com/polygon")) +// add-next-line +try await web3Auth.showWalletUI() +``` + +### `request(chainConfig:method:requestParams:)` signature updated + +The `chainConfig` parameter has been removed. Chain configuration now comes from the dashboard or `Web3AuthOptions.chains`. + +```swift +// remove-start +let response = try await web3Auth.request( + chainConfig: ChainConfig(chainId: "0x89", rpcTarget: "https://rpc.ankr.com/polygon"), + method: "personal_sign", + requestParams: params +) +// remove-end +// add-start +let response = try await web3Auth.request( + method: "personal_sign", + requestParams: params +) +// add-end +``` + +### `Web3AuthUserInfo` field renames + +The following fields in `Web3AuthUserInfo` (returned by `getUserInfo()`) have been renamed: + +| Old field name | New field name | +| ------------------- | ------------------------- | +| `verifier` | `authConnectionId` | +| `verifierId` | `userId` | +| `typeOfLogin` | `authConnection` | +| `aggregateVerifier` | `groupedAuthConnectionId` | + +Update any code that reads these fields from the user info response. + +### `useCoreKitKey` renamed to `useSFAKey` + +```swift +// remove-next-line +Web3AuthOptions(clientId: "...", web3AuthNetwork: .SAPPHIRE_MAINNET, redirectUrl: "...", useCoreKitKey: true) +// add-next-line +Web3AuthOptions(clientId: "...", web3AuthNetwork: .SAPPHIRE_MAINNET, redirectUrl: "...", useSFAKey: true) +``` + +### Session time default changed + +The default `sessionTime` has changed from **7 days** to **30 days**. If you were relying on the 7-day default, set `sessionTime` explicitly: + +```swift +Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // add-next-line + sessionTime: 86400 * 7 // Explicitly set to 7 days if needed +) +``` + +## New features + +### Chains configuration + +You can now configure blockchain networks directly in `Web3AuthOptions` using the `chains` parameter. When set, these chains are used by wallet services in addition to any chains configured in the project dashboard. + +```swift +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 + +A new `walletServicesConfig` parameter in `Web3AuthOptions` lets you customize the confirmation strategy for transaction requests. + +```swift +Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + walletServicesConfig: WalletServicesConfig( + confirmationStrategy: .modal + ) +) +``` + +### SFA (Single Factor Auth) mode + +The `idToken` parameter in `LoginParams` enables direct SFA authentication. When provided, the SDK authenticates the user with the given JWT token without launching any browser-based login flow. + +```swift +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .CUSTOM, + authConnectionId: "your-auth-connection-id", + idToken: "your_jwt_token" + ) +) +``` + +### `loginHint` in `LoginParams` + +A new `loginHint` parameter has been added directly to `LoginParams`, eliminating the need to nest it inside `ExtraLoginOptions` for passwordless flows. + +```swift +// Old way +let result = try await web3Auth.login( + W3ALoginParams( + loginProvider: .EMAIL_PASSWORDLESS, + extraLoginOptions: .init(loginHint: "hello@web3auth.io") + ) +) + +// New way +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .EMAIL_PASSWORDLESS, + loginHint: "hello@web3auth.io" + ) +) +``` diff --git a/embedded-wallets/sdk/ios/usage/README.mdx b/embedded-wallets/sdk/ios/usage/README.mdx index 03065666288..12391d6cfb9 100644 --- a/embedded-wallets/sdk/ios/usage/README.mdx +++ b/embedded-wallets/sdk/ios/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()`](./login.mdx) | Logs in the user with the selected login provider. | -| [`logout()`](./logout.mdx) | Logs out the user from the current session. | +| Function Name | Description | +| -------------------------------- | --------------------------------------------------- | +| [`connectTo()`](./connectTo.mdx) | Logs in the user with the selected auth connection. | +| [`logout()`](./logout.mdx) | Logs out the user from the current session. | ### User management functions @@ -31,8 +31,8 @@ For detailed usage, configuration options, and code examples, refer to the dedic | Function Name | Description | | ------------------------------------------------------ | ------------------------------------------------------------------------------- | -| [`getPrivKey()`](./get-private-key.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | -| [`getEd25519PrivKey()`](./get-ed25519-private-key.mdx) | Retrieve the user's ed25519 private key for chains like Solana, Near, Algorand. | +| [`getPrivateKey()`](./getPrivateKey.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | +| [`getEd25519PrivateKey()`](./getEd25519PrivateKey.mdx) | 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()`](./launch-wallet-services.mdx) | Launches the templated wallet UI in WebView. | -| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions. | +| Function Name | Description | +| -------------------------------------- | ----------------------------------------------------------------- | +| [`showWalletUI()`](./showWalletUI.mdx) | Launches the templated wallet UI in WebView. | +| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions. | diff --git a/embedded-wallets/sdk/ios/usage/connectTo.mdx b/embedded-wallets/sdk/ios/usage/connectTo.mdx new file mode 100644 index 00000000000..663bcfacb7e --- /dev/null +++ b/embedded-wallets/sdk/ios/usage/connectTo.mdx @@ -0,0 +1,295 @@ +--- +title: Logging in a User +sidebar_label: connectTo +description: 'Web3Auth iOS SDK - connectTo Function | Embedded Wallets' +--- + +import TabItem from '@theme/TabItem' +import Tabs from '@theme/Tabs' + +To log in a user, use the `connectTo` method. It triggers the login flow and navigates the user to a browser modal allowing them to authenticate. You can pass in the supported auth connections to the method for specific social logins (such as `.GOOGLE`, `.APPLE`, `.FACEBOOK`) and do whitelabel login. + +For SFA (Single Factor Auth) login with a JWT token, pass the `idToken` parameter to authenticate directly without the browser modal. + +## Parameters + +The `connectTo` method accepts `LoginParams` as a required parameter. + + + + + +| Parameter | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `authConnection` | It sets the OAuth login method to be used. You can use any of the supported values: `.GOOGLE`, `.FACEBOOK`, `.REDDIT`, `.DISCORD`, `.TWITCH`, `.APPLE`, `.LINE`, `.GITHUB`, `.KAKAO`, `.LINKEDIN`, `.TWITTER`, `.WEIBO`, `.WECHAT`, `.EMAIL_PASSWORDLESS`, `.SMS_PASSWORDLESS`, and `.FARCASTER`. | +| `authConnectionId?` | The auth connection ID for the connection. Required for SFA mode when `idToken` is passed. Default value is `nil`. | +| `groupedAuthConnectionId?` | The grouped auth connection ID for grouped auth connections. It accepts `String` as a value. | +| `extraLoginOptions?` | It can be used to set the OAuth login options for the corresponding `authConnection`. Default value is `nil`, 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 `nil`, and it accepts a string value. | +| `mfaLevel?` | Customize the MFA screen shown to the user during authentication. Default value is `.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | +| `dappShare?` | Custom auth connection 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 a string value. | +| `curve?` | It will be used to determine the public key encoded in the JWT token which is returned in `getUserInfo` after user login. Private key returned by `getPrivateKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivateKey`. The default value is `.SECP256K1`. | +| `loginHint?` | Used to specify the user's email address or phone number for email/SMS passwordless login flows. For SMS, the format should be: `+{country_code}-{phone_number}` (for example `+1-1234567890`). It accepts a string value. | +| `idToken?` | JWT token for SFA (Single Factor Auth) mode. When provided, enables direct authentication without the social login browser flow. It accepts a string value. | + + + + + +```swift +public struct LoginParams: Codable, Sendable { + public init( + authConnection: AuthConnection, + authConnectionId: String? = nil, + groupedAuthConnectionId: String? = nil, + appState: String? = nil, + mfaLevel: MFALevel? = nil, + extraLoginOptions: ExtraLoginOptions? = nil, + dappShare: String? = nil, + curve: SUPPORTED_KEY_CURVES = .SECP256K1, + dappUrl: String? = nil, + loginHint: String? = nil, + idToken: String? = nil + ) +} + +public enum AuthConnection: String, Codable { + case GOOGLE = "google" + case FACEBOOK = "facebook" + case REDDIT = "reddit" + case DISCORD = "discord" + case TWITCH = "twitch" + case APPLE = "apple" + case LINE = "line" + case GITHUB = "github" + case KAKAO = "kakao" + case LINKEDIN = "linkedin" + case TWITTER = "twitter" + case WEIBO = "weibo" + case WECHAT = "wechat" + case EMAIL_PASSWORDLESS = "email_passwordless" + case CUSTOM = "custom" + case SMS_PASSWORDLESS = "sms_passwordless" + case FARCASTER = "farcaster" +} +``` + + + + +## Usage + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .GOOGLE)) +``` + +## Examples + + + + + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .GOOGLE)) +``` + + + + + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .FACEBOOK)) +``` + + + + + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .DISCORD)) +``` + + + + + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .TWITCH)) +``` + + + + + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-start +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .EMAIL_PASSWORDLESS, + loginHint: "hello@web3auth.io", + extraLoginOptions: ExtraLoginOptions( + flow_type: .code // Use .code for OTP flow or .link for magic link flow + ) + ) +) +// focus-end +``` + + + + + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-start +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .SMS_PASSWORDLESS, + // The phone number should be in format of +{country_code}-{phone_number} + loginHint: "+91-9911223344" + ) +) +// focus-end +``` + + + + + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-next-line +let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .FARCASTER)) +``` + + + + + +For SFA (Single Factor Auth) mode, pass the JWT token via `idToken` to authenticate directly without any browser-based login flow. This is useful when you already have a JWT from your own authentication system. + +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-start +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .CUSTOM, + authConnectionId: "your-auth-connection-id", // Get it from Web3Auth Dashboard + idToken: "your_jwt_token" + ) +) +// focus-end +``` + + + diff --git a/embedded-wallets/sdk/ios/usage/enable-mfa.mdx b/embedded-wallets/sdk/ios/usage/enable-mfa.mdx index e30dede8c84..efa37b888f9 100644 --- a/embedded-wallets/sdk/ios/usage/enable-mfa.mdx +++ b/embedded-wallets/sdk/ios/usage/enable-mfa.mdx @@ -7,15 +7,15 @@ description: 'Web3Auth iOS SDK - enableMFA | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `W3ALoginParams` which will used during custom verifiers. If you are using default login providers, you don't need to pass `W3ALoginParams`. If you are using custom JWT verifiers, you need to pass the valid JWT token in `W3ALoginParams` as well. +The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will be used during custom auth connections. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT auth connections, you need to pass the valid JWT token in `LoginParams` as well. ## Usage @@ -23,7 +23,7 @@ The `enableMFA` method is used to trigger MFA setup flow for users. The method t ```swift do { - // focus-next-line + // focus-next-line let isMFAEnabled = try await web3Auth.enableMFA() } catch { print(error.localizedDescription) @@ -35,20 +35,26 @@ do { -```swift -do { - let loginParams = W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: .init(id_token: " diff --git a/embedded-wallets/sdk/ios/usage/get-ed25519-private-key.mdx b/embedded-wallets/sdk/ios/usage/get-ed25519-private-key.mdx deleted file mode 100644 index 726c5c68b03..00000000000 --- a/embedded-wallets/sdk/ios/usage/get-ed25519-private-key.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Get Ed25519 private key -sidebar_label: Get Ed25519 private key -description: 'Web3Auth iOS SDK - getEd25519PrivKey | Embedded Wallets' ---- - -To retrieve the secp256k1 private key of the user., use `getEd25519PrivKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. - -## Usage - -```swift -let privateKey = web3Auth.getEd25519PrivKey(); -``` diff --git a/embedded-wallets/sdk/ios/usage/get-private-key.mdx b/embedded-wallets/sdk/ios/usage/get-private-key.mdx deleted file mode 100644 index 246981881de..00000000000 --- a/embedded-wallets/sdk/ios/usage/get-private-key.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Get Secp256k1 private key -sidebar_label: Get Secp256k1 private key -description: 'Web3Auth iOS SDK - getPrivKey | 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 - -```swift -let privateKey = web3Auth.getPrivKey(); -``` diff --git a/embedded-wallets/sdk/ios/usage/get-user-info.mdx b/embedded-wallets/sdk/ios/usage/get-user-info.mdx index 55f7fbc6a02..406a904d590 100644 --- a/embedded-wallets/sdk/ios/usage/get-user-info.mdx +++ b/embedded-wallets/sdk/ios/usage/get-user-info.mdx @@ -6,10 +6,12 @@ description: 'Web3Auth iOS SDK - getUserInfo | Embedded Wallets' You can use the `getUserInfo` method to retrieve various details about the user, such as their login type, whether multi-factor authentication (MFA) is enabled, profile image, name, and other relevant information. +The method throws if no user session is found. + ## Usage ```swift -let web3AuthUserInfo = web3Auth.getUserInfo(); +let web3AuthUserInfo = try web3Auth.getUserInfo() ``` ## `getUserInfo` response @@ -20,14 +22,14 @@ let web3AuthUserInfo = web3Auth.getUserInfo(); "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 } } diff --git a/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx b/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx new file mode 100644 index 00000000000..12c89b90027 --- /dev/null +++ b/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx @@ -0,0 +1,15 @@ +--- +title: Ed25519 Private Key +sidebar_label: getEd25519PrivateKey +description: 'Web3Auth iOS SDK - getEd25519PrivateKey | Embedded Wallets' +--- + +To retrieve the Ed25519 private key of the user, use the `getEd25519PrivateKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. + +The method throws if no user session is found or if the key is unavailable. + +## Usage + +```swift +let ed25519PrivateKey = try web3Auth.getEd25519PrivateKey() +``` diff --git a/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx b/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx new file mode 100644 index 00000000000..9772d3aab67 --- /dev/null +++ b/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx @@ -0,0 +1,15 @@ +--- +title: Secp256k1 Private Key +sidebar_label: getPrivateKey +description: 'Web3Auth iOS SDK - getPrivateKey | Embedded Wallets' +--- + +To retrieve the secp256k1 private key of the user, use the `getPrivateKey` method. The method returns an EVM compatible private key which can be used to sign transactions on EVM-compatible chains. + +When `useSFAKey` is set to `true` in `Web3AuthOptions`, this method returns the SFA (Single Factor Auth) key instead of the standard private key. + +## Usage + +```swift +let privateKey = web3Auth.getPrivateKey() +``` diff --git a/embedded-wallets/sdk/ios/usage/launch-wallet-services.mdx b/embedded-wallets/sdk/ios/usage/launch-wallet-services.mdx deleted file mode 100644 index 6785cdaac78..00000000000 --- a/embedded-wallets/sdk/ios/usage/launch-wallet-services.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Launch Wallet Services -sidebar_label: Show wallet UI -description: 'Web3Auth iOS SDK - launchWalletServices | Embedded Wallets' ---- - -import TabItem from '@theme/TabItem' -import Tabs from '@theme/Tabs' - -The `launchWalletServices` method launches a WebView which allows you to use the prebuilt 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` at no cost. The minimum [pricing plan](https://web3auth.io/pricing.html) to use this feature in a production environment is the **Scale Plan**. - -::: - -Wallet Services - -## 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. (for example, `https://etherscan.io`) | -| `chainId` | The chain ID of the selected blockchain `String`. | -| `displayName?` | Display Name for the chain. | -| `logo?` | Logo for the selected `chainNamespace` and `chainId`. | -| `rpcTarget` | RPC Target URL for the selected `chainNamespace` and `chainId`. | -| `ticker?` | Default currency ticker of the network (for example, `ETH`). | -| `tickerName?` | Name for currency ticker (for example, `Ethereum`). | - - - - - -```swift -public struct ChainConfig: Codable { - public init(chainNamespace: ChainNamespace = ChainNamespace.eip155, decimals: Int? = 18, blockExplorerUrl: String? = nil, chainId: String, displayName: String? = nil, logo: String? = nil, rpcTarget: String, ticker: String? = nil, tickerName: String? = nil) { - self.chainNamespace = chainNamespace - self.decimals = decimals - self.blockExplorerUrl = blockExplorerUrl - self.chainId = chainId - self.displayName = displayName - self.logo = logo - self.rpcTarget = rpcTarget - self.ticker = ticker - self.tickerName = tickerName - } -} - -``` - - - - -## Usage - -```swift -do { - // focus-start - try await web3Auth!.launchWalletServices( - chainConfig: ChainConfig( - chainId: "0xaa36a7", - rpcTarget: "https://eth-sepolia.public.blastapi.io" - ) - ) - // focus-end -} catch { - print(error.localizedDescription) - // Handle error -} -``` diff --git a/embedded-wallets/sdk/ios/usage/login.mdx b/embedded-wallets/sdk/ios/usage/login.mdx deleted file mode 100644 index 4b0bab540da..00000000000 --- a/embedded-wallets/sdk/ios/usage/login.mdx +++ /dev/null @@ -1,272 +0,0 @@ ---- -title: Login user -sidebar_label: Sign in a user -description: 'Web3Auth iOS SDK - login | Embedded Wallets' ---- - -import TabItem from '@theme/TabItem' -import Tabs from '@theme/Tabs' - -To login in a user, you can use the `login` method. It will trigger login flow will navigate the user to a browser model allowing the user to login into the service. You can pass in the supported providers to the login method for specific social logins (such as GOOGLE, APPLE, FACEBOOK) and do whitelabel login. - -## Parameters - -The login method accepts `W3ALoginParams` as a required parameter. - - - - - -| 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`, `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 `nil`, 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 `nil`, and accepts `URL` 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 `nil`, and it accepts a string value. | -| `mfaLevel?` | Customize the MFA screen shown to the user during OAuth authentication. Default value for field is `MFALevel.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | -| `dappShare?` | Custom verifier logins can get a dapp share returned to them post successful login. This is useful if the dapps want to use this share to allow users to sign in without repeating the full flow. It accepts a string value. | -| `curve?` | It will be used to determine the public key encoded in the JWT token which returned in `getUserInfo` function after user login. This parameter won't change format of private key returned by We3Auth. Private key returned by `getPrivKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivKey` method. The default value is `SUPPORTED_KEY_CURVES.SECP256K1`. | - - - - - -```swift -public struct W3ALoginParams: Codable { - public init() { - loginProvider = nil - dappShare = nil - extraLoginOptions = nil - redirectUrl = nil - appState = nil - mfaLevel = nil - curve = .SECP256K1 - } - - let loginProvider: String? - var dappShare: String? - let extraLoginOptions: ExtraLoginOptions? - let redirectUrl: String? - let appState: String? - let mfaLevel: MFALevel? - let curve: SUPPORTED_KEY_CURVES -} - -public enum Web3AuthProvider: String, Codable { - case GOOGLE = "google" - case FACEBOOK = "facebook" - case REDDIT = "reddit" - case DISCORD = "discord" - case TWITCH = "twitch" - case APPLE = "apple" - case LINE = "line" - case GITHUB = "github" - case KAKAO = "kakao" - case LINKEDIN = "linkedin" - case TWITTER = "twitter" - case WEIBO = "weibo" - case WECHAT = "wechat" - case EMAIL_PASSWORDLESS = "email_passwordless" - case JWT = "jwt" - case SMS_PASSWORDLESS = "sms_passwordless" - case FARCASTER = "farcaster" -} -``` - - - - -## Usage - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .GOOGLE)) -``` - -## Examples - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .GOOGLE)) -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .FACEBOOK)) -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .DISCORD)) -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .TWITCH)) -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network:.sapphire_mainnet, - redirectUrl: "bundleId://auth" - ) -) - -// focus-start -let result = try await web3Auth.login( - W3ALoginParams( - loginProvider: .EMAIL_PASSWORDLESS, - extraLoginOptions: .init(loginHint: "hello@web3auth.io") - ) -) -// focus-end -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable network: .sapphire_mainnet, redirectUrl: "bundleId://auth" )) - -// focus-start -let result = try await web3Auth.login( -W3ALoginParams( -Web3AuthProvider.SMS_PASSWORDLESS, -// The phone number should be in format of +{country_code}-{phone_number} -extraLoginOptions: .init(loginHint: "+91-9911223344") -) -) -// focus-end - -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" - ) -) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .FARCASTER)) - -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-start -let result = try await web3Auth.login( - W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: .init(domain:"your-domain", id_token: "your_jwt_token") - ) -) -// focus-end -``` - - - diff --git a/embedded-wallets/sdk/ios/usage/manage-mfa.mdx b/embedded-wallets/sdk/ios/usage/manage-mfa.mdx index 0aeb2b67635..c64c1609efa 100644 --- a/embedded-wallets/sdk/ios/usage/manage-mfa.mdx +++ b/embedded-wallets/sdk/ios/usage/manage-mfa.mdx @@ -7,15 +7,15 @@ description: 'Web3Auth iOS SDK - manageMFA | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The `manageMFA` method is used to trigger manage MFA flow for users, allowing users to update their MFA settings. The method takes `W3ALoginParams` which will used during custom verifiers. If you are using default login providers, you don't need to pass `W3ALoginParams`. If you are using custom JWT verifiers, you need to pass the JWT token in `loginParams` as well. +The `manageMFA` method is used to trigger manage MFA flow for users, allowing users to update their MFA settings. The method takes `LoginParams` which will be used during custom auth connections. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT auth connections, you need to pass the JWT token in `LoginParams` as well. ## Usage @@ -39,20 +39,21 @@ do { ```swift -let loginParams = W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: .init(id_token: "your_jwt_token") +let loginParams = LoginParams( + authConnection: .CUSTOM, + authConnectionId: "your-auth-connection-id", + idToken: "your_jwt_token" ) do { - let response = try await web3Auth.manageMFA(loginParams) - if response { - // Handle success - } else { - // Something went wrong - } + let response = try await web3Auth.manageMFA(loginParams) + if response { + // Handle success + } else { + // Something went wrong + } } catch { - // Handle error + // Handle error } ``` diff --git a/embedded-wallets/sdk/ios/usage/request.mdx b/embedded-wallets/sdk/ios/usage/request.mdx index 48a03e3f2a4..cba576027f6 100644 --- a/embedded-wallets/sdk/ios/usage/request.mdx +++ b/embedded-wallets/sdk/ios/usage/request.mdx @@ -4,10 +4,12 @@ sidebar_label: Send requests description: 'Web3Auth iOS SDK - request | Embedded Wallets' --- -The `request` method facilitates the use of prebuilt transaction screens for signing transactions. The method will return [SignResponse](#signresponse). It can be used to sign transactions for any EVM chain and screens can be customized to match your branding. +The `request` method facilitates the use of templated transaction screens for signing transactions. The method returns a `SignResponse?`. It can be used to sign transactions for any EVM chain and screens can be whitelabeled to your branding. Please check the list of [JSON RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/), noting that the request method currently supports only the signing methods. +Chain configuration is retrieved automatically from your project settings in the Embedded Wallets dashboard. + Date: Thu, 16 Apr 2026 09:51:41 +1000 Subject: [PATCH 02/24] Initial custom-authentication edits. Signed-off-by: bgravenorst --- .../ios/advanced/custom-authentication.mdx | 93 ++++++++++++++++--- 1 file changed, 79 insertions(+), 14 deletions(-) diff --git a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx index 9daec2c50a2..a50466d65a7 100644 --- a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx @@ -8,33 +8,42 @@ import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' import GrowthPlanNote from '../../_common/_growth_plan_note.mdx' -Custom authentication is a way to authenticate users with your custom authentication service. For example, while authenticating with Google, you can use your own Google Client ID to authenticate users directly. +Custom authentication lets you use your own identity provider to sign users in directly. For example, +you can use your own Google Client ID when authenticating with Google. -This feature, with MFA turned off, can even make Embedded Wallets invisible to the end user. +With MFA disabled, custom authentication makes the wallet infrastructure invisible to your users, so +they don't see any authentication modal or branding. -## Get an Auth Connection ID +## Create a connection :::info prerequisite -To enable this, you need to [create a connection](/embedded-wallets/dashboard/authentication) from the **Authentication** tab of your project from the [Embedded Wallets developer dashboard](https://developer.metamask.io) with your desired configuration. +[Create a connection](../../../dashboard/authentication.mdx) from the **Authentication** tab of +your project in the [Embedded Wallets developer dashboard](https://developer.metamask.io). + ::: -To configure a connection, you need to provide the particular details of the connection into our Embedded Wallets dashboard. This enables us to map an `authConnectionId` with your connection details. This `authConnectionId` helps us to identify the connection details while initializing the SDK. You can configure multiple connections for the same project, and you can also update the connection details anytime. +Provide your connection details in the Embedded Wallets dashboard to generate an `authConnectionId`. +The SDK uses this ID to identify the connection during initialization. You can configure multiple +connections for the same project and update them anytime. :::tip -Learn more about the [auth provider setup](/embedded-wallets/authentication) and the different configurations available for each connection. +See [authentication provider setup](../../../authentication/README.mdx) for available connection configurations. ::: ## Configuration -To use custom authentication (using supported social providers or login providers like Auth0, AWS Cognito, Firebase, or your own custom JWT login), you can add the configuration using the `authConnectionConfig` parameter during the initialization. +To use custom authentication with supported social providers or login providers like Auth0, AWS +Cognito, Firebase, or your own custom JWT, add the configuration using the `authConnectionConfig` +parameter during initialization. -The `authConnectionConfig` parameter is an array of `AuthConnectionConfig` instances, each defining a specific authentication connection. +The `authConnectionConfig` parameter is an array of `AuthConnectionConfig` instances, each defining +a specific authentication connection. ### Parameters @@ -50,6 +59,7 @@ After creating the auth connection from the [Embedded Wallets developer dashboar +<<<<<<< HEAD | Parameter | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authConnectionId` | The name of the auth connection that you have registered on the Embedded Wallets dashboard. It's a mandatory field, and accepts `String` as a value. | @@ -65,6 +75,24 @@ After creating the auth connection from the [Embedded Wallets developer dashboar | `showOnModal?` | Whether to show the login button on modal or not. Default is true. | | `showOnDesktop?` | Whether to show the login button on desktop. Default is true. | | `showOnMobile?` | Whether to show the login button on mobile. Default is true. | +======= +| Parameter | Description | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `authConnectionId` | Name of the auth connection registered in the Embedded Wallets dashboard. Required. `String`. | +| `authConnection` | Sign-in type for this connection. `.GOOGLE` triggers a Google sign-in flow; `.CUSTOM` expects your own JWT token with no sign-in flow. Required. `AuthConnection`. | +| `clientId` | Client ID from your sign-in provider (for example, Google Client ID), or your Embedded Wallets client ID when using `.CUSTOM`. Required. `String`. | +| `name?` | Display name for the auth connection. If `nil`, the default name is used. `String`. | +| `description?` | Description for the sign-in button. If provided, the button renders at full width; otherwise it renders as an icon button. `String`. | +| `groupedAuthConnectionId?` | JWT token field that maps to a grouped auth connection ID. Must match the JWT auth connection ID configured in the dashboard. `String`. | +| `logoHover?` | Logo shown on mouse hover. `String`. | +| `logoLight?` | Light logo for dark backgrounds. `String`. | +| `logoDark?` | Dark logo for light backgrounds. `String`. | +| `mainOption?` | Show the sign-in button on the main list. Default is `false`. `Bool`. | +| `showOnModal?` | Show the sign-in button on the modal. Default is `true`. `Bool`. | +| `showOnDesktop?` | Show the sign-in button on desktop. Default is `true`. `Bool`. | +| `showOnMobile?` | Show the sign-in button on mobile. Default is `true`. `Bool`. | + +>>>>>>> 6f369b09 (Initial custom-authentication edits.) @@ -212,7 +240,8 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio ## Configure extra sign-in options -Additional to the auth connection config during initialization, you can pass extra options to the `connectTo` function to configure the login flow for cases requiring additional info. The `ExtraLoginOptions` accepts the following parameters. +In addition to the auth connection config during initialization, you can pass extra options to the +`connectTo` function to configure the login flow. `ExtraLoginOptions` accepts the following parameters. ### Parameters @@ -226,6 +255,7 @@ Additional to the auth connection config during initialization, you can pass ext +<<<<<<< HEAD | Parameter | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `additionalParams?` | Additional params in `[String: String]` format for OAuth login, use id_token (JWT) to authenticate with Web3Auth. | @@ -250,6 +280,32 @@ Additional to the auth connection config during initialization, you can pass ext | `response_type?` | Defines which grant to execute for the authorization server. It accepts a string value. | | `nonce?` | nonce | | `redirect_uri?` | It can be used to specify the default URL where your custom JWT verifier can redirect your browser to with the result. If you are using Auth0, it must be allowlisted in the Allowed Callback URLs in your Auth0's application. | +======= +| Parameter | Description | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `additionalParams?` | Additional parameters in `[String: String]` format for OAuth sign-in. Use `id_token` (JWT) to authenticate with the SDK. `[String: String]`. | +| `domain?` | Custom authentication domain (for example, `example.au.auth0.com` for Auth0). `String`. | +| `client_id?` | Client ID from your sign-in provider for custom auth connections. `String`. | +| `leeway?` | Clock-skew tolerance for JWT expiration, in seconds. Recommended maximum is 120 seconds. `Int`. | +| `userIdField?` | JWT token field that maps to the user ID. Must match the JWT user ID configured in the dashboard. `String`. | +| `isUserIdCaseSensitive?` | Whether the user ID field is case-sensitive. `Bool`. | +| `display?` | OIDC `display` parameter controlling how the authentication UI renders (for example, `page`, `popup`, `touch`). `String`. | +| `prompt?` | OIDC `prompt` parameter shown during authentication (for example, `login`, `consent`, `none`). `String`. | +| `max_age?` | Maximum time (in seconds) since the last authentication before the user must re-authenticate. `String`. | +| `ui_locales?` | Space-separated list of language tags, ordered by preference (for example, `fr-CA fr en`). `String`. | +| `id_token_hint?` | Previously issued ID token, used as a hint for re-authentication. `String`. | +| `id_token?` | JWT (ID token) to pass for sign-in. `String`. | +| `access_token?` | Access token for OAuth flows. `String`. | +| `flow_type?` | Email passwordless flow type. `EmailFlowType` (`.code` or `.link`). | +| `acr_values?` | Authentication context class reference values requested from the provider. `String`. | +| `scope?` | Default scope for authentication requests. `String`. | +| `audience?` | Audience for the access token, presented as the `aud` claim. `String`. | +| `connection?` | Name of the connection configured for your dapp. If `nil`, redirects to the Auth0 sign-in page. `String`. | +| `state?` | Opaque value used to maintain state between the request and callback, preventing CSRF attacks. `String`. | +| `response_type?` | Grant type to execute for the authorization server. `String`. | +| `nonce?` | Random value used to prevent replay attacks in OIDC flows. `String`. | +| `redirect_uri?` | URL where your custom JWT verifier redirects the browser with the result. For Auth0, must be allowlisted in **Allowed Callback URLs** in your Auth0 application. | +>>>>>>> 6f369b09 (Initial custom-authentication edits.) @@ -302,7 +358,9 @@ public enum EmailFlowType: String, Codable { -Auth0 has a special login flow called the SPA flow. This flow requires a `client_id` and `domain` to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these configurations in the `ExtraLoginOptions` object in the login function. +Auth0 has a special login flow called the SPA flow. This flow requires a `client_id` and `domain`, and +the SDK retrieves the JWT `id_token` from Auth0 directly. Pass these values in the `ExtraLoginOptions` +object in the `connectTo` call. ```swift import Web3Auth @@ -341,7 +399,9 @@ let result = try await web3Auth.connectTo( -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 `idToken` field of `LoginParams`. For SFA (Single Factor Auth) mode, this enables direct authentication without additional login flows. +If you're using another provider like Firebase, AWS Cognito, or your own custom JWT server, pass the +JWT token in the `idToken` parameter of `LoginParams`. In Single Factor Auth (SFA) mode, this +enables direct authentication without additional login flows. ```swift import Web3Auth @@ -378,7 +438,9 @@ let result = try await web3Auth.connectTo( -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`. +For Email Passwordless login, pass the email address as the `loginHint` parameter of `LoginParams`. +The default flow is `code` (OTP). To use a magic link flow instead, set `flow_type` to `.link` in +`extraLoginOptions`. ```swift import Web3Auth @@ -408,7 +470,8 @@ let result = try await web3Auth.connectTo( -To use the SMS Passwordless login, send the phone number as the `loginHint` parameter of `LoginParams`. Please ensure the phone number takes the format: `+{country_code}-{phone_number}`, for example `+91-9911223344`. +For SMS Passwordless login, pass the phone number as the `loginHint` parameter of `LoginParams`. +The phone number must use the format `+{country_code}-{phone_number}`, for example `+91-9911223344`. ```swift import Web3Auth @@ -436,7 +499,9 @@ let result = try await web3Auth.connectTo( ### Grouped auth connection example -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. +Grouped auth connections combine multiple login methods so your users get the same address regardless +of how they sign in. For example, combine Google and Email Passwordless, or Google and GitHub via +Auth0, to resolve to the same address. ```swift import Web3Auth From 497ba6dc78999290be85cc13241875edc3b9753e Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Thu, 16 Apr 2026 11:42:13 +1000 Subject: [PATCH 03/24] Dapp share edits. Signed-off-by: bgravenorst --- .../sdk/ios/advanced/dapp-share.mdx | 69 ++++++++++++++----- 1 file changed, 51 insertions(+), 18 deletions(-) diff --git a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx index 4bcf2a23f08..7ae9ad48493 100644 --- a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx +++ b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx @@ -6,25 +6,47 @@ description: 'Web3Auth iOS SDK - dapp share | Embedded Wallets' ## Embedded Wallets infrastructure at a glance -As described in the [Embedded Wallets infrastructure](/embedded-wallets/infrastructure/), to enable the non custodiality of Web3Auth, we split the private key into multiple parts, that is, into `shares`. These shares are a part of the offchain multisig, where multiple shares are stored in different places and can be used to reconstruct the private key dynamically in the user's frontend application. Typically, there are 3 shares: - -1. **`ShareA` is managed by a login service via node operators:** This share is further split amongst a network of nodes and retrieved via conventional authentication flows. -2. **`ShareB` is stored on the user's device:** Implementation is device and system specific. For example, on mobile devices, the share could be stored in device storage secured via biometrics. -3. **`ShareC` is a recovery share:** An extra share to be kept by the user, possibly kept on a separate device, downloaded or based on user input with enough entropy (such as, password, security questions, hardware device). - -Similar to existing 2FA systems, a user needs to prove ownership of at least 2 out of 3 (2/3) shares, in order to retrieve their private key. This initial setup provides several benefits. +As described in the [Embedded Wallets infrastructure](/embedded-wallets/infrastructure/), to keep +Embedded Wallets non-custodial, the private key is split into multiple parts called `shares`. +These shares are a part of the offchain multisig, where multiple shares are stored in different +places and can be used to reconstruct the private key dynamically in the user's frontend +application. +Typically, there are 3 shares: + +1. **`ShareA` is managed by a login service via node operators:** This share is further split + amongst a network of nodes and retrieved via conventional authentication flows. +2. **`ShareB` is stored on the user's device:** Implementation is device and system specific. + For example, on mobile devices, the share could be stored in device storage secured via + biometrics. +3. **`ShareC` is a recovery share:** An extra share to be kept by the user, possibly kept on a + separate device, downloaded or based on user input with enough entropy (such as, password, + security questions, hardware device). + +Similar to existing 2FA systems, a user needs to prove ownership of at least 2 out of 3 (2/3) +shares to retrieve their private key. ## Mobile platform user experience -The user experience on mobile platforms differs from web platforms. This is because the user has to be redirected to a browser where they can login using their socials and then back to the app once they have been successfully authenticated. This user experience shifts the context between two applications, whereas, in the web platforms, the context remains within the browser only. +The user experience on mobile platforms differs from web platforms. +On mobile, the user is redirected to a browser to sign in with their social accounts and then +back to the app after authentication. +This shifts context between two applications, whereas on web platforms the context remains +within the browser only. -For the dapp share login flow, we need to reconstruct the Shares `A` and `B`. `Share B` is managed by the login service and is provided on successful authentication. Whereas in web platforms, `Share A` is stored in the browser context. We can still store it in the browser context for mobile devices, but this has a few risks like users accidentally deleting browser data. This is a bigger problem in mobile devices since the user doesn't realize that the browser is being used to login within the app and clearing the browser data can cause their logins to fail. Hence, to tackle this issue, Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after successful login by the user. +For a seamless sign-in flow, Shares `A` and `B` must be reconstructed. +`Share B` is managed by the sign-in service and is provided on successful authentication. +On web platforms, `Share A` is stored in the browser context. +You can still store it in the browser context on mobile devices, but this carries risks; users +may accidentally delete browser data. +This is a bigger problem on mobile because users don't realize the browser is used to sign in +within the app, and clearing browser data can cause sign-in to fail. +To address this, Embedded Wallets issues a dapp share, a backup share that you can store +directly in your app and use to reconstruct the private key after a successful sign-in. -## Dapp share in iOS -Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after successful login by the user. +## Dapp share in iOS -After a successful login from a user, the user details are returned as a response to the application in mobile devices. +After a successful sign-in, the SDK returns user details to your app. #### Sample response in iOS @@ -38,22 +60,33 @@ After a successful login from a user, the user details are returned as a respons "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 + "dappShare": "", // 24 words of seed phrase will be sent only in case of custom auth connections "idToken": "", - "oAuthIdToken": "", // will be sent only incase of custom auth connections - "oAuthAccessToken": "", // will be sent only incase of custom auth connections + "oAuthIdToken": "", // will be sent only in case of custom auth connections + "oAuthAccessToken": "", // will be sent only in case of custom auth connections "isMfaEnabled": false // Returns whether the user has enabled MFA or not } } ``` -Notice, the response has a field called `dappShare` which is a 24 words seed phrase that can be used to reconstruct the private key. This dappShare is a supplement to the `Share A` and represents half of the private key. The application can store the dapp share in their own application local storage safely. +The response includes a `dappShare` field, a 24-word seed phrase that can reconstruct the +private key. +`dappShare` supplements `Share A` and represents half of the private key. +You can store the dapp share safely in your app's local storage. + +During sign-in, the user's social account provides one share, and your app provides the dapp +share, removing the need to store a share in the browser context. +Pass the stored dapp share value in the `connectTo` call. -While logging in, the user can use their social accounts to obtain one share, and the application provides the dapp share, removing the need to store the share in the browser context and enabling user to sign in without repeating the full flow. This can be done by passing over the stored dapp share value in the login function. :::note -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. +`dappShare` is only available for custom auth connections, not standard Embedded Wallets auth +connections. +This ensures your app only has access to the share corresponding to your users' private keys. +To use dapp share, you must use the +[custom authentication](./custom-authentication.mdx) feature. +Dapp share is only returned to users who have enabled 2FA on their account. ::: From b3cb6e1318697fb117ee1b03e56ba2dadf05b4f7 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Thu, 16 Apr 2026 11:43:42 +1000 Subject: [PATCH 04/24] second round of dapp share edits. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/advanced/dapp-share.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx index 7ae9ad48493..ba8cc45c3bb 100644 --- a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx +++ b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx @@ -60,10 +60,10 @@ After a successful sign-in, the SDK returns user details to your app. "userId": "w3a-heroes@web3auth.com", "authConnection": "google", "groupedAuthConnectionId": "w3a-google-sapphire", - "dappShare": "", // 24 words of seed phrase will be sent only in case of custom auth connections + "dappShare": "", // 24 words of seed phrase will be sent only incase of custom auth connections "idToken": "", - "oAuthIdToken": "", // will be sent only in case of custom auth connections - "oAuthAccessToken": "", // will be sent only in case of custom auth connections + "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 } } From 60362f6c870fa7a0122c8ffe6648f3202976033a Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Thu, 16 Apr 2026 12:00:10 +1000 Subject: [PATCH 05/24] Edit readme file. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/advanced/README.mdx | 36 ++++++++++++++------ 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/embedded-wallets/sdk/ios/advanced/README.mdx b/embedded-wallets/sdk/ios/advanced/README.mdx index fd5d4c2026b..3b60f445a96 100644 --- a/embedded-wallets/sdk/ios/advanced/README.mdx +++ b/embedded-wallets/sdk/ios/advanced/README.mdx @@ -7,11 +7,12 @@ description: 'Web3Auth iOS SDK - Advanced Configuration | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -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. +The Embedded Wallets SDK offers configuration options to customize authentication flows, UI +appearance, blockchain integrations, and security features for your dapp. ## Configuration structure -When setting up Web3Auth, you'll pass in the options to the constructor. This consists of: +Pass options to the `Web3Auth` constructor during setup: ```swift import Web3Auth @@ -29,7 +30,7 @@ web3Auth = try await Web3Auth( ### `Web3AuthOptions` -The Web3Auth constructor takes a `Web3AuthOptions` struct as input. +The constructor takes a `Web3AuthOptions` struct as input. Date: Thu, 16 Apr 2026 12:17:45 +1000 Subject: [PATCH 06/24] Initial mfa edits. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/advanced/mfa.mdx | 58 ++++++++++++++++------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/embedded-wallets/sdk/ios/advanced/mfa.mdx b/embedded-wallets/sdk/ios/advanced/mfa.mdx index 4f2efa44458..58ec46d6e48 100644 --- a/embedded-wallets/sdk/ios/advanced/mfa.mdx +++ b/embedded-wallets/sdk/ios/advanced/mfa.mdx @@ -8,17 +8,31 @@ import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' import MFAMinimumPlan from '../../_common/_scale_plan_note.mdx' -At Web3Auth, we prioritize your security by offering Multi-Factor Authentication (MFA). MFA is an extra layer of protection that verifies your identity when accessing your account. To ensure ownership, you must provide two or more different backup factors. You have the option to choose from the device, social, backup factor (seed phrase), and password factors to guarantee access to your web3 account. Once you create a recovery factor, MFA is enabled, and your keys are divided into three shares for offchain multi-sig, making the key self-custodial. With backup factors, you can easily recover your account if you lose access to your original device or helps login into a new device. +Multi-Factor Authentication (MFA) adds an extra layer of protection that verifies your identity +when accessing your account. +To ensure ownership, you must provide two or more different backup factors. +Choose from device, social, backup factor (seed phrase), and password factors to secure access +to your web3 account. +Once you create a recovery factor, MFA is enabled, and your keys are divided into three shares +for offchain multi-sig, making the key self-custodial. +With backup factors, you can recover your account if you lose access to your original device or +need to sign in on a new device. + -## Enable using the Multi-Factor Authentication level +## Enable using the MFA level -For a dapp, we provide various options to set up Multi-Factor Authentication. You can customize the MFA screen by passing the `mfaLevel` parameter in `connectTo` method. You can enable or disable a backup factor and change their order. Currently, there are four values for MFA level. +Customize the MFA screen by passing the `mfaLevel` parameter in the `connectTo` method. +You can enable or disable a backup factor and change their order. +There are four MFA level values. :::caution Note -If you are using default auth connections, your users may have set up MFA on other dapps that also use default Web3Auth auth connections. In this case, the MFA screen will continue to appear if the user has enabled MFA on other dapps. This is because MFA cannot be turned off once it is enabled. +If you're using default auth connections, your users may have set up MFA on other dapps that +also use default Embedded Wallets auth connections. +In this case, the MFA screen continues to appear if the user has enabled MFA on other dapps. +MFA can't be turned off once enabled. ::: @@ -26,9 +40,9 @@ If you are using default auth connections, your users may have set up MFA on oth | MFA Level | Description | | --------- | ---------------------------------------------------------- | -| DEFAULT | Shows the MFA screen every third login. | -| OPTIONAL | Shows the MFA screen on every login, but user can skip it. | -| MANDATORY | Makes it mandatory to set up MFA after first login. | +| DEFAULT | Shows the MFA screen every third sign-in. | +| OPTIONAL | Shows the MFA screen on every sign-in, but user can skip it. | +| MANDATORY | Makes it mandatory to set up MFA after first sign-in. | | NONE | Skips the MFA setup screen. | ### Usage @@ -55,7 +69,10 @@ let result = try await web3Auth.connectTo( ## Explicitly enable MFA -The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will be used during custom auth connections. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT auth connections, you need to pass the valid JWT token in `LoginParams` as well. +The `enableMFA` method triggers the MFA setup flow for users. +It takes `LoginParams`, which is used during custom auth connections. +If you're using default sign-in providers, you don't need to pass `LoginParams`. +For custom JWT auth connections, pass the valid JWT token in `LoginParams`. -### Parameters - `MfaSetting` +### `MfaSetting` parameters -`MfaSetting` allows you to configure the behavior of an individual MFA factor. +`MfaSetting` configures the behavior of an individual MFA factor. Date: Thu, 16 Apr 2026 12:28:11 +1000 Subject: [PATCH 07/24] Inital smart account edits. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/advanced/smart-accounts.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx b/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx index e2671be8b7e..4098a422f41 100644 --- a/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx +++ b/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx @@ -7,17 +7,23 @@ description: 'Web3Auth iOS SDK - Smart Accounts and Wallet Services Configuratio import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The iOS SDK provides fine-grained control over the `showWalletUI` and `request` flows through the `walletServicesConfig` parameter in `Web3AuthOptions`. This lets you customize how transaction confirmations are displayed and tailor the wallet UI branding. +The iOS SDK provides fine-grained control over the `showWalletUI` and `request` flows through +the `walletServicesConfig` parameter in `Web3AuthOptions`. +Customize how transaction confirmations display and tailor the wallet UI branding. :::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 requires a paid plan. +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**. ::: ## `WalletServicesConfig` -Pass `walletServicesConfig` in `Web3AuthOptions` to configure how wallet services behave across your application. +Pass `walletServicesConfig` in `Web3AuthOptions` to configure how wallet services behave across +your dapp. ### Parameters From 1923a06d3cc4f9a943ada9cab20bf598f6e718fc Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Thu, 16 Apr 2026 12:36:46 +1000 Subject: [PATCH 08/24] Edit whitelabelling. Signed-off-by: bgravenorst --- .../sdk/ios/advanced/whitelabel.mdx | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/embedded-wallets/sdk/ios/advanced/whitelabel.mdx b/embedded-wallets/sdk/ios/advanced/whitelabel.mdx index a2141ae2e68..5e76031e2ad 100644 --- a/embedded-wallets/sdk/ios/advanced/whitelabel.mdx +++ b/embedded-wallets/sdk/ios/advanced/whitelabel.mdx @@ -10,7 +10,9 @@ import WhiteLabelShowcase from '../../_common/_whitelabel_showcase.mdx' import GrowthPlanNote from '../../_common/_growth_plan_note.mdx' import WhitelabelingNote from '../../_common/_whitelabeling_note.mdx' -Web3Auth allows complete whitelabeling with application branding for a consistent user experience. You can customize three different aspects: +Embedded Wallets supports whitelabeling with your dapp's branding for a consistent user +experience. +You can customize three aspects: - **UI elements:** Customize the appearance of modals and components - **Branding:** Apply your brand colors, logos, and themes @@ -20,15 +22,14 @@ Web3Auth allows complete whitelabeling with application branding for a consisten -## Customizing the Web3Auth login screens +## Customizing the Embedded Wallets sign-in screens -For defining custom UI, branding, and translations for your brand app, you just need to define an optional object called `WhiteLabelData`. `WhiteLabelData` can be defined during initialization of the SDK in `Web3AuthOptions`. +Define a `WhiteLabelData` object to customize UI, branding, and translations. +Pass it during initialization of the SDK in `Web3AuthOptions`. - - -### Arguments +### Parameters -The parameters which can be used to customize the user flow screens are given below: +The following parameters customize the sign-in screens: From 7224a3e1846ac56ee039be7921d29ba6a9af6d94 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Thu, 16 Apr 2026 13:23:15 +1000 Subject: [PATCH 09/24] Edit migration content. Signed-off-by: bgravenorst --- .../ios/migration-guides/ios-v11-to-v12.mdx | 40 ++++++++++++++----- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx b/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx index 4cb9ce68c4a..2165582faa1 100644 --- a/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx +++ b/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx @@ -4,13 +4,19 @@ description: 'iOS SDK v11 to v12 migration guide | Embedded Wallets' sidebar_label: v11 to v12 --- -This migration guide covers the breaking changes and enhancements introduced in v12 of the Web3Auth iOS SDK. Version 12 aligns the iOS SDK with the Android SDK v10 changes and introduces a new API surface with cleaner naming conventions. +This migration guide covers the breaking changes and enhancements introduced in v12 of the +Embedded Wallets iOS SDK. +Version 12 aligns the iOS SDK with the Android SDK v10 changes and introduces a new API surface +with cleaner naming conventions. ## Breaking changes ### Initialization: `W3AInitParams` renamed to `Web3AuthOptions` -The initialization struct has been renamed from `W3AInitParams` to `Web3AuthOptions`, and the constructor is now fully async. The separate `initialize()` call has been removed — session restoration happens automatically in the constructor. +The initialization struct has been renamed from `W3AInitParams` to `Web3AuthOptions`, and the +constructor is now fully async. +The separate `initialize()` call has been removed; session restoration happens automatically in +the constructor. **Network enum renamed**: `Network` is now `Web3AuthNetwork`, and enum cases are now uppercase (for example, `.sapphire_mainnet` becomes `.SAPPHIRE_MAINNET`). @@ -35,7 +41,10 @@ The new constructor throws if initialization fails, so wrap it in `do/catch`. ### URL callbacks removed -The `setResultUrl(url:)` method has been removed. The SDK now uses `ASWebAuthenticationSession` internally and handles all redirects automatically. Remove any calls to `setResultUrl` and the associated `onOpenURL` handler. +The `setResultUrl(url:)` method has been removed. +The SDK now uses `ASWebAuthenticationSession` internally and handles all redirects +automatically. +Remove any calls to `setResultUrl` and the associated `onOpenURL` handler. ```swift // remove-start @@ -69,7 +78,9 @@ let params = LoginParams(authConnection: .CUSTOM, authConnectionId: "your-connec ### `loginConfig` renamed to `authConnectionConfig`; `W3ALoginConfig` renamed to `AuthConnectionConfig` -The custom authentication configuration has changed from a dictionary (`[String: W3ALoginConfig]`) to an array (`[AuthConnectionConfig]`). The type itself has been renamed with updated field names. +The custom authentication configuration has changed from a dictionary +(`[String: W3ALoginConfig]`) to an array (`[AuthConnectionConfig]`). +The type itself has been renamed with updated field names. | Old field | New field | | ----------------------- | ------------------------- | @@ -129,7 +140,9 @@ let ed25519Key = try web3Auth.getEd25519PrivateKey() ### `launchWalletServices(chainConfig:)` renamed to `showWalletUI(path:)` -The chain configuration is no longer passed directly to the wallet services method. Instead, chain config comes from the project settings in the Web3Auth Dashboard or via the new `chains` parameter in `Web3AuthOptions`. +The chain configuration is no longer passed directly to the wallet services method. +Instead, chain config comes from the project settings in the Embedded Wallets dashboard or via +the new `chains` parameter in `Web3AuthOptions`. ```swift // remove-next-line @@ -140,7 +153,8 @@ try await web3Auth.showWalletUI() ### `request(chainConfig:method:requestParams:)` signature updated -The `chainConfig` parameter has been removed. Chain configuration now comes from the dashboard or `Web3AuthOptions.chains`. +The `chainConfig` parameter has been removed. +Chain configuration now comes from the dashboard or `Web3AuthOptions.chains`. ```swift // remove-start @@ -198,7 +212,9 @@ Web3AuthOptions( ### Chains configuration -You can now configure blockchain networks directly in `Web3AuthOptions` using the `chains` parameter. When set, these chains are used by wallet services in addition to any chains configured in the project dashboard. +Configure blockchain networks directly in `Web3AuthOptions` using the `chains` parameter. +When set, these chains are used by wallet services in addition to any chains configured in the +project dashboard. ```swift Web3AuthOptions( @@ -220,7 +236,8 @@ Web3AuthOptions( ### Wallet Services configuration -A new `walletServicesConfig` parameter in `Web3AuthOptions` lets you customize the confirmation strategy for transaction requests. +A new `walletServicesConfig` parameter in `Web3AuthOptions` lets you customize the confirmation +strategy for transaction requests. ```swift Web3AuthOptions( @@ -235,7 +252,9 @@ Web3AuthOptions( ### SFA (Single Factor Auth) mode -The `idToken` parameter in `LoginParams` enables direct SFA authentication. When provided, the SDK authenticates the user with the given JWT token without launching any browser-based login flow. +The `idToken` parameter in `LoginParams` enables direct SFA authentication. +When provided, the SDK authenticates the user with the given JWT token without launching any +browser-based sign-in flow. ```swift let result = try await web3Auth.connectTo( @@ -249,7 +268,8 @@ let result = try await web3Auth.connectTo( ### `loginHint` in `LoginParams` -A new `loginHint` parameter has been added directly to `LoginParams`, eliminating the need to nest it inside `ExtraLoginOptions` for passwordless flows. +A new `loginHint` parameter has been added directly to `LoginParams`, eliminating the need to +nest it inside `ExtraLoginOptions` for passwordless flows. ```swift // Old way From b4445417b3c424dc10ee9fa5102e54efeab0af38 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Thu, 16 Apr 2026 14:08:45 +1000 Subject: [PATCH 10/24] Edit initial connect to content. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/connectTo.mdx | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/connectTo.mdx b/embedded-wallets/sdk/ios/usage/connectTo.mdx index 663bcfacb7e..0a69d3bbd19 100644 --- a/embedded-wallets/sdk/ios/usage/connectTo.mdx +++ b/embedded-wallets/sdk/ios/usage/connectTo.mdx @@ -1,5 +1,5 @@ --- -title: Logging in a User +title: Sign in a user sidebar_label: connectTo description: 'Web3Auth iOS SDK - connectTo Function | Embedded Wallets' --- @@ -7,9 +7,13 @@ description: 'Web3Auth iOS SDK - connectTo Function | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -To log in a user, use the `connectTo` method. It triggers the login flow and navigates the user to a browser modal allowing them to authenticate. You can pass in the supported auth connections to the method for specific social logins (such as `.GOOGLE`, `.APPLE`, `.FACEBOOK`) and do whitelabel login. +To sign in a user, use the `connectTo` method. +It triggers the sign-in flow and navigates the user to a browser modal for authentication. +Pass supported auth connections for specific social sign-ins (such as `.GOOGLE`, `.APPLE`, +`.FACEBOOK`) or use whitelabel sign-in. -For SFA (Single Factor Auth) login with a JWT token, pass the `idToken` parameter to authenticate directly without the browser modal. +For SFA (Single Factor Auth) sign-in with a JWT token, pass the `idToken` parameter to +authenticate directly without the browser modal. ## Parameters @@ -267,7 +271,9 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio -For SFA (Single Factor Auth) mode, pass the JWT token via `idToken` to authenticate directly without any browser-based login flow. This is useful when you already have a JWT from your own authentication system. +For SFA (Single Factor Auth) mode, pass the JWT token via `idToken` to authenticate directly +without any browser-based sign-in flow. +This is useful when you already have a JWT from your own authentication system. ```swift import Web3Auth @@ -284,7 +290,7 @@ let web3Auth = try await Web3Auth( let result = try await web3Auth.connectTo( loginParams: LoginParams( authConnection: .CUSTOM, - authConnectionId: "your-auth-connection-id", // Get it from Web3Auth Dashboard + authConnectionId: "your-auth-connection-id", // Get it from the Embedded Wallets dashboard idToken: "your_jwt_token" ) ) From cfcbc7f2cac9414e12366a3e8b092ac9ce178a1d Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 08:02:28 +1000 Subject: [PATCH 11/24] Edit enable MFA content. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/enable-mfa.mdx | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/enable-mfa.mdx b/embedded-wallets/sdk/ios/usage/enable-mfa.mdx index efa37b888f9..2a565272415 100644 --- a/embedded-wallets/sdk/ios/usage/enable-mfa.mdx +++ b/embedded-wallets/sdk/ios/usage/enable-mfa.mdx @@ -7,7 +7,13 @@ description: 'Web3Auth iOS SDK - enableMFA | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The `enableMFA` method is used to trigger MFA setup flow for users. The method takes `LoginParams` which will be used during custom auth connections. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT auth connections, you need to pass the valid JWT token in `LoginParams` as well. +The `enableMFA` method triggers multi-factor authentication (MFA) setup for users, adding an +additional recovery factor to protect wallet access. +It accepts an optional `LoginParams` parameter. + +- If you use a default sign-in provider, call `enableMFA()` without arguments. +- If you use a custom JWT auth connection, pass a `LoginParams` object that includes the valid JWT + token. ## Usage @@ -37,7 +43,9 @@ do { :::warning -SFA mode users (authenticated via `idToken`) cannot enable MFA. The `enableMFA` call will throw an error if the user was authenticated using a JWT token directly. +Single-factor authentication (SFA) mode users (authenticated directly via `idToken`) cannot enable +MFA. +The `enableMFA` call throws an error if the user signed in using a JWT token directly. ::: From b81f38602ea41c98dcd4a1f9973125edbbc3d087 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 08:07:52 +1000 Subject: [PATCH 12/24] Edit get private key info. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/getPrivateKey.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx b/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx index 9772d3aab67..acdbfa6267a 100644 --- a/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx +++ b/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx @@ -4,9 +4,12 @@ sidebar_label: getPrivateKey description: 'Web3Auth iOS SDK - getPrivateKey | Embedded Wallets' --- -To retrieve the secp256k1 private key of the user, use the `getPrivateKey` method. The method returns an EVM compatible private key which can be used to sign transactions on EVM-compatible chains. +The `getPrivateKey` method returns the user's secp256k1 private key (the elliptic curve used by +Ethereum and EVM-compatible chains). +Use this key to sign transactions on EVM-compatible chains. -When `useSFAKey` is set to `true` in `Web3AuthOptions`, this method returns the SFA (Single Factor Auth) key instead of the standard private key. +When you set `useSFAKey` to `true` in `Web3AuthOptions`, this method returns the single-factor +authentication (SFA) key instead of the standard private key. ## Usage From e0707b11eb4422dd39ccd7c282d97c72d8b84952 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 08:12:10 +1000 Subject: [PATCH 13/24] Edit 25519 PK content. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx b/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx index 12c89b90027..30da0585feb 100644 --- a/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx +++ b/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx @@ -4,9 +4,11 @@ sidebar_label: getEd25519PrivateKey description: 'Web3Auth iOS SDK - getEd25519PrivateKey | Embedded Wallets' --- -To retrieve the Ed25519 private key of the user, use the `getEd25519PrivateKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. +The `getEd25519PrivateKey` method returns the user's Ed25519 private key. +Use this key to sign transactions on Solana, Near, Algorand, and other chains that use the Ed25519 +curve. -The method throws if no user session is found or if the key is unavailable. +This method throws an error if no user session exists or if the key is unavailable. ## Usage From 451d949addc6a8b15b829c09cfd69239446b6482 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 08:17:05 +1000 Subject: [PATCH 14/24] Edit user info content. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/get-user-info.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/get-user-info.mdx b/embedded-wallets/sdk/ios/usage/get-user-info.mdx index 406a904d590..4418fb3bd5c 100644 --- a/embedded-wallets/sdk/ios/usage/get-user-info.mdx +++ b/embedded-wallets/sdk/ios/usage/get-user-info.mdx @@ -4,9 +4,10 @@ sidebar_label: Get user info description: 'Web3Auth iOS SDK - getUserInfo | Embedded Wallets' --- -You can use the `getUserInfo` method to retrieve various details about the user, such as their login type, whether multi-factor authentication (MFA) is enabled, profile image, name, and other relevant information. +The `getUserInfo` method returns details about the user, including sign-in type, whether +multi-factor authentication (MFA) is enabled, profile image, and name. -The method throws if no user session is found. +This method throws an error if no user session exists. ## Usage @@ -14,7 +15,7 @@ The method throws if no user session is found. let web3AuthUserInfo = try web3Auth.getUserInfo() ``` -## `getUserInfo` response +## Example response ```json { From f056c83a9c0e9d76f4abb428d8664b1603db56ab Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 08:31:44 +1000 Subject: [PATCH 15/24] Edit manage MFA content. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/manage-mfa.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/manage-mfa.mdx b/embedded-wallets/sdk/ios/usage/manage-mfa.mdx index c64c1609efa..1d4c18c0a4f 100644 --- a/embedded-wallets/sdk/ios/usage/manage-mfa.mdx +++ b/embedded-wallets/sdk/ios/usage/manage-mfa.mdx @@ -7,7 +7,13 @@ description: 'Web3Auth iOS SDK - manageMFA | Embedded Wallets' import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -The `manageMFA` method is used to trigger manage MFA flow for users, allowing users to update their MFA settings. The method takes `LoginParams` which will be used during custom auth connections. If you are using default login providers, you don't need to pass `LoginParams`. If you are using custom JWT auth connections, you need to pass the JWT token in `LoginParams` as well. +The `manageMFA` method triggers the multi-factor authentication (MFA) management flow, allowing +users to update their MFA settings. +It accepts an optional `LoginParams` parameter. + +- If you use a default sign-in provider, call `manageMFA()` without arguments. +- If you use a custom JWT auth connection, pass a `LoginParams` object that includes the JWT + token. ## Usage @@ -41,8 +47,8 @@ do { ```swift let loginParams = LoginParams( authConnection: .CUSTOM, - authConnectionId: "your-auth-connection-id", - idToken: "your_jwt_token" + authConnectionId: "", + idToken: "" ) do { From a1cfaadf71e3215be804f4bec61bfc929176e9e5 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 08:36:05 +1000 Subject: [PATCH 16/24] Edit readme file. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/README.mdx | 51 +++++++++++------------ 1 file changed, 24 insertions(+), 27 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/README.mdx b/embedded-wallets/sdk/ios/usage/README.mdx index 12391d6cfb9..0eaf0e6e0e8 100644 --- a/embedded-wallets/sdk/ios/usage/README.mdx +++ b/embedded-wallets/sdk/ios/usage/README.mdx @@ -4,46 +4,43 @@ sidebar_label: Overview description: 'Web3Auth iOS SDK Functions | Embedded Wallets' --- -Embedded Wallets provides a comprehensive set of functions to handle authentication, user management, and blockchain interactions in your iOS applications. These functions allow you to implement features like user login, multi-factor authentication, private key retrieval, and Wallet Services with minimal effort. Each function is designed to handle a specific aspect of Embedded Wallets' functionality, making it easy to integrate into your iOS projects. +Embedded Wallets provides methods for authentication, user management, and blockchain interactions +in your iOS applications. +Use these methods to implement sign-in, multi-factor authentication (MFA), private key retrieval, +and Wallet Services. -## List of functions +## Available methods -:::tip +### Authentication methods -For detailed usage, configuration options, and code examples, refer to the dedicated documentation page for each function. +| Method | Description | +| ---------------------------------- | ------------------------------------------------------ | +| [`connectTo()`](./connectTo.mdx) | Signs in the user with the selected auth connection. | +| [`logout()`](./logout.mdx) | Signs out the user from the current session. | -::: +### User management methods -### Authentication functions - -| Function Name | Description | -| -------------------------------- | --------------------------------------------------- | -| [`connectTo()`](./connectTo.mdx) | Logs in the user with the selected auth connection. | -| [`logout()`](./logout.mdx) | Logs out the user from the current session. | - -### User management functions - -| Function Name | Description | +| Method | Description | | -------------------------------------- | ----------------------------------------------- | | [`getUserInfo()`](./get-user-info.mdx) | Retrieves the authenticated user's information. | -### Private key functions +### Private key methods -| Function Name | Description | -| ------------------------------------------------------ | ------------------------------------------------------------------------------- | -| [`getPrivateKey()`](./getPrivateKey.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | -| [`getEd25519PrivateKey()`](./getEd25519PrivateKey.mdx) | Retrieve the user's ed25519 private key for chains like Solana, Near, Algorand. | +| Method | Description | +| ------------------------------------------------------ | -------------------------------------------------------------------------------- | +| [`getPrivateKey()`](./getPrivateKey.mdx) | Retrieves the user's secp256k1 private key for EVM-compatible chains. | +| [`getEd25519PrivateKey()`](./getEd25519PrivateKey.mdx) | Retrieves the user's Ed25519 private key for chains like Solana, Near, Algorand. | -### Security functions +### Security methods -| Function Name | Description | -| --------------------------------- | ------------------------------------------------- | -| [`enableMFA()`](./enable-mfa.mdx) | Enables Multi-Factor Authentication for the user. | -| [`manageMFA()`](./manage-mfa.mdx) | Allows users to manage their MFA settings. | +| Method | Description | +| ---------------------------------- | ---------------------------------------- | +| [`enableMFA()`](./enable-mfa.mdx) | Enables MFA for the user. | +| [`manageMFA()`](./manage-mfa.mdx) | Manages MFA settings for the user. | -### Wallet Services functions +### Wallet Services methods -| Function Name | Description | +| Method | Description | | -------------------------------------- | ----------------------------------------------------------------- | | [`showWalletUI()`](./showWalletUI.mdx) | Launches the templated wallet UI in WebView. | | [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions. | From 0c09da87680578b86f472e8de8e0bff18f661bad Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 08:50:54 +1000 Subject: [PATCH 17/24] Edit request page. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/request.mdx | 26 +++++++++++++--------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/request.mdx b/embedded-wallets/sdk/ios/usage/request.mdx index cba576027f6..ed5aa9b2796 100644 --- a/embedded-wallets/sdk/ios/usage/request.mdx +++ b/embedded-wallets/sdk/ios/usage/request.mdx @@ -4,11 +4,17 @@ sidebar_label: Send requests description: 'Web3Auth iOS SDK - request | Embedded Wallets' --- -The `request` method facilitates the use of templated transaction screens for signing transactions. The method returns a `SignResponse?`. It can be used to sign transactions for any EVM chain and screens can be whitelabeled to your branding. +The `request` method opens templated transaction screens for signing transactions. +The method returns a `SignResponse?`. +Use it to sign transactions on any EVM chain. +You can white-label the screens to match your branding. -Please check the list of [JSON RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/), noting that the request method currently supports only the signing methods. +See the list of [JSON-RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/). +The `request` method currently supports only signing methods. + +The SDK retrieves chain configuration automatically from your project settings in the Embedded +Wallets dashboard. -Chain configuration is retrieved automatically from your project settings in the Embedded Wallets dashboard. Date: Fri, 17 Apr 2026 09:12:04 +1000 Subject: [PATCH 18/24] Edit show wallet UI. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/showWalletUI.mdx | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/showWalletUI.mdx b/embedded-wallets/sdk/ios/usage/showWalletUI.mdx index 4540c41660d..e72e590fd39 100644 --- a/embedded-wallets/sdk/ios/usage/showWalletUI.mdx +++ b/embedded-wallets/sdk/ios/usage/showWalletUI.mdx @@ -4,11 +4,22 @@ sidebar_label: showWalletUI description: 'Web3Auth iOS SDK - showWalletUI | Embedded Wallets' --- -The `showWalletUI` method launches a WebView which allows you to use the templated wallet UI services. Chain configuration is retrieved automatically from your project settings in the Web3Auth Dashboard. Wallet Services is currently only available for EVM chains. +The `showWalletUI` method launches a WebView with the templated wallet UI. +The SDK retrieves chain configuration automatically from your project settings in the Embedded +Wallets dashboard. + +:::info + +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**. +Access to Wallet Services is gated. +This feature is free in `sapphire_devnet`. +The minimum [pricing plan](https://web3auth.io/pricing.html) to use this feature in production is +the **Scale Plan**. ::: From fb2dd61dc1a2367f06638e5a8341c0f31b8702a0 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 09:35:14 +1000 Subject: [PATCH 19/24] Edit readme file. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/README.mdx | 80 ++++++++++++++++------------- 1 file changed, 43 insertions(+), 37 deletions(-) diff --git a/embedded-wallets/sdk/ios/README.mdx b/embedded-wallets/sdk/ios/README.mdx index cabee68369b..d60d97c1e9c 100644 --- a/embedded-wallets/sdk/ios/README.mdx +++ b/embedded-wallets/sdk/ios/README.mdx @@ -9,24 +9,18 @@ import Tabs from '@theme/Tabs' ## Overview -MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play) provides authentication for iOS applications with social logins, external wallets, and more. Our iOS SDK, written in Swift, simplifies connecting users to their preferred wallets and manage authentication state natively. +The MetaMask Embedded Wallets SDK for iOS (formerly Web3Auth Plug and Play) supports social +sign-ins, external wallets, and native authentication state management. +The SDK is written in Swift. -## Requirements +## Prerequisites - iOS 14+ - Xcode 12+ - Swift 5.x -- Basic knowledge of Swift and iOS Development - -## Prerequisites - -- Set up your project on the [Embedded Wallets dashboard](https://developer.metamask.io/) - -:::tip - -See the [dashboard setup](../../dashboard/README.mdx) guide to learn more. - -::: +- A project configured on the + [Embedded Wallets dashboard](https://developer.metamask.io/). + See the [dashboard setup](../../dashboard/README.mdx) guide for details. ## Installation @@ -42,9 +36,10 @@ Install the Web3Auth iOS SDK using one of the following methods: https://github.com/Web3Auth/web3auth-swift-sdk ``` - From the **Dependency Rule** dropdown, select **Exact Version** and enter **12.0.1** as the version. + From the **Dependency Rule** dropdown, select **Exact Version** and enter **12.0.1** as the + version. -3. When finished, Xcode will automatically begin resolving and downloading your dependencies in the background. +3. Xcode automatically resolves and downloads your dependencies in the background. ### CocoaPods @@ -60,14 +55,18 @@ pod 'Web3Auth', '~> 12.0.1' ### Configure redirection -To use Embedded Wallets for iOS you need to allowlist your `bundleId` in your Embedded Wallets project. +To use Embedded Wallets for iOS, allowlist your `bundleId` in your Embedded Wallets project. -- Go to [Embedded Wallets developer dashboard](https://developer.metamask.io), and create or open an existing Embedded Wallets project. -- Allowlist `{bundleId}://auth` in the dashboard. This step is mandatory for the redirect to work. +- Go to the [Embedded Wallets developer dashboard](https://developer.metamask.io) and create or + open an existing project. +- Allowlist `{bundleId}://auth` in the dashboard. + This step is mandatory for the redirect to work. ## Initialize Embedded Wallets -The iOS SDK uses an async initializer. The constructor fetches project configuration and restores any active session automatically. There is no separate `initialize()` call. +The iOS SDK uses an async initializer. +The constructor fetches project configuration and restores any active session automatically. +The SDK does not require a separate `initialize()` call. ### Create and initialize an Embedded Wallets instance @@ -84,16 +83,16 @@ class ViewModel: ObservableObject { // focus-start web3Auth = try await Web3Auth( options: Web3AuthOptions( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from MetaMask Developer Dashboard + clientId: "", // From the Embedded Wallets dashboard web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET - redirectUrl: "com.yourapp.bundleid://auth" + redirectUrl: "://auth" ) ) // focus-end // Check for an active session if web3Auth?.web3AuthResponse != nil { - // User is already logged in + // User is already signed in } } catch { print("Error initializing Web3Auth: \(error)") @@ -104,13 +103,15 @@ class ViewModel: ObservableObject { :::note -The async constructor throws if the project configuration fetch fails or if a stored session token is invalid. Wrap it in `do/catch` and treat any error as a failed initialization rather than an absent session. +The async constructor throws if the project configuration fetch fails or if a stored session token +is invalid. +Wrap it in `do/catch` and treat any error as a failed initialization rather than an absent session. ::: ## Advanced configuration -The Embedded Wallets iOS SDK offers a rich set of advanced configuration options: +The Embedded Wallets iOS SDK supports several advanced configuration options: - **[Custom authentication](./advanced/custom-authentication.mdx):** Define authentication methods. - **[Whitelabeling and UI customization](./advanced/whitelabel.mdx):** Personalize the modal's appearance. @@ -136,9 +137,9 @@ See the [advanced configuration sections](./advanced/) to learn more about each ```swift web3Auth = try await Web3Auth( options: Web3AuthOptions( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", + clientId: "", web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET - redirectUrl: "com.yourapp.bundleid://auth" + redirectUrl: "://auth" ) ) ``` @@ -150,12 +151,12 @@ web3Auth = try await Web3Auth( ```swift web3Auth = try await Web3Auth( options: Web3AuthOptions( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", + clientId: "", web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET - redirectUrl: "com.yourapp.bundleid://auth", + redirectUrl: "://auth", authConnectionConfig: [ AuthConnectionConfig( - authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnectionId: "", // From the Embedded Wallets dashboard authConnection: .GOOGLE, clientId: "YOUR_GOOGLE_CLIENT_ID" ) @@ -174,17 +175,19 @@ web3Auth = try await Web3Auth( -## Single Factor Auth (SFA) support +## Single-factor authentication (SFA) support -The iOS SDK includes built-in support for Single Factor Auth (SFA), allowing seamless authentication when you already have a JWT token from your own authentication system. When MFA is disabled, users are authenticated directly using your JWT token, making the login experience completely frictionless. +The iOS SDK supports single-factor authentication (SFA), which authenticates users directly with a +JWT token from your own authentication system. +When MFA is disabled, users sign in using only the JWT token. ```swift -// SFA login with custom JWT +// SFA sign-in with custom JWT let result = try await web3Auth.connectTo( loginParams: LoginParams( authConnection: .CUSTOM, - authConnectionId: "your-auth-connection-id", - idToken: "your_jwt_token" + authConnectionId: "", + idToken: "" ) ) ``` @@ -193,11 +196,13 @@ SFA mode is activated automatically when you provide an `idToken` parameter. ## Blockchain integration -Embedded Wallets is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Embedded Wallets offers robust support for both **Solana** and **Ethereum**. +Embedded Wallets supports any blockchain network, with built-in support for **Ethereum** and +**Solana**. ### Ethereum integration -For Ethereum integration, you can get the private key using the `getPrivateKey` method and use it with web3.swift or other Ethereum libraries: +Get the private key using the `getPrivateKey` method and use it with web3.swift or other Ethereum +libraries: ```swift import web3 @@ -232,7 +237,8 @@ let balance = toEther(wei: balanceResponse) ### Solana integration -For Solana integration, you can get the Ed25519 private key using the `getEd25519PrivateKey` method and use it with SolanaSwift or any other Solana libraries: +Get the Ed25519 private key using the `getEd25519PrivateKey` method and use it with SolanaSwift or +other Solana libraries: ```swift import SolanaSwift From b78fe4d3aa9796d75dff94a2424f2aaf12268fd2 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Fri, 17 Apr 2026 09:49:06 +1000 Subject: [PATCH 20/24] Prettier updates. Signed-off-by: bgravenorst --- embedded-wallets/sdk/ios/usage/README.mdx | 16 ++++++++-------- embedded-wallets/sdk/ios/usage/request.mdx | 10 +++++----- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/embedded-wallets/sdk/ios/usage/README.mdx b/embedded-wallets/sdk/ios/usage/README.mdx index 0eaf0e6e0e8..4f04d531556 100644 --- a/embedded-wallets/sdk/ios/usage/README.mdx +++ b/embedded-wallets/sdk/ios/usage/README.mdx @@ -13,10 +13,10 @@ and Wallet Services. ### Authentication methods -| Method | Description | -| ---------------------------------- | ------------------------------------------------------ | -| [`connectTo()`](./connectTo.mdx) | Signs in the user with the selected auth connection. | -| [`logout()`](./logout.mdx) | Signs out the user from the current session. | +| Method | Description | +| -------------------------------- | ---------------------------------------------------- | +| [`connectTo()`](./connectTo.mdx) | Signs in the user with the selected auth connection. | +| [`logout()`](./logout.mdx) | Signs out the user from the current session. | ### User management methods @@ -33,10 +33,10 @@ and Wallet Services. ### Security methods -| Method | Description | -| ---------------------------------- | ---------------------------------------- | -| [`enableMFA()`](./enable-mfa.mdx) | Enables MFA for the user. | -| [`manageMFA()`](./manage-mfa.mdx) | Manages MFA settings for the user. | +| Method | Description | +| --------------------------------- | ---------------------------------- | +| [`enableMFA()`](./enable-mfa.mdx) | Enables MFA for the user. | +| [`manageMFA()`](./manage-mfa.mdx) | Manages MFA settings for the user. | ### Wallet Services methods diff --git a/embedded-wallets/sdk/ios/usage/request.mdx b/embedded-wallets/sdk/ios/usage/request.mdx index ed5aa9b2796..412016a7e37 100644 --- a/embedded-wallets/sdk/ios/usage/request.mdx +++ b/embedded-wallets/sdk/ios/usage/request.mdx @@ -24,12 +24,12 @@ Wallets dashboard. ## Parameters -| Parameter | Description | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `method` | JSON RPC method name in `String`. Currently, the request method only supports the signing methods. | +| Parameter | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `method` | JSON RPC method name in `String`. Currently, the request method only supports the signing methods. | | `requestParams` | Parameters for the corresponding method, in the correct sequence. See [JSON-RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/) for details. | -| `path?` | Path in the wallet WebView. Defaults to `"wallet/request"`. | -| `appState?` | Optional app state string to be passed through the request flow. | +| `path?` | Path in the wallet WebView. Defaults to `"wallet/request"`. | +| `appState?` | Optional app state string to be passed through the request flow. | ## Usage From bd7e42b33dd9306bfd4bb26849cb671a1526a5c2 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Thu, 2 Jul 2026 15:39:13 +0400 Subject: [PATCH 21/24] Update iOS docs for Web3Auth Swift SDK v12. Fix stale connect-blockchain snippets, consolidate the migration guide to v12, and correct quickstart sign-in references. Co-authored-by: Cursor --- .../_evm-get-account.mdx | 14 +- .../connect-blockchain/solana/ios.mdx | 20 +- embedded-wallets/migration-guides/README.mdx | 4 +- embedded-wallets/migration-guides/ios.mdx | 110 +++++-- .../ios/migration-guides/ios-v11-to-v12.mdx | 290 ------------------ embedded-wallets/sdk/ios/usage/logout.mdx | 2 +- .../ios/stepContent/signin.mdx | 2 +- 7 files changed, 101 insertions(+), 341 deletions(-) delete mode 100644 embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx diff --git a/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx b/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx index c45eb1f2835..68fe878e4eb 100644 --- a/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx +++ b/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx @@ -2,20 +2,20 @@ Use the `EthereumAccount` class to retrieve the user's Ethereum address. This ac also be used to sign transactions and messages. The package doesn't provides any direct way to consume the the private key and create an account. -Hence, we'll create an extension for the `Web3AuthState` extending the +Hence, we'll create an extension for the `Web3AuthResponse` extending the `EthereumSingleKeyStorageProtocol` to retrieve the private key and create an account. ```swift import web3 import Web3Auth -extension Web3AuthState: EthereumSingleKeyStorageProtocol { +extension Web3AuthResponse: EthereumSingleKeyStorageProtocol { public func storePrivateKey(key: Data) throws { } public func loadPrivateKey() throws -> Data { - guard let data = self.privKey?.web3.hexData else { + guard let data = self.privateKey?.web3.hexData else { throw PlaygroundError.decodingError } @@ -24,15 +24,15 @@ extension Web3AuthState: EthereumSingleKeyStorageProtocol { } ``` -Once we have created the extension, we can use the Web3AuthState to create an `EthereumAccount`. -Please note, that this assumes that the user has already logged in and the state is available. +Once we have created the extension, we can use the `Web3AuthResponse` to create an `EthereumAccount`. +Please note, that this assumes that the user has already logged in and the response is available. ```swift import web3 // Use your existing Web3Auth instance -let web3authState = web3Auth.state! +let web3AuthResponse = web3Auth.web3AuthResponse! -let account = try EthereumAccount(keyStorage: web3authState) +let account = try EthereumAccount(keyStorage: web3AuthResponse) let address = account.address ``` diff --git a/embedded-wallets/connect-blockchain/solana/ios.mdx b/embedded-wallets/connect-blockchain/solana/ios.mdx index 7d8ea9ba271..2e85fb4f63f 100644 --- a/embedded-wallets/connect-blockchain/solana/ios.mdx +++ b/embedded-wallets/connect-blockchain/solana/ios.mdx @@ -136,9 +136,9 @@ let solanaJSONRPCClient = JSONRPCAPIClient(endpoint: endpoint) ### Initializing the Web3Auth SDK -In the following code block, we'll initialize the Web3Auth SDK and check whether the user has any Web3Auth session persisted or not. If the user is already authenticated, you can route them directly to home view, otherwise you can route them to login view for authentication purpose. For checking, if user is already authenticated, we can check whether `Web3Auth.state` is `nil` or not. +In the following code block, we'll initialize the Web3Auth SDK and check whether the user has any Web3Auth session persisted or not. If the user is already authenticated, you can route them directly to home view, otherwise you can route them to login view for authentication purpose. For checking, if user is already authenticated, we can check whether `web3Auth.web3AuthResponse` is `nil` or not. -By default, the session is persisted for 1 day. You can modify it using `sessionTime` parameter during initialization. +By default, the session is persisted for 30 days. You can modify it using `sessionTime` parameter during initialization. :::note @@ -151,27 +151,27 @@ import Web3Auth // Initialize Web3Auth SDK // focus-start -let web3Auth = await Web3Auth( - W3AInitParams( +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( clientId: "BPi5PB_UiIZ-cPz1GtV5i1I2iOSOHuimiXBI0e-Oe_u6X3oVAbCiAZOTEBtTXw4tsluTITPqA8zMsfxIKMjiqNQ", - network: Network.sapphire_mainnet, - redirectUrl: "com.w3a.ios-solana-example" + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.w3a.ios-solana-example://auth" ) ) // focus-end -// Check whether state is nil or not for user authentication status. -let isUserAuthenticated = web3Auth.state != nil +// Check whether web3AuthResponse is nil or not for user authentication status. +let isUserAuthenticated = web3Auth.web3AuthResponse != nil // Customize your logic to perform operations or navigation ``` ## Get account -We can use `getEd25519PrivKey` method in Web3Auth to retrive the priavte key for the Solana ecosystem. In the following code block, we'll use the Ed25519 private key to retive user's public address by creating `KeyPair`. The `KeyPair` struct from `SolanaSwift` SDK once created can be used to sign the Solana transactions. +We can use `getEd25519PrivateKey` method in Web3Auth to retrive the priavte key for the Solana ecosystem. In the following code block, we'll use the Ed25519 private key to retive user's public address by creating `KeyPair`. The `KeyPair` struct from `SolanaSwift` SDK once created can be used to sign the Solana transactions. ```swift -let ed25519PrivateKey = web3Auth.getEd25519PrivKey() +let ed25519PrivateKey = try web3Auth.getEd25519PrivateKey() let keyPair = try KeyPair(secretKey: Data(hex: ed25519PrivateKey)) // focus-next-line diff --git a/embedded-wallets/migration-guides/README.mdx b/embedded-wallets/migration-guides/README.mdx index e4723946b0a..58fd3406398 100644 --- a/embedded-wallets/migration-guides/README.mdx +++ b/embedded-wallets/migration-guides/README.mdx @@ -30,8 +30,8 @@ current SDK in one pass. | Platform | Upgrade to | Covers upgrades from | | ---------------------------------------------------------------------- | ---------- | -------------------- | | [Web (JavaScript, React, Vue)](/embedded-wallets/migration-guides/web) | v11 | v9 through v10 | -| [Android](/embedded-wallets/migration-guides/android) | v10 | v4 through v9 | -| [iOS](/embedded-wallets/migration-guides/ios) | v10 | v6 through v9 | +| [Android](/embedded-wallets/migration-guides/android) | v9 | v4 through v8 | +| [iOS](/embedded-wallets/migration-guides/ios) | v12 | v6 through v11 | | [React Native](/embedded-wallets/migration-guides/react-native) | v9 | v3 through v8 | | [Flutter](/embedded-wallets/migration-guides/flutter) | v6 | v3 through v5 | diff --git a/embedded-wallets/migration-guides/ios.mdx b/embedded-wallets/migration-guides/ios.mdx index 384648ff252..51dadcadee6 100644 --- a/embedded-wallets/migration-guides/ios.mdx +++ b/embedded-wallets/migration-guides/ios.mdx @@ -1,12 +1,16 @@ --- -title: iOS SDK v10 Migration Guide -sidebar_label: iOS SDK v10 -description: Upgrade the Embedded Wallets iOS SDK directly from older versions to v10. -keywords: [migration, v10, ios, web3auth, embedded wallets, swift] +title: iOS SDK v12 Migration Guide +sidebar_label: iOS SDK v12 +description: Upgrade the Embedded Wallets iOS SDK directly from older versions to v12. +keywords: [migration, v12, ios, web3auth, embedded wallets, swift] --- -This guide upgrades Embedded Wallets iOS SDK integrations from **v6 through v9** directly to -**v10**. +This guide upgrades Embedded Wallets iOS SDK integrations from **v6 through v11** directly to +**v12**. + +If you're already on v11, focus on the [v12 changes](#v12-changes). +For older versions, apply the sections below that match your current version, then complete the v12 +updates. ## AI-assisted migration @@ -19,21 +23,21 @@ Copy the prompt below into your AI coding assistant (Cursor, Claude Code, Codex, similar): ```txt -Migrate my MetaMask Embedded Wallets iOS (web3auth-swift-sdk) project to v10. +Migrate my MetaMask Embedded Wallets iOS (web3auth-swift-sdk) project to v12. Before changing code: 1. Use the web3auth skill and MCP tools (search_docs, get_doc, get_example, get_sdk_reference). -2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/ios-v10 +2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/ios/ 3. Detect my current SDK version from Package.swift or Podfile and list which breaking changes apply. -Then migrate my codebase directly to v10: -- Update the Web3Auth dependency to v10.0.1 (Swift Package Manager or CocoaPods). -- Use .sapphire_mainnet or .sapphire_devnet for the network. -- Add mandatory redirectUrl to W3AInitParams ({bundleId}://auth). -- Replace getSignResponse() with the SignResponse returned from request(). -- Remove loginParams from launchWalletServices and request; pass chainConfig instead. -- Move chainConfig from W3AInitParams to launchWalletServices (v8.1+). -- Update W3AWhiteLabelData fields (appName, mode) if whitelabeling is configured. +Then migrate my codebase directly to v12: +- Update the Web3Auth dependency to 12.0.1 (Swift Package Manager or CocoaPods). +- Replace W3AInitParams with Web3AuthOptions (web3AuthNetwork: .SAPPHIRE_MAINNET or .SAPPHIRE_DEVNET). +- Replace login/W3ALoginParams with connectTo/LoginParams(authConnection:). +- Replace loginConfig with authConnectionConfig ([AuthConnectionConfig]). +- Replace getPrivKey/getEd25519PrivKey with getPrivateKey/getEd25519PrivateKey(). +- Replace launchWalletServices(chainConfig:) with showWalletUI() and configure chains in Web3AuthOptions. +- Remove chainConfig from request(); configure chains at init instead. - Do not change my Client ID or Sapphire network unless I ask; that would change wallet addresses. After migrating, list every file you changed and any manual dashboard steps I still need to do. @@ -46,7 +50,7 @@ Review the plan before generating code; config mistakes can change wallet addres ::: -## Install v10 +## Install v12 ### Swift Package Manager @@ -56,14 +60,14 @@ In Xcode, go to **File > Add Package Dependencies** and add: https://github.com/Web3Auth/web3auth-swift-sdk ``` -Select **Exact Version** and enter **10.0.1**. +Select **Exact Version** and enter **12.0.1**. ### CocoaPods Add to your `Podfile`: ```sh -pod 'Web3Auth', '~> 10.0.1' +pod 'Web3Auth', '~> 12.0.1' ``` Then run `pod install`. @@ -74,7 +78,52 @@ Allowlist `{bundleId}://auth` on the ## Breaking changes Apply the sections below that match your current version. -If you're already on v9, focus on the [v10 changes](#v10-changes). +If you're already on v11, focus on the [v12 changes](#v12-changes). + +### v12 changes {#v12-changes} + +v12 introduces a cleaner API surface. Key renames: + +| v11 and earlier | v12 | +| --------------------------------------- | ------------------------------------------------------ | +| `W3AInitParams` | `Web3AuthOptions` | +| `network: .sapphire_mainnet` | `web3AuthNetwork: .SAPPHIRE_MAINNET` | +| `login(W3ALoginParams(loginProvider:))` | `connectTo(loginParams: LoginParams(authConnection:))` | +| `Web3AuthProvider` / `.JWT` | `AuthConnection` / `.CUSTOM` | +| `loginConfig` | `authConnectionConfig` | +| `web3Auth.state` | `web3Auth.web3AuthResponse` | +| `getPrivKey()` | `getPrivateKey()` | +| `getEd25519PrivKey()` | `getEd25519PrivateKey()` (throws) | +| `launchWalletServices(chainConfig:)` | `showWalletUI()` | +| `request(chainConfig:...)` | `request(method:requestParams:)` | + +```swift +// v12 initialization +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" + ) + ] + ) +) + +// v12 login +let result = try await web3Auth.connectTo( + loginParams: LoginParams(authConnection: .GOOGLE) +) + +// v12 wallet services +try await web3Auth.showWalletUI() +``` + +Remove any `setResultUrl` / `onOpenURL` handlers — v12 uses `ASWebAuthenticationSession` internally. ### Network and init params (from v7) @@ -190,20 +239,21 @@ If you're upgrading from an older SDK, adopt the v10 signatures shown above. | SMS Passwordless login | v8.3 | `Web3AuthProvider.SMS_PASSWORDLESS` with `loginHint` | | Farcaster login | v8.3 | `.Farcaster` login provider | -See [Wallet Services](/embedded-wallets/sdk/ios/usage/launch-wallet-services) and +See [Wallet Services](/embedded-wallets/sdk/ios/usage/showWalletUI) and [MFA](/embedded-wallets/sdk/ios/advanced/mfa) for usage details. ## Summary table -| Area | Before v7 | v7-v9 | v10 | -| ---------------------- | ------------------------- | -------------------------- | --------------------------- | -| Network | `.mainnet`, `.cyan`, etc. | Sapphire supported | Sapphire recommended | -| `redirectUrl` | Optional | Mandatory (v8.4+) | Mandatory | -| Whitelabel `name` | `name` | `appName` | `appName` | -| `chainConfig` in init | N/A | Removed (v8.1) | Removed | -| `launchWalletServices` | N/A | Drops `loginParams` (v8.2) | `chainConfig` only | -| `request` | N/A | Drops `loginParams` (v8.3) | Returns `SignResponse` | -| Sign result | N/A | `getSignResponse()` | Return value of `request()` | +| Area | Before v7 | v7-v11 | v12 | +| ----------------- | ------------------------- | ------------------------ | --------------------------- | +| Network | `.mainnet`, `.cyan`, etc. | Sapphire supported | `.SAPPHIRE_MAINNET` | +| Init params | `W3AInitParams` | `W3AInitParams` | `Web3AuthOptions` | +| Login | N/A | `login(W3ALoginParams)` | `connectTo(LoginParams)` | +| `redirectUrl` | Optional | Mandatory (v8.4+) | Mandatory | +| Whitelabel `name` | `name` | `appName` | `appName` | +| Wallet UI | N/A | `launchWalletServices` | `showWalletUI()` | +| `request` | N/A | `chainConfig` parameter | Chains in `Web3AuthOptions` | +| Sign result | N/A | `getSignResponse()` (v9) | Return value of `request()` | ## Next steps diff --git a/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx b/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx deleted file mode 100644 index 2165582faa1..00000000000 --- a/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx +++ /dev/null @@ -1,290 +0,0 @@ ---- -title: iOS SDK - v11 to v12 -description: 'iOS SDK v11 to v12 migration guide | Embedded Wallets' -sidebar_label: v11 to v12 ---- - -This migration guide covers the breaking changes and enhancements introduced in v12 of the -Embedded Wallets iOS SDK. -Version 12 aligns the iOS SDK with the Android SDK v10 changes and introduces a new API surface -with cleaner naming conventions. - -## Breaking changes - -### Initialization: `W3AInitParams` renamed to `Web3AuthOptions` - -The initialization struct has been renamed from `W3AInitParams` to `Web3AuthOptions`, and the -constructor is now fully async. -The separate `initialize()` call has been removed; session restoration happens automatically in -the constructor. - -**Network enum renamed**: `Network` is now `Web3AuthNetwork`, and enum cases are now uppercase (for example, `.sapphire_mainnet` becomes `.SAPPHIRE_MAINNET`). - -```swift -// remove-next-line -web3Auth = await Web3Auth(W3AInitParams( -// add-next-line -web3Auth = try await Web3Auth(options: Web3AuthOptions( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", -// remove-next-line - network: .sapphire_mainnet, -// add-next-line - web3AuthNetwork: .SAPPHIRE_MAINNET, - redirectUrl: "com.yourapp.bundleid://auth" -)) - -// remove-next-line -await web3Auth.initialize() -``` - -The new constructor throws if initialization fails, so wrap it in `do/catch`. - -### URL callbacks removed - -The `setResultUrl(url:)` method has been removed. -The SDK now uses `ASWebAuthenticationSession` internally and handles all redirects -automatically. -Remove any calls to `setResultUrl` and the associated `onOpenURL` handler. - -```swift -// remove-start -.onOpenURL { url in - Web3Auth.setResultUrl(url) -} -// remove-end -``` - -### `login()` renamed to `connectTo()` - -The `login` method and `W3ALoginParams` have been replaced by `connectTo` and `LoginParams`. - -```swift -// remove-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .GOOGLE)) -// add-next-line -let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .GOOGLE)) -``` - -### `Web3AuthProvider` renamed to `AuthConnection`; `.JWT` renamed to `.CUSTOM` - -The login provider enum has been renamed from `Web3AuthProvider` to `AuthConnection`. The `.JWT` case is now `.CUSTOM`. - -```swift -// remove-next-line -let params = W3ALoginParams(loginProvider: .JWT, extraLoginOptions: .init(id_token: "...")) -// add-next-line -let params = LoginParams(authConnection: .CUSTOM, authConnectionId: "your-connection-id", idToken: "your_jwt_token") -``` - -### `loginConfig` renamed to `authConnectionConfig`; `W3ALoginConfig` renamed to `AuthConnectionConfig` - -The custom authentication configuration has changed from a dictionary -(`[String: W3ALoginConfig]`) to an array (`[AuthConnectionConfig]`). -The type itself has been renamed with updated field names. - -| Old field | New field | -| ----------------------- | ------------------------- | -| `verifier` | `authConnectionId` | -| `typeOfLogin` | `authConnection` | -| `verifierSubIdentifier` | `groupedAuthConnectionId` | - -```swift -// remove-start -loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "your-verifier-name", - typeOfLogin: .google, - clientId: "YOUR_GOOGLE_CLIENT_ID", - verifierSubIdentifier: "sub-verifier" - ) -] -// remove-end -// add-start -authConnectionConfig: [ - AuthConnectionConfig( - authConnectionId: "your-auth-connection-id", - authConnection: .GOOGLE, - clientId: "YOUR_GOOGLE_CLIENT_ID", - groupedAuthConnectionId: "sub-connection" - ) -] -// add-end -``` - -### `ExtraLoginOptions`: `verifierIdField` and `isVerifierIdCaseSensitive` renamed - -```swift -// remove-next-line -ExtraLoginOptions(verifierIdField: "sub", isVerifierIdCaseSensitive: false) -// add-next-line -ExtraLoginOptions(userIdField: "sub", isUserIdCaseSensitive: false) -``` - -### `getPrivKey()` renamed to `getPrivateKey()` - -```swift -// remove-next-line -let privateKey = web3Auth.getPrivKey() -// add-next-line -let privateKey = web3Auth.getPrivateKey() -``` - -### `getEd25519PrivKey()` renamed to `getEd25519PrivateKey()` - -```swift -// remove-next-line -let ed25519Key = web3Auth.getEd25519PrivKey() -// add-next-line -let ed25519Key = try web3Auth.getEd25519PrivateKey() -``` - -### `launchWalletServices(chainConfig:)` renamed to `showWalletUI(path:)` - -The chain configuration is no longer passed directly to the wallet services method. -Instead, chain config comes from the project settings in the Embedded Wallets dashboard or via -the new `chains` parameter in `Web3AuthOptions`. - -```swift -// remove-next-line -try await web3Auth.launchWalletServices(chainConfig: ChainConfig(chainId: "0x89", rpcTarget: "https://rpc.ankr.com/polygon")) -// add-next-line -try await web3Auth.showWalletUI() -``` - -### `request(chainConfig:method:requestParams:)` signature updated - -The `chainConfig` parameter has been removed. -Chain configuration now comes from the dashboard or `Web3AuthOptions.chains`. - -```swift -// remove-start -let response = try await web3Auth.request( - chainConfig: ChainConfig(chainId: "0x89", rpcTarget: "https://rpc.ankr.com/polygon"), - method: "personal_sign", - requestParams: params -) -// remove-end -// add-start -let response = try await web3Auth.request( - method: "personal_sign", - requestParams: params -) -// add-end -``` - -### `Web3AuthUserInfo` field renames - -The following fields in `Web3AuthUserInfo` (returned by `getUserInfo()`) have been renamed: - -| Old field name | New field name | -| ------------------- | ------------------------- | -| `verifier` | `authConnectionId` | -| `verifierId` | `userId` | -| `typeOfLogin` | `authConnection` | -| `aggregateVerifier` | `groupedAuthConnectionId` | - -Update any code that reads these fields from the user info response. - -### `useCoreKitKey` renamed to `useSFAKey` - -```swift -// remove-next-line -Web3AuthOptions(clientId: "...", web3AuthNetwork: .SAPPHIRE_MAINNET, redirectUrl: "...", useCoreKitKey: true) -// add-next-line -Web3AuthOptions(clientId: "...", web3AuthNetwork: .SAPPHIRE_MAINNET, redirectUrl: "...", useSFAKey: true) -``` - -### Session time default changed - -The default `sessionTime` has changed from **7 days** to **30 days**. If you were relying on the 7-day default, set `sessionTime` explicitly: - -```swift -Web3AuthOptions( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", - web3AuthNetwork: .SAPPHIRE_MAINNET, - redirectUrl: "com.yourapp.bundleid://auth", - // add-next-line - sessionTime: 86400 * 7 // Explicitly set to 7 days if needed -) -``` - -## New features - -### Chains configuration - -Configure blockchain networks directly in `Web3AuthOptions` using the `chains` parameter. -When set, these chains are used by wallet services in addition to any chains configured in the -project dashboard. - -```swift -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 - -A new `walletServicesConfig` parameter in `Web3AuthOptions` lets you customize the confirmation -strategy for transaction requests. - -```swift -Web3AuthOptions( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", - web3AuthNetwork: .SAPPHIRE_MAINNET, - redirectUrl: "com.yourapp.bundleid://auth", - walletServicesConfig: WalletServicesConfig( - confirmationStrategy: .modal - ) -) -``` - -### SFA (Single Factor Auth) mode - -The `idToken` parameter in `LoginParams` enables direct SFA authentication. -When provided, the SDK authenticates the user with the given JWT token without launching any -browser-based sign-in flow. - -```swift -let result = try await web3Auth.connectTo( - loginParams: LoginParams( - authConnection: .CUSTOM, - authConnectionId: "your-auth-connection-id", - idToken: "your_jwt_token" - ) -) -``` - -### `loginHint` in `LoginParams` - -A new `loginHint` parameter has been added directly to `LoginParams`, eliminating the need to -nest it inside `ExtraLoginOptions` for passwordless flows. - -```swift -// Old way -let result = try await web3Auth.login( - W3ALoginParams( - loginProvider: .EMAIL_PASSWORDLESS, - extraLoginOptions: .init(loginHint: "hello@web3auth.io") - ) -) - -// New way -let result = try await web3Auth.connectTo( - loginParams: LoginParams( - authConnection: .EMAIL_PASSWORDLESS, - loginHint: "hello@web3auth.io" - ) -) -``` diff --git a/embedded-wallets/sdk/ios/usage/logout.mdx b/embedded-wallets/sdk/ios/usage/logout.mdx index 4a11756d82d..77b728b381d 100644 --- a/embedded-wallets/sdk/ios/usage/logout.mdx +++ b/embedded-wallets/sdk/ios/usage/logout.mdx @@ -9,5 +9,5 @@ To logout the user and remove the session ID from the device you can use the `lo ## Usage ```swift -try await web3auth.logout() +try await web3Auth.logout() ``` diff --git a/src/pages/quickstart/builder/embedded-wallets/ios/stepContent/signin.mdx b/src/pages/quickstart/builder/embedded-wallets/ios/stepContent/signin.mdx index 16b4268d9b5..7b5896190f9 100644 --- a/src/pages/quickstart/builder/embedded-wallets/ios/stepContent/signin.mdx +++ b/src/pages/quickstart/builder/embedded-wallets/ios/stepContent/signin.mdx @@ -1,6 +1,6 @@ ### Sign in the user -Use the [`login`](/embedded-wallets/sdk/ios/usage/login) function to access +Use the [`connectTo`](/embedded-wallets/sdk/ios/usage/connectTo) function to access the sign-in functionality. You can trigger this function from a button or other user action. From 16a7966eb4977be782ca83e5838a336a07a6c7c7 Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Thu, 2 Jul 2026 20:31:42 +0400 Subject: [PATCH 22/24] Fix for vale and style guide --- .../_evm-get-account.mdx | 2 +- .../connect-blockchain/solana/ios.mdx | 24 +-- embedded-wallets/migration-guides/ios.mdx | 10 +- embedded-wallets/sdk/ios/README.mdx | 2 +- embedded-wallets/sdk/ios/advanced/README.mdx | 10 +- .../ios/advanced/custom-authentication.mdx | 142 ++++++------------ .../sdk/ios/advanced/dapp-share.mdx | 8 +- embedded-wallets/sdk/ios/advanced/mfa.mdx | 25 ++- .../sdk/ios/advanced/smart-accounts.mdx | 6 +- .../sdk/ios/advanced/whitelabel.mdx | 20 +-- embedded-wallets/sdk/ios/usage/README.mdx | 8 +- embedded-wallets/sdk/ios/usage/connectTo.mdx | 58 +++---- embedded-wallets/sdk/ios/usage/logout.mdx | 2 +- embedded-wallets/sdk/ios/usage/request.mdx | 5 +- .../sdk/ios/usage/showWalletUI.mdx | 8 +- 15 files changed, 138 insertions(+), 192 deletions(-) diff --git a/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx b/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx index 68fe878e4eb..a35fb30c279 100644 --- a/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx +++ b/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx @@ -1,7 +1,7 @@ Use the `EthereumAccount` class to retrieve the user's Ethereum address. This account can also be used to sign transactions and messages. -The package doesn't provides any direct way to consume the the private key and create an account. +The package doesn't provide any direct way to consume the private key and create an account. Hence, we'll create an extension for the `Web3AuthResponse` extending the `EthereumSingleKeyStorageProtocol` to retrieve the private key and create an account. diff --git a/embedded-wallets/connect-blockchain/solana/ios.mdx b/embedded-wallets/connect-blockchain/solana/ios.mdx index 2e85fb4f63f..8c7a1844a14 100644 --- a/embedded-wallets/connect-blockchain/solana/ios.mdx +++ b/embedded-wallets/connect-blockchain/solana/ios.mdx @@ -10,7 +10,7 @@ description: 'Integrate Embedded Wallets with the Solana Blockchain in iOS | Emb import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -While using the Embedded Wallets iOS SDK (formerly Web3Auth), you can retrieve the Ed25519 private key upon successful authentication. This private key can be used to derive the user's public address and interact with the [Solana](https://solana.org/) chain. We've highlighted a few methods here to get you started quickly. +While using the Embedded Wallets iOS SDK (formerly Web3Auth), you can retrieve the Ed25519 private key upon successful authentication. This private key can be used to derive the user's public address and interact with the [Solana](https://solana.org/) chain. We've highlighted a few methods here to get you started. :::note @@ -72,14 +72,14 @@ The SDKs are now branded as MetaMask Embedded Wallet SDKs (formerly Web3Auth Plu To interact with the Solana blockchain in iOS, you can use any Solana compatible SDK. Here, we're using [SolanaSwift](https://github.com/p2p-org/solana-swift) to demonstrate how to interact with Solana chain using Web3Auth. - - + To install `SolanaSwift` through Swift Package Manager, follow the below steps: @@ -97,7 +97,7 @@ Once finished, Xcode will automatically begin resolving and downloading your dep - + To install using CocoaPods, simply add the following line to your Podfile @@ -116,7 +116,7 @@ pod install ## Initialize -To Initialize the `JSONRPCAPIClient` we require a RPC URL. The `JSONRPCAPIClient` instance will provide a gateway & protocol to interact with Solana cluster while sending requests and receving response. For this example, we are using the RPC URL for Devnet-beta. To interact with Testnet or Mainnet, change the RPC URL. +To Initialize the `JSONRPCAPIClient` we require a RPC URL. The `JSONRPCAPIClient` instance will provide a gateway & protocol to interact with Solana cluster while sending requests and receiving response. For this example, we are using the RPC URL for Devnet-beta. To interact with Testnet or Mainnet, change the RPC URL. ### Initializing the Solana SDK @@ -136,7 +136,7 @@ let solanaJSONRPCClient = JSONRPCAPIClient(endpoint: endpoint) ### Initializing the Web3Auth SDK -In the following code block, we'll initialize the Web3Auth SDK and check whether the user has any Web3Auth session persisted or not. If the user is already authenticated, you can route them directly to home view, otherwise you can route them to login view for authentication purpose. For checking, if user is already authenticated, we can check whether `web3Auth.web3AuthResponse` is `nil` or not. +In the following code block, we'll initialize the Web3Auth SDK and check whether the user has any Web3Auth session persisted or not. If the user is already authenticated, you can route them directly to home view, otherwise you can route them to the sign-in view for authentication purpose. For checking, if user is already authenticated, we can check whether `web3Auth.web3AuthResponse` is `nil` or not. By default, the session is persisted for 30 days. You can modify it using `sessionTime` parameter during initialization. @@ -168,7 +168,7 @@ let isUserAuthenticated = web3Auth.web3AuthResponse != nil ## Get account -We can use `getEd25519PrivateKey` method in Web3Auth to retrive the priavte key for the Solana ecosystem. In the following code block, we'll use the Ed25519 private key to retive user's public address by creating `KeyPair`. The `KeyPair` struct from `SolanaSwift` SDK once created can be used to sign the Solana transactions. +We can use `getEd25519PrivateKey` method in Web3Auth to retrieve the private key for the Solana ecosystem. In the following code block, we'll use the Ed25519 private key to retrieve user's public address by creating `KeyPair`. The `KeyPair` struct from `SolanaSwift` SDK once created can be used to sign the Solana transactions. ```swift let ed25519PrivateKey = try web3Auth.getEd25519PrivateKey() @@ -180,7 +180,7 @@ let userAccount = keyPair.publicKey.base58EncodedString ## Get User balance -Once we have retrived userAccount, we can use it to fetch user balance. We'll use `getBalance` method from `JSONRPCAPIClient` instance to interact with Solana cluster and fetch user balance. The response of `getBalance` is UInt64, we will need to divide it by 10^9, because Solana's token decimals is 9. To help us with the calculation, the SDK also provides a `convertToBalance` function. +Once we have retrieved `userAccount`, we can use it to fetch user balance. We'll use `getBalance` method from `JSONRPCAPIClient` instance to interact with Solana cluster and fetch user balance. The response of `getBalance` is UInt64, we will need to divide it by 10^9, because Solana's token decimals is 9. To help us with the calculation, the SDK also provides a `convertToBalance` function. ```swift // focus-start @@ -197,7 +197,7 @@ let userBalance = return balanceResponse.convertToBalance(decimals: 9) ## Sign a transaction -Let's now go through how can we sign the transaction. In the below codeblock, we'll create a new function `perpareTransaction` which can be used to retrive the Base58 signature as well as broadcast transaction to the cluster. We'll use `BlockchainClient.prepareSendingNativeSOL` to create the transaction to self transfer 0.01 Sol and sign it. You can also checkout `prepareSendingSPLTokens`, and `prepareTransaction` for other types of transaction. +Let's now go through how can we sign the transaction. In the below code block, we'll create a new function `perpareTransaction` which can be used to retrieve the Base58 signature as well as broadcast transaction to the cluster. We'll use `BlockchainClient.prepareSendingNativeSOL` to create the transaction to self transfer 0.01 Sol and sign it. You can also checkout `prepareSendingSPLTokens`, and `prepareTransaction` for other types of transaction. ```swift let blockchainClient = BlockchainClient(apiClient: solanaJSONRPCClient) @@ -213,7 +213,7 @@ let blockchainClient = BlockchainClient(apiClient: solanaJSONRPCClient) } ``` -Once we have created `perpareTransaction` function, we'll use it to prepare, sign the transaction, and retrive Base58 signature. You can use `findSignature` to retrive the signature for the respective signer. +Once we have created `perpareTransaction` function, we'll use it to prepare, sign the transaction, and retrieve Base58 signature. You can use `findSignature` to retrieve the signature for the respective signer. ```swift do { diff --git a/embedded-wallets/migration-guides/ios.mdx b/embedded-wallets/migration-guides/ios.mdx index 51dadcadee6..ac9398c9142 100644 --- a/embedded-wallets/migration-guides/ios.mdx +++ b/embedded-wallets/migration-guides/ios.mdx @@ -123,7 +123,7 @@ let result = try await web3Auth.connectTo( try await web3Auth.showWalletUI() ``` -Remove any `setResultUrl` / `onOpenURL` handlers — v12 uses `ASWebAuthenticationSession` internally. +Remove any `setResultUrl` / `onOpenURL` handlers; v12 uses `ASWebAuthenticationSession` internally. ### Network and init params (from v7) @@ -234,10 +234,10 @@ If you're upgrading from an older SDK, adopt the v10 signatures shown above. | API | Added in | Purpose | | ------------------------ | -------- | ---------------------------------------------------- | | `enableMFA()` | v8 | Initiate MFA setup for logged-in users | -| `launchWalletServices()` | v8 | Open the templated wallet UI | +| `launchWalletServices()` | v8 | Open the built-in wallet UI | | `request()` | v8 | Sign transactions with confirmation screens | -| SMS Passwordless login | v8.3 | `Web3AuthProvider.SMS_PASSWORDLESS` with `loginHint` | -| Farcaster login | v8.3 | `.Farcaster` login provider | +| SMS Passwordless sign-in | v8.3 | `Web3AuthProvider.SMS_PASSWORDLESS` with `loginHint` | +| Farcaster sign-in | v8.3 | `.Farcaster` sign-in provider | See [Wallet Services](/embedded-wallets/sdk/ios/usage/showWalletUI) and [MFA](/embedded-wallets/sdk/ios/advanced/mfa) for usage details. @@ -248,7 +248,7 @@ See [Wallet Services](/embedded-wallets/sdk/ios/usage/showWalletUI) and | ----------------- | ------------------------- | ------------------------ | --------------------------- | | Network | `.mainnet`, `.cyan`, etc. | Sapphire supported | `.SAPPHIRE_MAINNET` | | Init params | `W3AInitParams` | `W3AInitParams` | `Web3AuthOptions` | -| Login | N/A | `login(W3ALoginParams)` | `connectTo(LoginParams)` | +| Sign-in | N/A | `login(W3ALoginParams)` | `connectTo(LoginParams)` | | `redirectUrl` | Optional | Mandatory (v8.4+) | Mandatory | | Whitelabel `name` | `name` | `appName` | `appName` | | Wallet UI | N/A | `launchWalletServices` | `showWalletUI()` | diff --git a/embedded-wallets/sdk/ios/README.mdx b/embedded-wallets/sdk/ios/README.mdx index d60d97c1e9c..1e71f8eff72 100644 --- a/embedded-wallets/sdk/ios/README.mdx +++ b/embedded-wallets/sdk/ios/README.mdx @@ -64,7 +64,7 @@ To use Embedded Wallets for iOS, allowlist your `bundleId` in your Embedded Wall ## Initialize Embedded Wallets -The iOS SDK uses an async initializer. +The iOS SDK uses an async initialization pattern. The constructor fetches project configuration and restores any active session automatically. The SDK does not require a separate `initialize()` call. diff --git a/embedded-wallets/sdk/ios/advanced/README.mdx b/embedded-wallets/sdk/ios/advanced/README.mdx index 3b60f445a96..495e357ae01 100644 --- a/embedded-wallets/sdk/ios/advanced/README.mdx +++ b/embedded-wallets/sdk/ios/advanced/README.mdx @@ -50,7 +50,7 @@ The constructor takes a `Web3AuthOptions` struct as input. | `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 pregeneration and SFA mode. | +| `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`. | @@ -62,7 +62,7 @@ The constructor takes a `Web3AuthOptions` struct as input. | `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. | +| `walletServicesConfig?` | Configuration for Wallet Services including whitelabel options. Takes `WalletServicesConfig` as a value. | @@ -97,7 +97,6 @@ Control how long users stay authenticated and how sessions persist. The session - `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`). @@ -116,7 +115,7 @@ web3Auth = try await Web3Auth( ## 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 +When set, these chains are used by Wallet Services (`showWalletUI`, `request`) in addition to any chains configured in the project dashboard. ### `Chains` fields @@ -180,7 +179,7 @@ For full configuration options, see the [Smart Accounts](./smart-accounts.mdx) s | 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`. | +| `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( @@ -207,7 +206,6 @@ Customize the Embedded Wallets sign-in screens to match your dapp's design. For complete customization options, see [Whitelabeling and UI customization](./whitelabel.mdx). - ## Multi-Factor Authentication Add security layers to protect user accounts with two-factor authentication. diff --git a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx index a50466d65a7..4cbb2f83b80 100644 --- a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx @@ -23,7 +23,6 @@ they don't see any authentication modal or branding. [Create a connection](../../../dashboard/authentication.mdx) from the **Authentication** tab of your project in the [Embedded Wallets developer dashboard](https://developer.metamask.io). - ::: Provide your connection details in the Embedded Wallets dashboard to generate an `authConnectionId`. @@ -38,8 +37,7 @@ See [authentication provider setup](../../../authentication/README.mdx) for avai ## Configuration -To use custom authentication with supported social providers or login providers like Auth0, AWS -Cognito, Firebase, or your own custom JWT, add the configuration using the `authConnectionConfig` +To use custom authentication with supported social providers or sign-in providers like Auth0, `AWS Cognito`, Firebase, or your own custom JWT, add the configuration using the `authConnectionConfig` parameter during initialization. The `authConnectionConfig` parameter is an array of `AuthConnectionConfig` instances, each defining @@ -59,40 +57,21 @@ After creating the auth connection from the [Embedded Wallets developer dashboar -<<<<<<< HEAD -| Parameter | Description | -| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `authConnectionId` | The name of the auth connection that you have registered on the Embedded Wallets dashboard. It's a mandatory field, and accepts `String` as a value. | -| `authConnection` | Type of login of this auth connection. 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. For example, Google's Client ID or Web3Auth's Client ID if using `.CUSTOM` as `AuthConnection`. It's a mandatory field, and accepts `String` as a value. | -| `name?` | Display name for the auth connection. If nil, 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 the correct JWT auth connection ID in the developer dashboard. It accepts `String` as a value. | -| `logoHover?` | Logo to be shown on mouse hover. It accepts `String` as a value. | -| `logoLight?` | Light logo for dark background. It accepts `String` as a value. | -| `logoDark?` | Dark logo for light background. It accepts `String` as a value. | -| `mainOption?` | Show login button on the main list. It accepts `Bool` as a value. Default is false. | -| `showOnModal?` | Whether to show the login button on modal or not. Default is true. | -| `showOnDesktop?` | Whether to show the login button on desktop. Default is true. | -| `showOnMobile?` | Whether to show the login button on mobile. Default is true. | -======= -| Parameter | Description | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `authConnectionId` | Name of the auth connection registered in the Embedded Wallets dashboard. Required. `String`. | -| `authConnection` | Sign-in type for this connection. `.GOOGLE` triggers a Google sign-in flow; `.CUSTOM` expects your own JWT token with no sign-in flow. Required. `AuthConnection`. | -| `clientId` | Client ID from your sign-in provider (for example, Google Client ID), or your Embedded Wallets client ID when using `.CUSTOM`. Required. `String`. | -| `name?` | Display name for the auth connection. If `nil`, the default name is used. `String`. | -| `description?` | Description for the sign-in button. If provided, the button renders at full width; otherwise it renders as an icon button. `String`. | -| `groupedAuthConnectionId?` | JWT token field that maps to a grouped auth connection ID. Must match the JWT auth connection ID configured in the dashboard. `String`. | -| `logoHover?` | Logo shown on mouse hover. `String`. | -| `logoLight?` | Light logo for dark backgrounds. `String`. | -| `logoDark?` | Dark logo for light backgrounds. `String`. | -| `mainOption?` | Show the sign-in button on the main list. Default is `false`. `Bool`. | -| `showOnModal?` | Show the sign-in button on the modal. Default is `true`. `Bool`. | -| `showOnDesktop?` | Show the sign-in button on desktop. Default is `true`. `Bool`. | -| `showOnMobile?` | Show the sign-in button on mobile. Default is `true`. `Bool`. | - ->>>>>>> 6f369b09 (Initial custom-authentication edits.) +| Parameter | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `authConnectionId` | Name of the auth connection registered in the Embedded Wallets dashboard. Required. `String`. | +| `authConnection` | Sign-in type for this connection. `.GOOGLE` triggers a Google sign-in flow; `.CUSTOM` expects your own JWT token with no sign-in flow. Required. `AuthConnection`. | +| `clientId` | Client ID from your sign-in provider (for example, Google Client ID), or your Embedded Wallets client ID when using `.CUSTOM`. Required. `String`. | +| `name?` | Display name for the auth connection. If `nil`, the default name is used. `String`. | +| `description?` | Description for the sign-in button. If provided, the button renders at full width; otherwise it renders as an icon button. `String`. | +| `groupedAuthConnectionId?` | JWT token field that maps to a grouped auth connection ID. Must match the JWT auth connection ID configured in the dashboard. `String`. | +| `logoHover?` | Logo shown on mouse hover. `String`. | +| `logoLight?` | Light logo for dark backgrounds. `String`. | +| `logoDark?` | Dark logo for light backgrounds. `String`. | +| `mainOption?` | Show the sign-in button on the main list. Default is `false`. `Bool`. | +| `showOnModal?` | Show the sign-in button on the modal. Default is `true`. `Bool`. | +| `showOnDesktop?` | Show the sign-in button on desktop. Default is `true`. `Bool`. | +| `showOnMobile?` | Show the sign-in button on mobile. Default is `true`. `Bool`. | @@ -241,7 +220,7 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio ## Configure extra sign-in options In addition to the auth connection config during initialization, you can pass extra options to the -`connectTo` function to configure the login flow. `ExtraLoginOptions` accepts the following parameters. +`connectTo` function to configure the sign-in flow. `ExtraLoginOptions` accepts the following parameters. ### Parameters @@ -255,57 +234,30 @@ In addition to the auth connection config during initialization, you can pass ex -<<<<<<< HEAD -| Parameter | Description | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `additionalParams?` | Additional params in `[String: String]` format for OAuth login, use id_token (JWT) to authenticate with Web3Auth. | -| `domain?` | Your custom authentication domain as string. For example, if you are using Auth0, it can be `example.au.auth0.com`. | -| `client_id?` | Client ID as string, provided by your login provider used for custom auth connection. | -| `leeway?` | The value used to account for clock skew in JWT expirations. The value is in seconds, and ideally should be no more than 60 seconds or 120 seconds at max. It takes integer value. | -| `userIdField?` | The field in JWT token which maps to user ID. Please make sure you selected the correct JWT user ID in the developer dashboard. It accepts a string value. | -| `isUserIdCaseSensitive?` | Boolean to confirm whether the user ID field is case sensitive or not. | -| `display?` | Allows developers to configure the display of UI. It accepts a string value. | -| `prompt?` | Prompt shown to the user during authentication process. It accepts a string value. | -| `max_age?` | Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It accepts a string value. | -| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | -| `id_token_hint?` | It denotes the previously issued ID token. It accepts a string value. | -| `id_token?` | JWT (ID token) to be passed for login. | -| `access_token?` | Access token for OAuth flows. It accepts a string value. | -| `flow_type?` | Specifies the email passwordless flow type. Accepts `EmailFlowType` (`.code` or `.link`). | -| `acr_values?` | acr_values | -| `scope?` | The default scope to be used on authentication requests. It accepts a string value. | -| `audience?` | The audience, presented as the aud claim in the access token. It accepts a string value. | -| `connection?` | The name of the connection configured for your application. If nil, it will redirect to the Auth0 login page. It accepts a string value. | -| `state?` | state | -| `response_type?` | Defines which grant to execute for the authorization server. It accepts a string value. | -| `nonce?` | nonce | -| `redirect_uri?` | It can be used to specify the default URL where your custom JWT verifier can redirect your browser to with the result. If you are using Auth0, it must be allowlisted in the Allowed Callback URLs in your Auth0's application. | -======= -| Parameter | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `additionalParams?` | Additional parameters in `[String: String]` format for OAuth sign-in. Use `id_token` (JWT) to authenticate with the SDK. `[String: String]`. | -| `domain?` | Custom authentication domain (for example, `example.au.auth0.com` for Auth0). `String`. | -| `client_id?` | Client ID from your sign-in provider for custom auth connections. `String`. | -| `leeway?` | Clock-skew tolerance for JWT expiration, in seconds. Recommended maximum is 120 seconds. `Int`. | -| `userIdField?` | JWT token field that maps to the user ID. Must match the JWT user ID configured in the dashboard. `String`. | -| `isUserIdCaseSensitive?` | Whether the user ID field is case-sensitive. `Bool`. | -| `display?` | OIDC `display` parameter controlling how the authentication UI renders (for example, `page`, `popup`, `touch`). `String`. | -| `prompt?` | OIDC `prompt` parameter shown during authentication (for example, `login`, `consent`, `none`). `String`. | -| `max_age?` | Maximum time (in seconds) since the last authentication before the user must re-authenticate. `String`. | -| `ui_locales?` | Space-separated list of language tags, ordered by preference (for example, `fr-CA fr en`). `String`. | -| `id_token_hint?` | Previously issued ID token, used as a hint for re-authentication. `String`. | -| `id_token?` | JWT (ID token) to pass for sign-in. `String`. | -| `access_token?` | Access token for OAuth flows. `String`. | -| `flow_type?` | Email passwordless flow type. `EmailFlowType` (`.code` or `.link`). | -| `acr_values?` | Authentication context class reference values requested from the provider. `String`. | -| `scope?` | Default scope for authentication requests. `String`. | -| `audience?` | Audience for the access token, presented as the `aud` claim. `String`. | -| `connection?` | Name of the connection configured for your dapp. If `nil`, redirects to the Auth0 sign-in page. `String`. | -| `state?` | Opaque value used to maintain state between the request and callback, preventing CSRF attacks. `String`. | -| `response_type?` | Grant type to execute for the authorization server. `String`. | -| `nonce?` | Random value used to prevent replay attacks in OIDC flows. `String`. | -| `redirect_uri?` | URL where your custom JWT verifier redirects the browser with the result. For Auth0, must be allowlisted in **Allowed Callback URLs** in your Auth0 application. | ->>>>>>> 6f369b09 (Initial custom-authentication edits.) +| Parameter | Description | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `additionalParams?` | Additional parameters in `[String: String]` format for OAuth sign-in. Use `id_token` (JWT) to authenticate with the SDK. `[String: String]`. | +| `domain?` | Custom authentication domain (for example, `example.au.auth0.com` for Auth0). `String`. | +| `client_id?` | Client ID from your sign-in provider for custom auth connections. `String`. | +| `leeway?` | Clock-skew tolerance for JWT expiration, in seconds. Recommended maximum is 120 seconds. `Int`. | +| `userIdField?` | JWT token field that maps to the user ID. Must match the JWT user ID configured in the dashboard. `String`. | +| `isUserIdCaseSensitive?` | Whether the user ID field is case-sensitive. `Bool`. | +| `display?` | OIDC `display` parameter controlling how the authentication UI renders (for example, `page`, `popup`, `touch`). `String`. | +| `prompt?` | OIDC `prompt` parameter shown during authentication (for example, `login`, `consent`, `none`). `String`. | +| `max_age?` | Maximum time (in seconds) since the last authentication before the user must re-authenticate. `String`. | +| `ui_locales?` | Space-separated list of language tags, ordered by preference (for example, `fr-CA fr en`). `String`. | +| `id_token_hint?` | Previously issued ID token, used as a hint for re-authentication. `String`. | +| `id_token?` | JWT (ID token) to pass for sign-in. `String`. | +| `access_token?` | Access token for OAuth flows. `String`. | +| `flow_type?` | Email passwordless flow type. `EmailFlowType` (`.code` or `.link`). | +| `acr_values?` | Authentication context class reference values requested from the provider. `String`. | +| `scope?` | Default scope for authentication requests. `String`. | +| `audience?` | Audience for the access token, presented as the `aud` claim. `String`. | +| `connection?` | Name of the connection configured for your dapp. If `nil`, redirects to the Auth0 sign-in page. `String`. | +| `state?` | Opaque value used to maintain state between the request and callback, preventing CSRF attacks. `String`. | +| `response_type?` | Grant type to execute for the authorization server. `String`. | +| `nonce?` | Random value used to prevent replay attacks in OIDC flows. `String`. | +| `redirect_uri?` | URL where your custom JWT verifier redirects the browser with the result. For Auth0, must be allowlisted in **Allowed Callback URLs** in your Auth0 application. | @@ -358,7 +310,7 @@ public enum EmailFlowType: String, Codable { -Auth0 has a special login flow called the SPA flow. This flow requires a `client_id` and `domain`, and +Auth0 has a special sign-in flow called the SPA flow. This flow requires a `client_id` and `domain`, and the SDK retrieves the JWT `id_token` from Auth0 directly. Pass these values in the `ExtraLoginOptions` object in the `connectTo` call. @@ -399,9 +351,9 @@ let result = try await web3Auth.connectTo( -If you're using another provider like Firebase, AWS Cognito, or your own custom JWT server, pass the +If you're using another provider like Firebase, `AWS Cognito`, or your own custom JWT server, pass the JWT token in the `idToken` parameter of `LoginParams`. In Single Factor Auth (SFA) mode, this -enables direct authentication without additional login flows. +enables direct authentication without additional sign-in flows. ```swift import Web3Auth @@ -438,7 +390,7 @@ let result = try await web3Auth.connectTo( -For Email Passwordless login, pass the email address as the `loginHint` parameter of `LoginParams`. +For Email Passwordless sign-in, pass the email address as the `loginHint` parameter of `LoginParams`. The default flow is `code` (OTP). To use a magic link flow instead, set `flow_type` to `.link` in `extraLoginOptions`. @@ -470,7 +422,7 @@ let result = try await web3Auth.connectTo( -For SMS Passwordless login, pass the phone number as the `loginHint` parameter of `LoginParams`. +For SMS Passwordless sign-in, pass the phone number as the `loginHint` parameter of `LoginParams`. The phone number must use the format `+{country_code}-{phone_number}`, for example `+91-9911223344`. ```swift @@ -499,7 +451,7 @@ let result = try await web3Auth.connectTo( ### Grouped auth connection example -Grouped auth connections combine multiple login methods so your users get the same address regardless +Grouped auth connections combine multiple sign-in methods so your users get the same address regardless of how they sign in. For example, combine Google and Email Passwordless, or Google and GitHub via Auth0, to resolve to the same address. diff --git a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx index ba8cc45c3bb..c0a8610df44 100644 --- a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx +++ b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx @@ -13,7 +13,7 @@ places and can be used to reconstruct the private key dynamically in the user's application. Typically, there are 3 shares: -1. **`ShareA` is managed by a login service via node operators:** This share is further split +1. **`ShareA` is managed by a sign-in service via node operators:** This share is further split amongst a network of nodes and retrieved via conventional authentication flows. 2. **`ShareB` is stored on the user's device:** Implementation is device and system specific. For example, on mobile devices, the share could be stored in device storage secured via @@ -37,13 +37,12 @@ For a seamless sign-in flow, Shares `A` and `B` must be reconstructed. `Share B` is managed by the sign-in service and is provided on successful authentication. On web platforms, `Share A` is stored in the browser context. You can still store it in the browser context on mobile devices, but this carries risks; users -may accidentally delete browser data. +may delete browser data by mistake. This is a bigger problem on mobile because users don't realize the browser is used to sign in within the app, and clearing browser data can cause sign-in to fail. To address this, Embedded Wallets issues a dapp share, a backup share that you can store directly in your app and use to reconstruct the private key after a successful sign-in. - ## Dapp share in iOS After a successful sign-in, the SDK returns user details to your app. @@ -72,13 +71,12 @@ After a successful sign-in, the SDK returns user details to your app. The response includes a `dappShare` field, a 24-word seed phrase that can reconstruct the private key. `dappShare` supplements `Share A` and represents half of the private key. -You can store the dapp share safely in your app's local storage. +You can store the dapp share in your app's local storage. During sign-in, the user's social account provides one share, and your app provides the dapp share, removing the need to store a share in the browser context. Pass the stored dapp share value in the `connectTo` call. - :::note `dappShare` is only available for custom auth connections, not standard Embedded Wallets auth diff --git a/embedded-wallets/sdk/ios/advanced/mfa.mdx b/embedded-wallets/sdk/ios/advanced/mfa.mdx index 58ec46d6e48..666a25605ad 100644 --- a/embedded-wallets/sdk/ios/advanced/mfa.mdx +++ b/embedded-wallets/sdk/ios/advanced/mfa.mdx @@ -18,14 +18,13 @@ for offchain multi-sig, making the key self-custodial. With backup factors, you can recover your account if you lose access to your original device or need to sign in on a new device. - ## Enable using the MFA level Customize the MFA screen by passing the `mfaLevel` parameter in the `connectTo` method. You can enable or disable a backup factor and change their order. -There are four MFA level values. +Four MFA level values are available. :::caution Note @@ -38,12 +37,12 @@ MFA can't be turned off once enabled. ### MFA level options -| MFA Level | Description | -| --------- | ---------------------------------------------------------- | +| MFA Level | Description | +| --------- | ------------------------------------------------------------ | | DEFAULT | Shows the MFA screen every third sign-in. | | OPTIONAL | Shows the MFA screen on every sign-in, but user can skip it. | | MANDATORY | Makes it mandatory to set up MFA after first sign-in. | -| NONE | Skips the MFA setup screen. | +| NONE | Skips the MFA setup screen. | ### Usage @@ -150,14 +149,14 @@ Configure the order of MFA or enable/disable MFA types by passing the `mfaSettin -| Parameter | Description | -| ---------------------- | ------------------------------------------------------------------------ | -| `deviceShareFactor?` | MFA setting for deviceShareFactor. It accepts `MfaSetting` as a value. | -| `backUpShareFactor?` | MFA setting for backUpShareFactor. It accepts `MfaSetting` as a value. | -| `socialBackupFactor?` | MFA setting for socialBackupFactor. It accepts `MfaSetting` as a value. | -| `passwordFactor?` | MFA setting for passwordFactor. It accepts `MfaSetting` as a value. | -| `passkeysFactor?` | MFA setting for passkeysFactor. It accepts `MfaSetting` as a value. | -| `authenticatorFactor?` | MFA setting for authenticatorFactor. It accepts `MfaSetting` as a value. | +| Parameter | Description | +| ---------------------- | -------------------------------------------------------------------------- | +| `deviceShareFactor?` | MFA setting for deviceShareFactor. It accepts `MfaSetting` as a value. | +| `backUpShareFactor?` | MFA setting for backUpShareFactor. It accepts `MfaSetting` as a value. | +| `socialBackupFactor?` | MFA setting for socialBackupFactor. It accepts `MfaSetting` as a value. | +| `passwordFactor?` | MFA setting for `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. | diff --git a/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx b/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx index 4098a422f41..98a529addef 100644 --- a/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx +++ b/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx @@ -14,7 +14,7 @@ Customize how transaction confirmations display and tailor the wallet UI brandin :::note Wallet Services requires a paid plan. -You can use this feature in `sapphire_devnet` for free. +You can use this feature in `sapphire_devnet` at no cost. The minimum [pricing plan](https://web3auth.io/pricing.html) to use this feature in a production environment is the **Scale Plan**. @@ -22,7 +22,7 @@ production environment is the **Scale Plan**. ## `WalletServicesConfig` -Pass `walletServicesConfig` in `Web3AuthOptions` to configure how wallet services behave across +Pass `walletServicesConfig` in `Web3AuthOptions` to configure how Wallet Services behave across your dapp. ### Parameters @@ -30,7 +30,7 @@ your dapp. | Parameter | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirmationStrategy?` | Controls how transaction confirmations are displayed. Accepts `ConfirmationStrategy`. Default is `.defaultStrategy`. | -| `whiteLabel?` | Whitelabel configuration for the wallet services UI. When provided, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as a value. | +| `whiteLabel?` | Whitelabel configuration for the Wallet Services UI. When provided, merged with the project-level whitelabel config. Accepts `WhiteLabelData` as a value. | ### `ConfirmationStrategy` diff --git a/embedded-wallets/sdk/ios/advanced/whitelabel.mdx b/embedded-wallets/sdk/ios/advanced/whitelabel.mdx index 5e76031e2ad..3be03a076f7 100644 --- a/embedded-wallets/sdk/ios/advanced/whitelabel.mdx +++ b/embedded-wallets/sdk/ios/advanced/whitelabel.mdx @@ -41,16 +41,16 @@ The following parameters customize the sign-in screens: -| Parameter | Description | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `appName?` | Display name for the app in the UI. | -| `logoLight?` | App logo to be used in dark mode. It accepts URL as a string. | -| `logoDark?` | App logo to be used in light mode. It accepts URL as a string. | -| `defaultLanguage?` | Language used by Embedded Wallets. Falls back to browser language if not specified. Default is `Language.en`. See `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 a dictionary of `[String: String]` as a value. | -| `appUrl?` | URL to be used in the modal. It accepts URL as a string. | -| `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are nil, the default Embedded Wallets logo is used for the loader. Default is false. | +| Parameter | Description | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `appName?` | Display name for the app in the UI. | +| `logoLight?` | App logo to be used in dark mode. It accepts URL as a string. | +| `logoDark?` | App logo to be used in light mode. It accepts URL as a string. | +| `defaultLanguage?` | Language used by Embedded Wallets. Falls back to browser language if not specified. Default is `Language.en`. See `Language` for supported languages. | +| `mode?` | Theme mode for the sign-in modal. Choose between `ThemeModes.auto`, `ThemeModes.light` or `ThemeModes.dark` background modes. Default value is `ThemeModes.auto`. | +| `theme?` | Used to customize the theme of the sign-in modal. It accepts a dictionary of `[String: String]` as a value. | +| `appUrl?` | URL to be used in the modal. It accepts URL as a string. | +| `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are nil, the default Embedded Wallets logo is used for the loader. Default is false. | diff --git a/embedded-wallets/sdk/ios/usage/README.mdx b/embedded-wallets/sdk/ios/usage/README.mdx index 4f04d531556..0463f04c017 100644 --- a/embedded-wallets/sdk/ios/usage/README.mdx +++ b/embedded-wallets/sdk/ios/usage/README.mdx @@ -40,7 +40,7 @@ and Wallet Services. ### Wallet Services methods -| Method | Description | -| -------------------------------------- | ----------------------------------------------------------------- | -| [`showWalletUI()`](./showWalletUI.mdx) | Launches the templated wallet UI in WebView. | -| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions. | +| Method | Description | +| -------------------------------------- | ---------------------------------------------------------------- | +| [`showWalletUI()`](./showWalletUI.mdx) | Launches the built-in wallet UI in WebView. | +| [`request()`](./request.mdx) | Opens built-in transaction screens for signing EVM transactions. | diff --git a/embedded-wallets/sdk/ios/usage/connectTo.mdx b/embedded-wallets/sdk/ios/usage/connectTo.mdx index 0a69d3bbd19..c72ed1c9013 100644 --- a/embedded-wallets/sdk/ios/usage/connectTo.mdx +++ b/embedded-wallets/sdk/ios/usage/connectTo.mdx @@ -29,18 +29,18 @@ The `connectTo` method accepts `LoginParams` as a required parameter. -| Parameter | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `authConnection` | It sets the OAuth login method to be used. You can use any of the supported values: `.GOOGLE`, `.FACEBOOK`, `.REDDIT`, `.DISCORD`, `.TWITCH`, `.APPLE`, `.LINE`, `.GITHUB`, `.KAKAO`, `.LINKEDIN`, `.TWITTER`, `.WEIBO`, `.WECHAT`, `.EMAIL_PASSWORDLESS`, `.SMS_PASSWORDLESS`, and `.FARCASTER`. | -| `authConnectionId?` | The auth connection ID for the connection. Required for SFA mode when `idToken` is passed. Default value is `nil`. | -| `groupedAuthConnectionId?` | The grouped auth connection ID for grouped auth connections. It accepts `String` as a value. | -| `extraLoginOptions?` | It can be used to set the OAuth login options for the corresponding `authConnection`. Default value is `nil`, 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 `nil`, and it accepts a string value. | -| `mfaLevel?` | Customize the MFA screen shown to the user during authentication. Default value is `.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | -| `dappShare?` | Custom auth connection 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 a string value. | -| `curve?` | It will be used to determine the public key encoded in the JWT token which is returned in `getUserInfo` after user login. Private key returned by `getPrivateKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivateKey`. The default value is `.SECP256K1`. | -| `loginHint?` | Used to specify the user's email address or phone number for email/SMS passwordless login flows. For SMS, the format should be: `+{country_code}-{phone_number}` (for example `+1-1234567890`). It accepts a string value. | -| `idToken?` | JWT token for SFA (Single Factor Auth) mode. When provided, enables direct authentication without the social login browser flow. It accepts a string value. | +| Parameter | Description | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `authConnection` | It sets the OAuth sign-in method to be used. You can use any of the supported values: `.GOOGLE`, `.FACEBOOK`, `.REDDIT`, `.DISCORD`, `.TWITCH`, `.APPLE`, `.LINE`, `.GITHUB`, `.KAKAO`, `.LINKEDIN`, `.TWITTER`, `.WEIBO`, `.WECHAT`, `.EMAIL_PASSWORDLESS`, `.SMS_PASSWORDLESS`, and `.FARCASTER`. | +| `authConnectionId?` | The auth connection ID for the connection. Required for SFA mode when `idToken` is passed. Default value is `nil`. | +| `groupedAuthConnectionId?` | The grouped auth connection ID for grouped auth connections. It accepts `String` as a value. | +| `extraLoginOptions?` | It can be used to set the OAuth sign-in options for the corresponding `authConnection`. Default value is `nil`, and it accepts `ExtraLoginOptions` as a value. | +| `appState?` | It can be used to keep track of the app state when user will be redirected to app after sign-in. Default is `nil`, and it accepts a string value. | +| `mfaLevel?` | Customize the MFA screen shown to the user during authentication. Default value is `.DEFAULT`, which shows MFA screen every 3rd sign-in. It accepts `MFALevel` as a value. | +| `dappShare?` | Custom auth connection sign-ins can get a dapp share returned to them post successful sign-in. This is useful if the dapps want to use this share to allow users to sign in seamlessly. It accepts a string value. | +| `curve?` | It will be used to determine the public key encoded in the JWT token which is returned in `getUserInfo` after user sign-in. Private key returned by `getPrivateKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivateKey`. The default value is `.SECP256K1`. | +| `loginHint?` | Used to specify the user's email address or phone number for email/SMS passwordless sign-in flows. For SMS, the format should be: `+{country_code}-{phone_number}` (for example `+1-1234567890`). It accepts a string value. | +| `idToken?` | JWT token for SFA (Single Factor Auth) mode. When provided, enables direct authentication without the social sign-in browser flow. It accepts a string value. | @@ -107,20 +107,20 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio ## Examples - + ```swift import Web3Auth @@ -139,7 +139,7 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio - + ```swift import Web3Auth @@ -158,7 +158,7 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio - + ```swift import Web3Auth @@ -177,7 +177,7 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio - + ```swift import Web3Auth @@ -196,7 +196,7 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio - + ```swift import Web3Auth @@ -224,7 +224,7 @@ let result = try await web3Auth.connectTo( - + ```swift import Web3Auth @@ -250,7 +250,7 @@ let result = try await web3Auth.connectTo( - + ```swift import Web3Auth @@ -269,7 +269,7 @@ let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnectio - + For SFA (Single Factor Auth) mode, pass the JWT token via `idToken` to authenticate directly without any browser-based sign-in flow. diff --git a/embedded-wallets/sdk/ios/usage/logout.mdx b/embedded-wallets/sdk/ios/usage/logout.mdx index 77b728b381d..88ae817dbae 100644 --- a/embedded-wallets/sdk/ios/usage/logout.mdx +++ b/embedded-wallets/sdk/ios/usage/logout.mdx @@ -4,7 +4,7 @@ sidebar_label: Sign out description: 'Web3Auth iOS SDK - logout | Embedded Wallets' --- -To logout the user and remove the session ID from the device you can use the `logout` method. The user will need to login again to use the dapp next time the dapp is opened. +To sign out the user and remove the session ID from the device, use the `logout` method. The user must sign in again to use the dapp the next time the dapp is opened. ## Usage diff --git a/embedded-wallets/sdk/ios/usage/request.mdx b/embedded-wallets/sdk/ios/usage/request.mdx index 412016a7e37..36e24911a1e 100644 --- a/embedded-wallets/sdk/ios/usage/request.mdx +++ b/embedded-wallets/sdk/ios/usage/request.mdx @@ -4,7 +4,7 @@ sidebar_label: Send requests description: 'Web3Auth iOS SDK - request | Embedded Wallets' --- -The `request` method opens templated transaction screens for signing transactions. +The `request` method opens built-in transaction screens for signing transactions. The method returns a `SignResponse?`. Use it to sign transactions on any EVM chain. You can white-label the screens to match your branding. @@ -15,7 +15,6 @@ The `request` method currently supports only signing methods. The SDK retrieves chain configuration automatically from your project settings in the Embedded Wallets dashboard. - Date: Thu, 2 Jul 2026 20:33:33 +0400 Subject: [PATCH 23/24] Update .linkspector.yml --- .linkspector.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.linkspector.yml b/.linkspector.yml index 7695faa73a4..ec23cff338f 100644 --- a/.linkspector.yml +++ b/.linkspector.yml @@ -20,6 +20,7 @@ ignorePatterns: - pattern: '^http(s)?://help.figma.com' - pattern: '^http(s)?://metamask.io' - pattern: '^http(s)?://rivet.cloud' + - pattern: '^http(s)?://tenderly\.co' - pattern: '^http(s)?://app\.infura\.io($|/.*)' - pattern: '^http(s)?://docs.arbitrum.io($|/.*)' - pattern: '^/img/' From 292f2373d6ce025437432b01fe4a6496c36fb7fa Mon Sep 17 00:00:00 2001 From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com> Date: Thu, 2 Jul 2026 20:46:45 +0400 Subject: [PATCH 24/24] fixes --- .linkspector.yml | 1 + embedded-wallets/sdk/ios/advanced/README.mdx | 6 +-- .../ios/advanced/custom-authentication.mdx | 50 ++++++++++--------- ...smart-accounts.mdx => wallet-services.mdx} | 6 +-- ew-sidebar.js | 2 +- 5 files changed, 35 insertions(+), 30 deletions(-) rename embedded-wallets/sdk/ios/advanced/{smart-accounts.mdx => wallet-services.mdx} (96%) diff --git a/.linkspector.yml b/.linkspector.yml index ec23cff338f..513f07edf35 100644 --- a/.linkspector.yml +++ b/.linkspector.yml @@ -21,6 +21,7 @@ ignorePatterns: - pattern: '^http(s)?://metamask.io' - pattern: '^http(s)?://rivet.cloud' - pattern: '^http(s)?://tenderly\.co' + - pattern: '^http(s)?://docs\.tenderly\.co($|/.*)' - pattern: '^http(s)?://app\.infura\.io($|/.*)' - pattern: '^http(s)?://docs.arbitrum.io($|/.*)' - pattern: '^/img/' diff --git a/embedded-wallets/sdk/ios/advanced/README.mdx b/embedded-wallets/sdk/ios/advanced/README.mdx index 495e357ae01..80e278526f5 100644 --- a/embedded-wallets/sdk/ios/advanced/README.mdx +++ b/embedded-wallets/sdk/ios/advanced/README.mdx @@ -20,7 +20,7 @@ import Web3Auth // focus-start web3Auth = try await Web3Auth( options: Web3AuthOptions( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from MetaMask Developer Dashboard + clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets dashboard web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET redirectUrl: "com.yourapp.bundleid://auth" ) @@ -104,7 +104,7 @@ Control how long users stay authenticated and how sessions persist. The session ```swift web3Auth = try await Web3Auth( options: Web3AuthOptions( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from MetaMask Developer Dashboard + 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) @@ -174,7 +174,7 @@ web3Auth = try await Web3Auth( The `walletServicesConfig` parameter in `Web3AuthOptions` customizes the behavior of the wallet UI (`showWalletUI`) and request signing (`request`). -For full configuration options, see the [Smart Accounts](./smart-accounts.mdx) section. +For full configuration options, see the [Wallet Services](./wallet-services.mdx) section. | Parameter | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx index 4cbb2f83b80..161d482f325 100644 --- a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx @@ -57,21 +57,23 @@ After creating the auth connection from the [Embedded Wallets developer dashboar -| Parameter | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `authConnectionId` | Name of the auth connection registered in the Embedded Wallets dashboard. Required. `String`. | -| `authConnection` | Sign-in type for this connection. `.GOOGLE` triggers a Google sign-in flow; `.CUSTOM` expects your own JWT token with no sign-in flow. Required. `AuthConnection`. | -| `clientId` | Client ID from your sign-in provider (for example, Google Client ID), or your Embedded Wallets client ID when using `.CUSTOM`. Required. `String`. | -| `name?` | Display name for the auth connection. If `nil`, the default name is used. `String`. | -| `description?` | Description for the sign-in button. If provided, the button renders at full width; otherwise it renders as an icon button. `String`. | -| `groupedAuthConnectionId?` | JWT token field that maps to a grouped auth connection ID. Must match the JWT auth connection ID configured in the dashboard. `String`. | -| `logoHover?` | Logo shown on mouse hover. `String`. | -| `logoLight?` | Light logo for dark backgrounds. `String`. | -| `logoDark?` | Dark logo for light backgrounds. `String`. | -| `mainOption?` | Show the sign-in button on the main list. Default is `false`. `Bool`. | -| `showOnModal?` | Show the sign-in button on the modal. Default is `true`. `Bool`. | -| `showOnDesktop?` | Show the sign-in button on desktop. Default is `true`. `Bool`. | -| `showOnMobile?` | Show the sign-in button on mobile. Default is `true`. `Bool`. | +| Parameter | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `authConnectionId` | Name of the auth connection registered in the Embedded Wallets dashboard. Required. `String`. | +| `authConnection` | Sign-in type for this connection. Social values such as `.GOOGLE` trigger the provider sign-in flow. `.CUSTOM` marks a JWT-based auth connection: Auth0 and similar providers retrieve the token via `ExtraLoginOptions`, while Firebase, AWS Cognito, or your own JWT server use `LoginParams.idToken`. Required. `AuthConnection`. | +| `clientId` | Client ID from your sign-in provider (for example, Google Client ID), or your Embedded Wallets client ID when using `.CUSTOM`. Required. `String`. | +| `name?` | Display name for the auth connection. If `nil`, the default name is used. `String`. | +| `description?` | Description for the sign-in button. If provided, the button renders at full width; otherwise it renders as an icon button. `String`. | +| `groupedAuthConnectionId?` | JWT token field that maps to a grouped auth connection ID. Must match the JWT auth connection ID configured in the dashboard. `String`. | +| `logoHover?` | Logo shown on mouse hover. `String`. | +| `logoLight?` | Light logo for dark backgrounds. `String`. | +| `logoDark?` | Dark logo for light backgrounds. `String`. | +| `mainOption?` | Show the sign-in button on the main list. Default is `false`. `Bool`. | +| `showOnModal?` | Show the sign-in button on the modal. Default is `true`. `Bool`. | +| `showOnDesktop?` | Show the sign-in button on desktop. Default is `true`. `Bool`. | +| `showOnMobile?` | Show the sign-in button on mobile. Default is `true`. `Bool`. | +| `jwtParameters?` | Default JWT sign-in options for this auth connection. Useful for Auth0 configuration. `ExtraLoginOptions`. | +| `isDefault?` | Whether this auth connection is the default connector. Used internally by the SDK. `Bool`. | @@ -144,7 +146,7 @@ let web3Auth = try await Web3Auth( // focus-start authConnectionConfig: [ AuthConnectionConfig( - authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets dashboard authConnection: .GOOGLE, clientId: "YOUR_GOOGLE_CLIENT_ID" ) @@ -172,7 +174,7 @@ let web3Auth = try await Web3Auth( // focus-start authConnectionConfig: [ AuthConnectionConfig( - authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets dashboard authConnection: .FACEBOOK, clientId: "YOUR_FACEBOOK_CLIENT_ID" ) @@ -200,7 +202,7 @@ let web3Auth = try await Web3Auth( // focus-start authConnectionConfig: [ AuthConnectionConfig( - authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets dashboard authConnection: .CUSTOM, clientId: "YOUR_WEB3AUTH_CLIENT_ID" ) @@ -248,6 +250,7 @@ In addition to the auth connection config during initialization, you can pass ex | `ui_locales?` | Space-separated list of language tags, ordered by preference (for example, `fr-CA fr en`). `String`. | | `id_token_hint?` | Previously issued ID token, used as a hint for re-authentication. `String`. | | `id_token?` | JWT (ID token) to pass for sign-in. `String`. | +| `login_hint?` | Hint for the sign-in provider (for example, an email address). For passwordless flows, prefer `LoginParams.loginHint`. `String`. | | `access_token?` | Access token for OAuth flows. `String`. | | `flow_type?` | Email passwordless flow type. `EmailFlowType` (`.code` or `.link`). | | `acr_values?` | Authentication context class reference values requested from the provider. `String`. | @@ -310,9 +313,10 @@ public enum EmailFlowType: String, Codable { -Auth0 has a special sign-in flow called the SPA flow. This flow requires a `client_id` and `domain`, and -the SDK retrieves the JWT `id_token` from Auth0 directly. Pass these values in the `ExtraLoginOptions` -object in the `connectTo` call. +Auth0 uses the `.CUSTOM` auth connection type with Auth0's SPA flow. Unlike Firebase or custom JWT +servers where you pass a pre-obtained token in `LoginParams.idToken`, the SDK retrieves the JWT +`id_token` from Auth0 directly. Pass your Auth0 `client_id` and `domain` in `ExtraLoginOptions` in +the `connectTo` call. ```swift import Web3Auth @@ -325,7 +329,7 @@ let web3Auth = try await Web3Auth( // focus-start authConnectionConfig: [ AuthConnectionConfig( - authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets dashboard authConnection: .CUSTOM, clientId: "YOUR_AUTH0_CLIENT_ID" ) @@ -366,7 +370,7 @@ let web3Auth = try await Web3Auth( // focus-start authConnectionConfig: [ AuthConnectionConfig( - authConnectionId: "your-auth-connection-id", // Get it from MetaMask Developer Dashboard + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets dashboard authConnection: .CUSTOM, clientId: "YOUR_WEB3AUTH_CLIENT_ID" ) diff --git a/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx b/embedded-wallets/sdk/ios/advanced/wallet-services.mdx similarity index 96% rename from embedded-wallets/sdk/ios/advanced/smart-accounts.mdx rename to embedded-wallets/sdk/ios/advanced/wallet-services.mdx index 98a529addef..1a1fd3ac64e 100644 --- a/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx +++ b/embedded-wallets/sdk/ios/advanced/wallet-services.mdx @@ -1,7 +1,7 @@ --- -title: Smart accounts and Wallet Services configuration -sidebar_label: Smart accounts -description: 'Web3Auth iOS SDK - Smart Accounts and Wallet Services Configuration | Embedded Wallets' +title: Wallet Services configuration +sidebar_label: Wallet Services +description: 'Web3Auth iOS SDK - Wallet Services Configuration | Embedded Wallets' --- import TabItem from '@theme/TabItem' diff --git a/ew-sidebar.js b/ew-sidebar.js index 125e32f0029..edff85d7daf 100644 --- a/ew-sidebar.js +++ b/ew-sidebar.js @@ -798,7 +798,7 @@ const sidebar = { 'sdk/ios/advanced/whitelabel', 'sdk/ios/advanced/mfa', 'sdk/ios/advanced/dapp-share', - 'sdk/ios/advanced/smart-accounts', + 'sdk/ios/advanced/wallet-services', ], }, {