diff --git a/embedded-wallets/sdk/ios/README.mdx b/embedded-wallets/sdk/ios/README.mdx index 3f3e6692824..d16c7c08d85 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 a seamless authentication experience 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://dashboard.web3auth.io/) - -:::tip - -See the [dashboard setup](../../dashboard/README.mdx) guide to learn more. - -::: +- A project configured on the + [Embedded Wallets dashboard](https://dashboard.web3auth.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 E**xact 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. +3. Xcode automatically resolves and downloads your dependencies in the background. ### Cocoapods @@ -53,62 +48,52 @@ 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. ### 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://dashboard.web3auth.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://dashboard.web3auth.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 -### Configure Redirection - -To use Web3Auth for iOS you need to allowlist your `bundleId` in your Web3Auth project. - -- Go to [Embedded Wallets developer dashboard](https://dashboard.web3auth.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. +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. -### 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 Web3Auth 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: "", // From the Embedded Wallets dashboard + web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET + redirectUrl: "://auth" + ) + ) + // focus-end + + // Check for an active session + if web3Auth?.web3AuthResponse != nil { + // User is already signed in + } } catch { print("Error initializing Web3Auth: \(error)") } @@ -116,31 +101,17 @@ override func viewDidLoad() { } ``` -### 3. Handle URL callbacks - -Configure your application to handle URL callbacks in your `SceneDelegate`: +:::note -```swift -import Web3Auth - -func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { - guard let url = URLContexts.first?.url else { return } - Web3Auth().setResultUrl(url: url) -} -``` - -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 -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. @@ -164,11 +135,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: "", + web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET + redirectUrl: "://auth" + ) +) ``` @@ -176,56 +149,67 @@ 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 web3auth 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: "", + web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET + redirectUrl: "://auth", + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "", // From the Embedded Wallets 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 authentication (SFA) support + +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 sign-in with custom JWT +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .CUSTOM, + authConnectionId: "", + idToken: "" + ) +) +``` + +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 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 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 +219,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 +237,14 @@ let balance = toEther(wei: balanceResponse) ### Solana integration -For Solana integration, you can get the Ed25519 private key: +Get the Ed25519 private key using the `getEd25519PrivateKey` method and use it with SolanaSwift or +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 +261,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 e39f14ebcbb..b73acd1801c 100644 --- a/embedded-wallets/sdk/ios/advanced/README.mdx +++ b/embedded-wallets/sdk/ios/advanced/README.mdx @@ -7,27 +7,30 @@ 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 // 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 Web3Auth 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 Web3Auth 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 constructor takes a `Web3AuthOptions` struct as input. -| Parameter | Description | -| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `clientId` | Your Web3Auth Client ID from the [Dashboard](https://dashboard.web3auth.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://dashboard.web3auth.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? } ``` @@ -86,35 +93,126 @@ public struct W3AInitParams { Control how long users stay authenticated and how sessions persist. The session key is stored in the device's encrypted Keychain. -**Key Configuration Options:** +**Key configuration options:** -- `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to log in again. +- `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 Web3Auth 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 Web3Auth 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` customizes 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 -Control the login options presented to your users. For detailed configuration options and implementation examples, see the [custom authentication](./custom-authentication.mdx) section. +Control the sign-in options presented to your users. +For detailed configuration options and implementation examples, see the +[custom authentication](./custom-authentication.mdx) section. ## UI customization -Create a seamless brand experience by customizing the Web3Auth Login Screens to match your application's design. For complete customization options, refer to the [Whitelabeling and UI Customization](./whitelabel.mdx) section. +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 additional security layers to protect user accounts with two-factor authentication. For detailed configuration options and implementation examples, see the [Multi-Factor Authentication](./mfa.mdx) section. +Add security layers to protect user accounts with two-factor authentication. +For detailed configuration options and implementation examples, see +[Multi-Factor Authentication](./mfa.mdx). -**Key Configuration Options:** +**Key configuration options:** - `mfaSettings` - Configure MFA settings for different authentication flows - `mfaLevel` - Control when users are prompted to set up MFA diff --git a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx index e98f1d29a52..31ded0d18ff 100644 --- a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx @@ -1,52 +1,52 @@ --- -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' 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://dashboard.web3auth.io) with your desired configuration. +[Create a connection](../../../dashboard/authentication.mdx) from the **Authentication** tab of +your project in the [Embedded Wallets dashboard](https://dashboard.web3auth.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 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. +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 -:::warning +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. -**"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 Login providers like Auth0, AWS Cognito, Firebase, or your own custom JWT login), 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 [Web3Auth Dashboard](https://dashboard.web3auth.io), you can use the following parameters in the `AuthConnectionConfig`. -| Parameter | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `verifier` | The name of the verifier that you have registered on the 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` | 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`. | ```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 +138,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 web3auth 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 Web3Auth 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 +166,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 web3auth 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 Web3Auth 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 +194,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 web3auth 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 Web3Auth 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 +220,8 @@ let web3Auth = try await Web3Auth( ## Configure extra login options -Additional to the login config during initialization, you can pass extra options to the `login` function to configure the login flow for cases requiring additional info for enabling login. 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 @@ -219,29 +235,30 @@ Additional to the login config during initialization, you can pass extra options -| 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 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. | @@ -249,24 +266,31 @@ Additional to the login config during initialization, you can pass extra options ```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 +298,7 @@ public struct ExtraLoginOptions: Codable { -### Single verifier example +### Single auth connection example -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 +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 Web3Auth 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 Web3Auth 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 +351,38 @@ 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 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 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 web3auth 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 Web3Auth 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 +390,32 @@ let result = await web3Auth.login( -To use the email passwordless login, you need to put the email into the `login_hint` parameter of -the `ExtraLoginOptions`. By default, the login flow will be `code` flow, if you want to use the -`link` flow, you need to put `flow_type` into the `additionalParams` parameter of the -`ExtraLoginOptions`. + +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 -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 +423,86 @@ let result = try await web3Auth.login( -To use the SMS Passwordless login, 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). +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 -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 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 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 f526e03d986..2b4bfa3d1c1 100644 --- a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx +++ b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx @@ -1,30 +1,51 @@ --- 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 -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. - -For the seamless 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. +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 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. - -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 @@ -34,31 +55,46 @@ 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. +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. -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 login seamlessly. This can be done by passing over the stored dapp share value in the login function. +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 -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. +`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. ::: ```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 +106,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 5b628bea7b8..9d65041bc28 100644 --- a/embedded-wallets/sdk/ios/advanced/mfa.mdx +++ b/embedded-wallets/sdk/ios/advanced/mfa.mdx @@ -1,24 +1,37 @@ --- -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' 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 `login` 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 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'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 +39,9 @@ If you are using default verifiers, your users may have set up MFA on other dapp | 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 @@ -36,30 +49,35 @@ 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 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`. @@ -67,7 +85,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 +99,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 } - ``` @@ -100,21 +118,26 @@ do { ## Configure Multi-Factor Authentication settings -You can configure the order of MFA or enable/disable MFA type by passing the `mfaSettings` object in `Web3AuthOptions`. +Configure the order of MFA or enable/disable MFA types by passing the `mfaSettings` object in +`Web3AuthOptions`. :::note Note -- At least two factors are mandatory when setting up the mfaSettings. -- If you set `mandatory: true` for all factors, the user must set up all four factors. -- If you set `mandatory: false` for all factors, the user can skip setting up MFA. But at least two factors are mandatory. -- If you set `mandatory: true` for some factors and `mandatory: false` for others, the user must set up the mandatory factors and can skip the optional factors. But, the user must set up at least two factors. -- The `priority` field is used to set the order of the factors. The factor with the lowest priority will be the first factor to be set up. The factor with the highest priority will be the last factor to be set up. +- At least two factors are mandatory when setting up `mfaSettings`. +- If you set `mandatory: true` for all factors, the user must set up all factors. +- If you set `mandatory: false` for all factors, the user can skip MFA setup, but at least + two factors are still mandatory. +- If you set `mandatory: true` for some factors and `mandatory: false` for others, the user + must set up the mandatory factors and can skip the optional ones, but must set up at least + two factors total. +- The `priority` field sets the order of the factors. The lowest priority value is set up + first; the highest is set up last. ::: -### Parameters - `MfaSettings` +### `MfaSettings` parameters -`MfaSettings` allows you to set the type of the MFA. +`MfaSettings` configures which MFA factor types are available. ```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? +} ``` -### 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. ```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 +231,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..8c081b9d85d --- /dev/null +++ b/embedded-wallets/sdk/ios/advanced/smart-accounts.mdx @@ -0,0 +1,182 @@ +--- +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`. +Customize how transaction confirmations display and tailor the wallet UI branding. + +:::note + +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 dapp. + +### 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..5e76031e2ad 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' @@ -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 `W3AWhiteLabelData``. `W3AWhiteLabelData``can be definied during initialization of the SDK in`W3AInitParams` object. +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: ```swift -public struct W3AWhiteLabelData: Codable { +public struct WhiteLabelData: Codable { let appName: String? let logoLight: String? let logoDark: String? @@ -76,19 +77,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..9fb17d5c9f6 --- /dev/null +++ b/embedded-wallets/sdk/ios/migration-guides/ios-v11-to-v12.mdx @@ -0,0 +1,290 @@ +--- +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/README.mdx b/embedded-wallets/sdk/ios/usage/README.mdx index 2bcfbdd65f7..13f7826a012 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 | -| -------------------------- | -------------------------------------------------- | -| [`login()`](./login.mdx) | Logs in the user with the selected login provider. | -| [`logout()`](./logout.mdx) | Logs out the user from the current session. | - -### User management functions - -| Function Name | Description | +| Method | Description | | ------------------------------------ | ----------------------------------------------- | | [`getUserInfo()`](./getUserInfo.mdx) | Retrieves the authenticated user's information. | -### Private key functions +### Private key methods -| Function Name | Description | -| ------------------------------------------------ | ------------------------------------------------------------------------------- | -| [`getPrivKey()`](./getPrivKey.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | -| [`getEd25519PrivKey()`](./getEd25519PrivKey.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()`](./enableMFA.mdx) | Enables Multi-Factor Authentication for the user. | -| [`manageMFA()`](./manageMFA.mdx) | Allows users to manage their MFA settings. | +| Method | Description | +| -------------------------------- | ---------------------------------- | +| [`enableMFA()`](./enableMFA.mdx) | Enables MFA for the user. | +| [`manageMFA()`](./manageMFA.mdx) | Manages MFA settings for the user. | -### Wallet Services functions +### Wallet Services methods -| Function Name | Description | -| ------------------------------------------------------ | ----------------------------------------------------------------- | -| [`launchWalletServices()`](./launchWalletServices.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 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..bd14dbbc2f0 --- /dev/null +++ b/embedded-wallets/sdk/ios/usage/connectTo.mdx @@ -0,0 +1,301 @@ +--- +title: Sign 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 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) sign-in 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 sign-in 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 the Embedded Wallets dashboard + idToken: "your_jwt_token" + ) +) +// focus-end +``` + + + diff --git a/embedded-wallets/sdk/ios/usage/enableMFA.mdx b/embedded-wallets/sdk/ios/usage/enableMFA.mdx index fccbe348871..fe4cad13d2c 100644 --- a/embedded-wallets/sdk/ios/usage/enableMFA.mdx +++ b/embedded-wallets/sdk/ios/usage/enableMFA.mdx @@ -7,15 +7,21 @@ 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 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 @@ -23,7 +29,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 +41,28 @@ do { +:::warning + +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. + +::: + ```swift do { - let loginParams = W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: .init(id_token: " diff --git a/embedded-wallets/sdk/ios/usage/getEd25519PrivKey.mdx b/embedded-wallets/sdk/ios/usage/getEd25519PrivKey.mdx deleted file mode 100644 index 67f89148690..00000000000 --- a/embedded-wallets/sdk/ios/usage/getEd25519PrivKey.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Get Ed25519 private key -sidebar_label: getEd25519PrivKey -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/getEd25519PrivateKey.mdx b/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx new file mode 100644 index 00000000000..30da0585feb --- /dev/null +++ b/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey.mdx @@ -0,0 +1,17 @@ +--- +title: Ed25519 Private Key +sidebar_label: getEd25519PrivateKey +description: 'Web3Auth iOS SDK - getEd25519PrivateKey | Embedded Wallets' +--- + +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. + +This method throws an error if no user session exists or if the key is unavailable. + +## Usage + +```swift +let ed25519PrivateKey = try web3Auth.getEd25519PrivateKey() +``` diff --git a/embedded-wallets/sdk/ios/usage/getPrivKey.mdx b/embedded-wallets/sdk/ios/usage/getPrivKey.mdx deleted file mode 100644 index db6a7f3fa53..00000000000 --- a/embedded-wallets/sdk/ios/usage/getPrivKey.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Get Secp256k1 private key -sidebar_label: getPrivKey -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/getPrivateKey.mdx b/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx new file mode 100644 index 00000000000..acdbfa6267a --- /dev/null +++ b/embedded-wallets/sdk/ios/usage/getPrivateKey.mdx @@ -0,0 +1,18 @@ +--- +title: Secp256k1 Private Key +sidebar_label: getPrivateKey +description: 'Web3Auth iOS SDK - getPrivateKey | Embedded Wallets' +--- + +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 you set `useSFAKey` to `true` in `Web3AuthOptions`, this method returns the single-factor +authentication (SFA) key instead of the standard private key. + +## Usage + +```swift +let privateKey = web3Auth.getPrivateKey() +``` diff --git a/embedded-wallets/sdk/ios/usage/getUserInfo.mdx b/embedded-wallets/sdk/ios/usage/getUserInfo.mdx index c2d9840e071..cf758bd1607 100644 --- a/embedded-wallets/sdk/ios/usage/getUserInfo.mdx +++ b/embedded-wallets/sdk/ios/usage/getUserInfo.mdx @@ -4,15 +4,18 @@ sidebar_label: getUserInfo 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. + +This method throws an error if no user session exists. ## Usage ```swift -let web3AuthUserInfo = web3Auth.getUserInfo(); +let web3AuthUserInfo = try web3Auth.getUserInfo() ``` -## `getUserInfo` response +## Example response ```json { @@ -20,14 +23,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/launchWalletServices.mdx b/embedded-wallets/sdk/ios/usage/launchWalletServices.mdx deleted file mode 100644 index 188f9a70987..00000000000 --- a/embedded-wallets/sdk/ios/usage/launchWalletServices.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Launch Wallet Services -sidebar_label: launchWalletServices -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 templated wallet UI services. The method takes `ChainConfig` as the required input. Wallet Services is currently only available for EVM chains. - -:::note - -Access to Wallet Services is gated. You can use this feature in `sapphire_devnet` for free. The minimum [pricing plan](https://web3auth.io/pricing.html) to use this feature in a production environment is the **Scale Plan**. - -::: - -![Wallet Services](/img/embedded-wallets/wallet-services/mobile-wallet-services.png) - -## Parameters - - - - - -| Parameter | Description | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `chainNamespace` | Custom configuration for your preferred blockchain. As of now only EVM supported. Default value is `ChainNamespace.eip155`. | -| `decimals?` | Number of decimals for the currency ticker. Default value is 18, and accepts `Int` as value. | -| `blockExplorerUrl?` | Blockchain's explorer URL. (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 94290dacb71..00000000000 --- a/embedded-wallets/sdk/ios/usage/login.mdx +++ /dev/null @@ -1,263 +0,0 @@ ---- -title: Login user -sidebar_label: login -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 login seamlessly. 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/manageMFA.mdx b/embedded-wallets/sdk/ios/usage/manageMFA.mdx index 8fa1f223dbf..c58fe664d8a 100644 --- a/embedded-wallets/sdk/ios/usage/manageMFA.mdx +++ b/embedded-wallets/sdk/ios/usage/manageMFA.mdx @@ -7,15 +7,21 @@ 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 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 @@ -39,20 +45,21 @@ do { ```swift -let loginParams = W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: .init(id_token: "your_jwt_token") +let loginParams = LoginParams( + authConnection: .CUSTOM, + authConnectionId: "", + idToken: "" ) 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 4c189cacf3f..8d7a1347c49 100644 --- a/embedded-wallets/sdk/ios/usage/request.mdx +++ b/embedded-wallets/sdk/ios/usage/request.mdx @@ -4,51 +4,56 @@ sidebar_label: request description: 'Web3Auth iOS SDK - request | Embedded Wallets' --- -The `request` method facilitates the use of templated 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 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. ![Request Method](/img/embedded-wallets/wallet-services/mobile-request-method.png) ## Parameters -| Parameter | Description | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chainConfig` | Defines the chain to be used for signature. | -| `method` | JSON RPC method name in `String`. Currently, the request method only supports the singing methods. | -| `requestParams` | Parameters for the corresponding method. The parameters should be in the list and correct sequence. Take a look at [RPC methods](https://docs.metamask.io/wallet/reference/json-rpc-api/) to know more. | +| 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. | ## Usage ```swift do { - var params = [Any]() - // Message to be signed - params.append("Hello, Web3Auth from iOS!") - // User's EOA address - params.append(address) - - // focus-start - let response = try await web3Auth?.request( - chainConfig: ChainConfig( - chainId: "0xaa36a7", - rpcTarget: "https://eth-sepolia.public.blastapi.io" - ), - method: "personal_sign", - requestParams: params - ) - // focus-end - - if response!.success { - print(response!.result!) - } else { - // Handle Error - print(response!.error!) - } + var params = [Any]() + // Message to be signed + params.append("Hello, Web3Auth from iOS!") + // User's EOA address + params.append(address) + + // focus-start + let response = try await web3Auth.request( + method: "personal_sign", + requestParams: params + ) + // focus-end + if let response = response { + if response.success { + print(response.result!) + } else { + // Handle Error + print(response.error!) + } + } } catch { - print(error.localizedDescription) - // Handle error + print(error.localizedDescription) + // Handle error } ``` @@ -56,6 +61,6 @@ do { | Name | Description | | --------- | ------------------------------------------------------------- | -| `success` | Determines whether the request was successful or not. | +| `success` | Whether the request succeeded. | | `result?` | Holds the signature for the request when `success` is `true`. | | `error?` | Holds the error for the request when `success` is `false`. | diff --git a/embedded-wallets/sdk/ios/usage/showWalletUI.mdx b/embedded-wallets/sdk/ios/usage/showWalletUI.mdx new file mode 100644 index 00000000000..e72e590fd39 --- /dev/null +++ b/embedded-wallets/sdk/ios/usage/showWalletUI.mdx @@ -0,0 +1,56 @@ +--- +title: Show Wallet UI +sidebar_label: showWalletUI +description: 'Web3Auth iOS SDK - showWalletUI | Embedded Wallets' +--- + +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. +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**. + +::: + +![Wallet Services](/img/embedded-wallets/wallet-services/mobile-wallet-services.png) + +## Parameters + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `path?` | Path to navigate to in the wallet UI. Defaults to `"wallet"`. You can use `"wallet/transactions"`, `"wallet/nfts"`, etc. for specific wallet screens. | + +## Usage + +```swift +do { + // focus-next-line + try await web3Auth.showWalletUI() +} catch { + print(error.localizedDescription) + // Handle error +} +``` + +## Navigate to a specific screen + +```swift +do { + // focus-next-line + try await web3Auth.showWalletUI(path: "wallet/transactions") +} catch { + print(error.localizedDescription) + // Handle error +} +``` diff --git a/ew-sidebar.js b/ew-sidebar.js index 063e7fa06f4..ce8999dfba0 100644 --- a/ew-sidebar.js +++ b/ew-sidebar.js @@ -808,6 +808,7 @@ const sidebar = { 'sdk/ios/advanced/whitelabel', 'sdk/ios/advanced/mfa', 'sdk/ios/advanced/dapp-share', + 'sdk/ios/advanced/smart-accounts', ], }, { @@ -815,14 +816,14 @@ const sidebar = { label: 'Usage', items: [ 'sdk/ios/usage/README', - 'sdk/ios/usage/login', + 'sdk/ios/usage/connectTo', 'sdk/ios/usage/getUserInfo', - 'sdk/ios/usage/getPrivKey', - 'sdk/ios/usage/getEd25519PrivKey', + 'sdk/ios/usage/getPrivateKey', + 'sdk/ios/usage/getEd25519PrivateKey', 'sdk/ios/usage/logout', 'sdk/ios/usage/enableMFA', 'sdk/ios/usage/manageMFA', - 'sdk/ios/usage/launchWalletServices', + 'sdk/ios/usage/showWalletUI', 'sdk/ios/usage/request', ], }, diff --git a/src/utils/w3a-sdk-map.js b/src/utils/w3a-sdk-map.js index aa7af5d74ce..bc658c89abf 100644 --- a/src/utils/w3a-sdk-map.js +++ b/src/utils/w3a-sdk-map.js @@ -15,7 +15,7 @@ export const unreal = 'Unreal Engine' export const pnpWebVersion = `10.0.x` export const pnpAndroidVersion = `9.1.2` -export const pnpIOSVersion = `11.1.0` +export const pnpIOSVersion = `12.0.1` export const pnpRNVersion = `8.1.x` export const pnpNodeVersion = `5.0.x` export const pnpFlutterVersion = `6.1.2` diff --git a/vercel.json b/vercel.json index e2e82beebd9..dc7c099c37d 100644 --- a/vercel.json +++ b/vercel.json @@ -669,6 +669,22 @@ { "source": "/sdk/:path*/", "destination": "/metamask-connect/" + }, + { + "source": "/embedded-wallets/sdk/ios/usage/login/", + "destination": "/embedded-wallets/sdk/ios/usage/connectTo/" + }, + { + "source": "/embedded-wallets/sdk/ios/usage/getPrivKey/", + "destination": "/embedded-wallets/sdk/ios/usage/getPrivateKey/" + }, + { + "source": "/embedded-wallets/sdk/ios/usage/getEd25519PrivKey/", + "destination": "/embedded-wallets/sdk/ios/usage/getEd25519PrivateKey/" + }, + { + "source": "/embedded-wallets/sdk/ios/usage/launchWalletServices/", + "destination": "/embedded-wallets/sdk/ios/usage/showWalletUI/" } ] }