diff --git a/.linkspector.yml b/.linkspector.yml index 7695faa73a4..513f07edf35 100644 --- a/.linkspector.yml +++ b/.linkspector.yml @@ -20,6 +20,8 @@ ignorePatterns: - pattern: '^http(s)?://help.figma.com' - pattern: '^http(s)?://metamask.io' - pattern: '^http(s)?://rivet.cloud' + - pattern: '^http(s)?://tenderly\.co' + - pattern: '^http(s)?://docs\.tenderly\.co($|/.*)' - pattern: '^http(s)?://app\.infura\.io($|/.*)' - pattern: '^http(s)?://docs.arbitrum.io($|/.*)' - pattern: '^/img/' diff --git a/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx b/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx index c45eb1f2835..a35fb30c279 100644 --- a/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx +++ b/embedded-wallets/connect-blockchain/_ios-connect-blockchain/_evm-get-account.mdx @@ -1,21 +1,21 @@ Use the `EthereumAccount` class to retrieve the user's Ethereum address. This account can also be used to sign transactions and messages. -The package doesn't provides any direct way to consume the the private key and create an account. -Hence, we'll create an extension for the `Web3AuthState` extending the +The package doesn't provide any direct way to consume the private key and create an account. +Hence, we'll create an extension for the `Web3AuthResponse` extending the `EthereumSingleKeyStorageProtocol` to retrieve the private key and create an account. ```swift import web3 import Web3Auth -extension Web3AuthState: EthereumSingleKeyStorageProtocol { +extension Web3AuthResponse: EthereumSingleKeyStorageProtocol { public func storePrivateKey(key: Data) throws { } public func loadPrivateKey() throws -> Data { - guard let data = self.privKey?.web3.hexData else { + guard let data = self.privateKey?.web3.hexData else { throw PlaygroundError.decodingError } @@ -24,15 +24,15 @@ extension Web3AuthState: EthereumSingleKeyStorageProtocol { } ``` -Once we have created the extension, we can use the Web3AuthState to create an `EthereumAccount`. -Please note, that this assumes that the user has already logged in and the state is available. +Once we have created the extension, we can use the `Web3AuthResponse` to create an `EthereumAccount`. +Please note, that this assumes that the user has already logged in and the response is available. ```swift import web3 // Use your existing Web3Auth instance -let web3authState = web3Auth.state! +let web3AuthResponse = web3Auth.web3AuthResponse! -let account = try EthereumAccount(keyStorage: web3authState) +let account = try EthereumAccount(keyStorage: web3AuthResponse) let address = account.address ``` diff --git a/embedded-wallets/connect-blockchain/solana/ios.mdx b/embedded-wallets/connect-blockchain/solana/ios.mdx index 7d8ea9ba271..8c7a1844a14 100644 --- a/embedded-wallets/connect-blockchain/solana/ios.mdx +++ b/embedded-wallets/connect-blockchain/solana/ios.mdx @@ -10,7 +10,7 @@ description: 'Integrate Embedded Wallets with the Solana Blockchain in iOS | Emb import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' -While using the Embedded Wallets iOS SDK (formerly Web3Auth), you can retrieve the Ed25519 private key upon successful authentication. This private key can be used to derive the user's public address and interact with the [Solana](https://solana.org/) chain. We've highlighted a few methods here to get you started quickly. +While using the Embedded Wallets iOS SDK (formerly Web3Auth), you can retrieve the Ed25519 private key upon successful authentication. This private key can be used to derive the user's public address and interact with the [Solana](https://solana.org/) chain. We've highlighted a few methods here to get you started. :::note @@ -72,14 +72,14 @@ The SDKs are now branded as MetaMask Embedded Wallet SDKs (formerly Web3Auth Plu To interact with the Solana blockchain in iOS, you can use any Solana compatible SDK. Here, we're using [SolanaSwift](https://github.com/p2p-org/solana-swift) to demonstrate how to interact with Solana chain using Web3Auth. - - + To install `SolanaSwift` through Swift Package Manager, follow the below steps: @@ -97,7 +97,7 @@ Once finished, Xcode will automatically begin resolving and downloading your dep - + To install using CocoaPods, simply add the following line to your Podfile @@ -116,7 +116,7 @@ pod install ## Initialize -To Initialize the `JSONRPCAPIClient` we require a RPC URL. The `JSONRPCAPIClient` instance will provide a gateway & protocol to interact with Solana cluster while sending requests and receving response. For this example, we are using the RPC URL for Devnet-beta. To interact with Testnet or Mainnet, change the RPC URL. +To Initialize the `JSONRPCAPIClient` we require a RPC URL. The `JSONRPCAPIClient` instance will provide a gateway & protocol to interact with Solana cluster while sending requests and receiving response. For this example, we are using the RPC URL for Devnet-beta. To interact with Testnet or Mainnet, change the RPC URL. ### Initializing the Solana SDK @@ -136,9 +136,9 @@ let solanaJSONRPCClient = JSONRPCAPIClient(endpoint: endpoint) ### Initializing the Web3Auth SDK -In the following code block, we'll initialize the Web3Auth SDK and check whether the user has any Web3Auth session persisted or not. If the user is already authenticated, you can route them directly to home view, otherwise you can route them to login view for authentication purpose. For checking, if user is already authenticated, we can check whether `Web3Auth.state` is `nil` or not. +In the following code block, we'll initialize the Web3Auth SDK and check whether the user has any Web3Auth session persisted or not. If the user is already authenticated, you can route them directly to home view, otherwise you can route them to the sign-in view for authentication purpose. For checking, if user is already authenticated, we can check whether `web3Auth.web3AuthResponse` is `nil` or not. -By default, the session is persisted for 1 day. You can modify it using `sessionTime` parameter during initialization. +By default, the session is persisted for 30 days. You can modify it using `sessionTime` parameter during initialization. :::note @@ -151,27 +151,27 @@ import Web3Auth // Initialize Web3Auth SDK // focus-start -let web3Auth = await Web3Auth( - W3AInitParams( +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( clientId: "BPi5PB_UiIZ-cPz1GtV5i1I2iOSOHuimiXBI0e-Oe_u6X3oVAbCiAZOTEBtTXw4tsluTITPqA8zMsfxIKMjiqNQ", - network: Network.sapphire_mainnet, - redirectUrl: "com.w3a.ios-solana-example" + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.w3a.ios-solana-example://auth" ) ) // focus-end -// Check whether state is nil or not for user authentication status. -let isUserAuthenticated = web3Auth.state != nil +// Check whether web3AuthResponse is nil or not for user authentication status. +let isUserAuthenticated = web3Auth.web3AuthResponse != nil // Customize your logic to perform operations or navigation ``` ## Get account -We can use `getEd25519PrivKey` method in Web3Auth to retrive the priavte key for the Solana ecosystem. In the following code block, we'll use the Ed25519 private key to retive user's public address by creating `KeyPair`. The `KeyPair` struct from `SolanaSwift` SDK once created can be used to sign the Solana transactions. +We can use `getEd25519PrivateKey` method in Web3Auth to retrieve the private key for the Solana ecosystem. In the following code block, we'll use the Ed25519 private key to retrieve user's public address by creating `KeyPair`. The `KeyPair` struct from `SolanaSwift` SDK once created can be used to sign the Solana transactions. ```swift -let ed25519PrivateKey = web3Auth.getEd25519PrivKey() +let ed25519PrivateKey = try web3Auth.getEd25519PrivateKey() let keyPair = try KeyPair(secretKey: Data(hex: ed25519PrivateKey)) // focus-next-line @@ -180,7 +180,7 @@ let userAccount = keyPair.publicKey.base58EncodedString ## Get User balance -Once we have retrived userAccount, we can use it to fetch user balance. We'll use `getBalance` method from `JSONRPCAPIClient` instance to interact with Solana cluster and fetch user balance. The response of `getBalance` is UInt64, we will need to divide it by 10^9, because Solana's token decimals is 9. To help us with the calculation, the SDK also provides a `convertToBalance` function. +Once we have retrieved `userAccount`, we can use it to fetch user balance. We'll use `getBalance` method from `JSONRPCAPIClient` instance to interact with Solana cluster and fetch user balance. The response of `getBalance` is UInt64, we will need to divide it by 10^9, because Solana's token decimals is 9. To help us with the calculation, the SDK also provides a `convertToBalance` function. ```swift // focus-start @@ -197,7 +197,7 @@ let userBalance = return balanceResponse.convertToBalance(decimals: 9) ## Sign a transaction -Let's now go through how can we sign the transaction. In the below codeblock, we'll create a new function `perpareTransaction` which can be used to retrive the Base58 signature as well as broadcast transaction to the cluster. We'll use `BlockchainClient.prepareSendingNativeSOL` to create the transaction to self transfer 0.01 Sol and sign it. You can also checkout `prepareSendingSPLTokens`, and `prepareTransaction` for other types of transaction. +Let's now go through how can we sign the transaction. In the below code block, we'll create a new function `perpareTransaction` which can be used to retrieve the Base58 signature as well as broadcast transaction to the cluster. We'll use `BlockchainClient.prepareSendingNativeSOL` to create the transaction to self transfer 0.01 Sol and sign it. You can also checkout `prepareSendingSPLTokens`, and `prepareTransaction` for other types of transaction. ```swift let blockchainClient = BlockchainClient(apiClient: solanaJSONRPCClient) @@ -213,7 +213,7 @@ let blockchainClient = BlockchainClient(apiClient: solanaJSONRPCClient) } ``` -Once we have created `perpareTransaction` function, we'll use it to prepare, sign the transaction, and retrive Base58 signature. You can use `findSignature` to retrive the signature for the respective signer. +Once we have created `perpareTransaction` function, we'll use it to prepare, sign the transaction, and retrieve Base58 signature. You can use `findSignature` to retrieve the signature for the respective signer. ```swift do { diff --git a/embedded-wallets/migration-guides/README.mdx b/embedded-wallets/migration-guides/README.mdx index e4723946b0a..58fd3406398 100644 --- a/embedded-wallets/migration-guides/README.mdx +++ b/embedded-wallets/migration-guides/README.mdx @@ -30,8 +30,8 @@ current SDK in one pass. | Platform | Upgrade to | Covers upgrades from | | ---------------------------------------------------------------------- | ---------- | -------------------- | | [Web (JavaScript, React, Vue)](/embedded-wallets/migration-guides/web) | v11 | v9 through v10 | -| [Android](/embedded-wallets/migration-guides/android) | v10 | v4 through v9 | -| [iOS](/embedded-wallets/migration-guides/ios) | v10 | v6 through v9 | +| [Android](/embedded-wallets/migration-guides/android) | v9 | v4 through v8 | +| [iOS](/embedded-wallets/migration-guides/ios) | v12 | v6 through v11 | | [React Native](/embedded-wallets/migration-guides/react-native) | v9 | v3 through v8 | | [Flutter](/embedded-wallets/migration-guides/flutter) | v6 | v3 through v5 | diff --git a/embedded-wallets/migration-guides/ios.mdx b/embedded-wallets/migration-guides/ios.mdx index 384648ff252..ac9398c9142 100644 --- a/embedded-wallets/migration-guides/ios.mdx +++ b/embedded-wallets/migration-guides/ios.mdx @@ -1,12 +1,16 @@ --- -title: iOS SDK v10 Migration Guide -sidebar_label: iOS SDK v10 -description: Upgrade the Embedded Wallets iOS SDK directly from older versions to v10. -keywords: [migration, v10, ios, web3auth, embedded wallets, swift] +title: iOS SDK v12 Migration Guide +sidebar_label: iOS SDK v12 +description: Upgrade the Embedded Wallets iOS SDK directly from older versions to v12. +keywords: [migration, v12, ios, web3auth, embedded wallets, swift] --- -This guide upgrades Embedded Wallets iOS SDK integrations from **v6 through v9** directly to -**v10**. +This guide upgrades Embedded Wallets iOS SDK integrations from **v6 through v11** directly to +**v12**. + +If you're already on v11, focus on the [v12 changes](#v12-changes). +For older versions, apply the sections below that match your current version, then complete the v12 +updates. ## AI-assisted migration @@ -19,21 +23,21 @@ Copy the prompt below into your AI coding assistant (Cursor, Claude Code, Codex, similar): ```txt -Migrate my MetaMask Embedded Wallets iOS (web3auth-swift-sdk) project to v10. +Migrate my MetaMask Embedded Wallets iOS (web3auth-swift-sdk) project to v12. Before changing code: 1. Use the web3auth skill and MCP tools (search_docs, get_doc, get_example, get_sdk_reference). -2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/ios-v10 +2. Read the migration guide: https://docs.metamask.io/embedded-wallets/migration-guides/ios/ 3. Detect my current SDK version from Package.swift or Podfile and list which breaking changes apply. -Then migrate my codebase directly to v10: -- Update the Web3Auth dependency to v10.0.1 (Swift Package Manager or CocoaPods). -- Use .sapphire_mainnet or .sapphire_devnet for the network. -- Add mandatory redirectUrl to W3AInitParams ({bundleId}://auth). -- Replace getSignResponse() with the SignResponse returned from request(). -- Remove loginParams from launchWalletServices and request; pass chainConfig instead. -- Move chainConfig from W3AInitParams to launchWalletServices (v8.1+). -- Update W3AWhiteLabelData fields (appName, mode) if whitelabeling is configured. +Then migrate my codebase directly to v12: +- Update the Web3Auth dependency to 12.0.1 (Swift Package Manager or CocoaPods). +- Replace W3AInitParams with Web3AuthOptions (web3AuthNetwork: .SAPPHIRE_MAINNET or .SAPPHIRE_DEVNET). +- Replace login/W3ALoginParams with connectTo/LoginParams(authConnection:). +- Replace loginConfig with authConnectionConfig ([AuthConnectionConfig]). +- Replace getPrivKey/getEd25519PrivKey with getPrivateKey/getEd25519PrivateKey(). +- Replace launchWalletServices(chainConfig:) with showWalletUI() and configure chains in Web3AuthOptions. +- Remove chainConfig from request(); configure chains at init instead. - Do not change my Client ID or Sapphire network unless I ask; that would change wallet addresses. After migrating, list every file you changed and any manual dashboard steps I still need to do. @@ -46,7 +50,7 @@ Review the plan before generating code; config mistakes can change wallet addres ::: -## Install v10 +## Install v12 ### Swift Package Manager @@ -56,14 +60,14 @@ In Xcode, go to **File > Add Package Dependencies** and add: https://github.com/Web3Auth/web3auth-swift-sdk ``` -Select **Exact Version** and enter **10.0.1**. +Select **Exact Version** and enter **12.0.1**. ### CocoaPods Add to your `Podfile`: ```sh -pod 'Web3Auth', '~> 10.0.1' +pod 'Web3Auth', '~> 12.0.1' ``` Then run `pod install`. @@ -74,7 +78,52 @@ Allowlist `{bundleId}://auth` on the ## Breaking changes Apply the sections below that match your current version. -If you're already on v9, focus on the [v10 changes](#v10-changes). +If you're already on v11, focus on the [v12 changes](#v12-changes). + +### v12 changes {#v12-changes} + +v12 introduces a cleaner API surface. Key renames: + +| v11 and earlier | v12 | +| --------------------------------------- | ------------------------------------------------------ | +| `W3AInitParams` | `Web3AuthOptions` | +| `network: .sapphire_mainnet` | `web3AuthNetwork: .SAPPHIRE_MAINNET` | +| `login(W3ALoginParams(loginProvider:))` | `connectTo(loginParams: LoginParams(authConnection:))` | +| `Web3AuthProvider` / `.JWT` | `AuthConnection` / `.CUSTOM` | +| `loginConfig` | `authConnectionConfig` | +| `web3Auth.state` | `web3Auth.web3AuthResponse` | +| `getPrivKey()` | `getPrivateKey()` | +| `getEd25519PrivKey()` | `getEd25519PrivateKey()` (throws) | +| `launchWalletServices(chainConfig:)` | `showWalletUI()` | +| `request(chainConfig:...)` | `request(method:requestParams:)` | + +```swift +// v12 initialization +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + chains: [ + Chains( + chainId: "0x89", + rpcTarget: "https://rpc.ankr.com/polygon", + displayName: "Polygon Mainnet" + ) + ] + ) +) + +// v12 login +let result = try await web3Auth.connectTo( + loginParams: LoginParams(authConnection: .GOOGLE) +) + +// v12 wallet services +try await web3Auth.showWalletUI() +``` + +Remove any `setResultUrl` / `onOpenURL` handlers; v12 uses `ASWebAuthenticationSession` internally. ### Network and init params (from v7) @@ -185,25 +234,26 @@ If you're upgrading from an older SDK, adopt the v10 signatures shown above. | API | Added in | Purpose | | ------------------------ | -------- | ---------------------------------------------------- | | `enableMFA()` | v8 | Initiate MFA setup for logged-in users | -| `launchWalletServices()` | v8 | Open the templated wallet UI | +| `launchWalletServices()` | v8 | Open the built-in wallet UI | | `request()` | v8 | Sign transactions with confirmation screens | -| SMS Passwordless login | v8.3 | `Web3AuthProvider.SMS_PASSWORDLESS` with `loginHint` | -| Farcaster login | v8.3 | `.Farcaster` login provider | +| SMS Passwordless sign-in | v8.3 | `Web3AuthProvider.SMS_PASSWORDLESS` with `loginHint` | +| Farcaster sign-in | v8.3 | `.Farcaster` sign-in provider | -See [Wallet Services](/embedded-wallets/sdk/ios/usage/launch-wallet-services) and +See [Wallet Services](/embedded-wallets/sdk/ios/usage/showWalletUI) and [MFA](/embedded-wallets/sdk/ios/advanced/mfa) for usage details. ## Summary table -| Area | Before v7 | v7-v9 | v10 | -| ---------------------- | ------------------------- | -------------------------- | --------------------------- | -| Network | `.mainnet`, `.cyan`, etc. | Sapphire supported | Sapphire recommended | -| `redirectUrl` | Optional | Mandatory (v8.4+) | Mandatory | -| Whitelabel `name` | `name` | `appName` | `appName` | -| `chainConfig` in init | N/A | Removed (v8.1) | Removed | -| `launchWalletServices` | N/A | Drops `loginParams` (v8.2) | `chainConfig` only | -| `request` | N/A | Drops `loginParams` (v8.3) | Returns `SignResponse` | -| Sign result | N/A | `getSignResponse()` | Return value of `request()` | +| Area | Before v7 | v7-v11 | v12 | +| ----------------- | ------------------------- | ------------------------ | --------------------------- | +| Network | `.mainnet`, `.cyan`, etc. | Sapphire supported | `.SAPPHIRE_MAINNET` | +| Init params | `W3AInitParams` | `W3AInitParams` | `Web3AuthOptions` | +| Sign-in | N/A | `login(W3ALoginParams)` | `connectTo(LoginParams)` | +| `redirectUrl` | Optional | Mandatory (v8.4+) | Mandatory | +| Whitelabel `name` | `name` | `appName` | `appName` | +| Wallet UI | N/A | `launchWalletServices` | `showWalletUI()` | +| `request` | N/A | `chainConfig` parameter | Chains in `Web3AuthOptions` | +| Sign result | N/A | `getSignResponse()` (v9) | Return value of `request()` | ## Next steps diff --git a/embedded-wallets/sdk/ios/README.mdx b/embedded-wallets/sdk/ios/README.mdx index f9897800f66..1e71f8eff72 100644 --- a/embedded-wallets/sdk/ios/README.mdx +++ b/embedded-wallets/sdk/ios/README.mdx @@ -9,24 +9,18 @@ import Tabs from '@theme/Tabs' ## Overview -MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play) provides authentication for iOS applications with social logins, external wallets, and more. Our iOS SDK, written in Swift, simplifies connecting users to their preferred wallets and manage authentication state natively. +The MetaMask Embedded Wallets SDK for iOS (formerly Web3Auth Plug and Play) supports social +sign-ins, external wallets, and native authentication state management. +The SDK is written in Swift. -## Requirements +## Prerequisites - iOS 14+ - Xcode 12+ - Swift 5.x -- Basic knowledge of Swift and iOS Development - -## Prerequisites - -- Set up your project on the [Embedded Wallets dashboard](https://developer.metamask.io/) - -:::tip - -See the [dashboard setup](../../dashboard/README.mdx) guide to learn more. - -::: +- A project configured on the + [Embedded Wallets dashboard](https://developer.metamask.io/). + See the [dashboard setup](../../dashboard/README.mdx) guide for details. ## Installation @@ -42,9 +36,10 @@ Install the Web3Auth iOS SDK using one of the following methods: https://github.com/Web3Auth/web3auth-swift-sdk ``` - From the **Dependency Rule** dropdown, select **Exact Version** and enter **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://developer.metamask.io), and create or open an existing Embedded Wallets project. -- Allowlist `{bundleId}://auth` in the dashboard. This step is mandatory for the redirect to work. +- Go to the [Embedded Wallets developer dashboard](https://developer.metamask.io) and create or + open an existing project. +- Allowlist `{bundleId}://auth` in the dashboard. + This step is mandatory for the redirect to work. ## Initialize Embedded Wallets -### Configure Redirection - -To use Web3Auth for iOS you need to allowlist your `bundleId` in your Web3Auth project. - -- Go to [Embedded Wallets developer dashboard](https://developer.metamask.io), and create or open an existing Embedded Wallets project. -- Allowlist `{bundleId}://auth` in the developer dashboard. This step is mandatory for the redirect to work. +The iOS SDK uses an async initialization pattern. +The constructor fetches project configuration and restores any active session automatically. +The SDK does not require a separate `initialize()` call. -### 1. Create an Embedded Wallets instance +### Create and initialize an Embedded Wallets instance Import and configure Web3Auth in your application: ```swift import Web3Auth -class ViewController: UIViewController { +class ViewModel: ObservableObject { var web3Auth: Web3Auth? - override func viewDidLoad() { - super.viewDidLoad() - - // Configure Web3Auth - web3Auth = Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard - network: .sapphire_mainnet, // or .sapphire_devnet - redirectUrl: "com.yourapp.bundleid://auth" - )) - } -} -``` - -### 2. Initialize the Embedded Wallets instance - -Initialize the Web3Auth instance: - -```swift -override func viewDidLoad() { - super.viewDidLoad() - - Task { + func setup() async { do { - try await web3Auth?.initialize() - print("Web3Auth initialized successfully") + // focus-start + web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "", // 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 MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.google, - clientId: "YOUR_GOOGLE_CLIENT_ID", - ) - ], - mfaSettings: MfaSettings( - deviceShareFactor: MfaSetting( - enable: true, - priority: 1 - ), - backUpShareFactor: MfaSetting( - enable: true, - priority: 2 - ), - socialBackupFactor: MfaSetting( - enable: true, - priority: 3 - ), - passwordFactor: MfaSetting( - enable: true, - priority: 4 +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "", + 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 4e002af430e..80e278526f5 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 MetaMask Developer Dashboard - network: .sapphire_mainnet, // or .sapphire_devnet - redirectUrl: "com.yourapp.bundleid://auth" -)) +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets 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://developer.metamask.io/). It's a mandatory field of type `String`. | -| `network` | Web3Auth Network: `.sapphire_mainnet`, `.sapphire_devnet`, `.mainnet`, `.cyan`, `.aqua` or `.testnet`. Mandatory field of type `Network`. | -| `redirectUrl` | URL that Web3Auth will redirect API responses upon successful authentication. It's a mandatory field of type `String`. | -| `whiteLabel?` | Whitelabel options for custom UI, branding, and translations. Takes `W3AWhiteLabelData`` as a value. | -| `loginConfig?` | Login config for custom verifiers. Takes `[String: W3ALoginConfig]` as a value. | -| `mfaSettings?` | Configure MFA settings for authentication. Takes `MfaSettings` as a value. | -| `sessionTime?` | Configure session management time in seconds. Default is 86400 seconds (1 day). Max 30 days. | +**Basic parameters:** + +| Parameter | Description | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `clientId` | Your Web3Auth Client ID from the [Dashboard](https://developer.metamask.io/). It's a mandatory field of type `String`. | +| `web3AuthNetwork` | Web3Auth Network: `.SAPPHIRE_MAINNET`, `.SAPPHIRE_DEVNET`, `.MAINNET`, `.CYAN`, `.AQUA`, or `.TESTNET`. Mandatory field of type `Web3AuthNetwork`. | +| `redirectUrl` | URL that Web3Auth will redirect API responses upon successful authentication. It's a mandatory field of type `String`. | +| `sessionTime?` | Session duration in seconds. Default is `86400 * 30` (30 days). Maximum is 30 days. | +| `useSFAKey?` | Use SFA key to get single factor auth key. Default is `false`. Useful for wallet pre-generation and SFA mode. | +| `defaultChainId?` | Default chain ID to use. Default is `"0x1"` (Ethereum mainnet). | +| `enableLogging?` | Enable SDK logging. Default is `false`. | + +**Advanced parameters:** + +| Parameter | Description | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `whiteLabel?` | Whitelabel options for custom UI, branding, and translations. Takes `WhiteLabelData` as a value. | +| `authConnectionConfig?` | Auth connection config for custom auth connections. Takes `[AuthConnectionConfig]` as a value. | +| `mfaSettings?` | Configure MFA settings for authentication. Takes `MfaSettings` as a value. | +| `chains?` | Custom chain configuration for blockchain networks. Takes `[Chains]` as a value. See [Chains configuration](#chains-configuration) below. | +| `walletServicesConfig?` | Configuration for Wallet Services including whitelabel options. Takes `WalletServicesConfig` as a value. | ```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 sign 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 Embedded Wallets dashboard + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + sessionTime: 86400 * 7 // 7 days (in seconds) + ) +) +``` + +## Chains configuration + +The `chains` parameter lets you specify custom blockchain networks for the SDK. +When set, these chains are used by Wallet Services (`showWalletUI`, `request`) in addition to +any chains configured in the project dashboard. + +### `Chains` fields + +| Field | Type | Required | Description | +| ------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------- | +| `chainId` | `String` | Yes | Chain ID in hex format (for example, `"0x1"` for Ethereum mainnet, `"0x89"` for Polygon). | +| `rpcTarget` | `String` | Yes | RPC endpoint URL for the chain. | +| `chainNamespace` | `ChainNamespace` | No | Namespace of the chain. Accepts `.eip155`, `.solana`, or `.other`. Default is `.eip155`. | +| `decimals?` | `Int?` | No | Number of decimals for the native token. Default is `18`. | +| `blockExplorerUrl?` | `String?` | No | URL of the block explorer for this chain. | +| `displayName?` | `String?` | No | Human-readable name for the chain. | +| `logo?` | `String?` | No | URL of the chain's logo image. | +| `ticker?` | `String?` | No | Ticker symbol for the native token (for example, `"ETH"`). | +| `tickerName?` | `String?` | No | Full name of the native token (for example, `"Ethereum"`). | + +### Interface ```swift -web3Auth = Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard - network: .sapphire_mainnet, // or .sapphire_devnet - sessionTime: 86400 * 7, // 7 days (in seconds) - redirectUrl: "com.yourapp.bundleid://auth" -)) +public struct Chains: Codable { + public let chainNamespace: ChainNamespace + public let decimals: Int? + public let blockExplorerUrl: String? + public let chainId: String? + public let displayName: String? + public let logo: String? + public let rpcTarget: String + public let ticker: String? + public let tickerName: String? +} +``` + +### Example + +```swift +web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + chains: [ + Chains( + chainId: "0x89", + rpcTarget: "https://rpc.ankr.com/polygon", + displayName: "Polygon Mainnet", + ticker: "MATIC", + tickerName: "Matic", + blockExplorerUrl: "https://polygonscan.com" + ) + ] + ) +) +``` + +## Wallet Services configuration + +The `walletServicesConfig` parameter in `Web3AuthOptions` customizes the behavior of the wallet +UI (`showWalletUI`) and request signing (`request`). +For full configuration options, see the [Wallet Services](./wallet-services.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 sign-in 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 -Customize the brand experience by customizing the Web3Auth Sign-in 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 7c7b5b4d574..161d482f325 100644 --- a/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx +++ b/embedded-wallets/sdk/ios/advanced/custom-authentication.mdx @@ -1,52 +1,51 @@ --- -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://developer.metamask.io) with your desired configuration. +[Create a connection](../../../dashboard/authentication.mdx) from the **Authentication** tab of +your project in the [Embedded Wallets developer dashboard](https://developer.metamask.io). ::: -To configure a connection, you need to provide the particular details of the connection into our Embedded Wallets dashboard. This enables us to map 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 sign-in 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 Sign-in providers like Auth0, AWS Cognito, Firebase, or your own custom JWT sign-in), you can add the configuration using the `loginConfig` parameter during the initialization. - -The `loginConfig` parameter is a key value map. The key should be one of the `Web3AuthProvider` in its string form, and the value should be a `W3ALoginConfig` struct. +The `authConnectionConfig` parameter is an array of `AuthConnectionConfig` instances, each defining +a specific authentication connection. ### Parameters -After creating the verifier, you can use the following parameters in the `W3ALoginConfig`. +After creating the auth connection from the [Embedded Wallets developer dashboard](https://developer.metamask.io), you can use the following parameters in the `AuthConnectionConfig`. -| Parameter | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `verifier` | The name of the verifier that you have registered on the Embedded Wallets dashboard. It's a mandatory field, and it accepts a string value. | -| `typeOfLogin` | Type of login of this verifier, this value will affect the login flow that is adapted. For example, if you choose `google`, a Google sign-in flow will be used. If you choose `jwt`, you should be providing your own JWT token, no sign-in flow will be presented. It's a mandatory field, and accepts `TypeOfLogin` as a value. | -| `clientId` | Client ID provided by your login provider used for custom verifier. for example, Google's Client ID or Web3Auth's client ID if using JWT as `TypeOfLogin`. It's a mandatory field, and it accepts a string value. | -| `name?` | Display name for the verifier. If null, the default name is used. It accepts a string value. | -| `description?` | Description for the button. If provided, it renders as a full length button. else, icon button. It accepts a string value. | -| `verifierSubIdentifier?` | The field in JWT token which maps to verifier ID. Please make sure you selected correct JWT verifier ID in the developer dashboard. It accepts a string value. | -| `logoHover?` | Logo to be shown on mouse hover. It accepts a string value. | -| `logoLight?` | Light logo for dark background. It accepts a string value. | -| `logoDark?` | Dark logo for light background. It accepts a string value. | -| `mainOption?` | Show login button on the main list. It accepts a boolean value; default is false. | -| `showOnModal?` | Whether to show the login button on modal or not. Default value is true. | -| `showOnDesktop?` | Whether to show the login button on desktop. It accepts a boolean value; default is true. | -| `showOnMobile?` | Whether to show the login button on mobile. It accepts a boolean value; default is true. | +| Parameter | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `authConnectionId` | Name of the auth connection registered in the Embedded Wallets dashboard. Required. `String`. | +| `authConnection` | Sign-in type for this connection. Social values such as `.GOOGLE` trigger the provider sign-in flow. `.CUSTOM` marks a JWT-based auth connection: Auth0 and similar providers retrieve the token via `ExtraLoginOptions`, while Firebase, AWS Cognito, or your own JWT server use `LoginParams.idToken`. Required. `AuthConnection`. | +| `clientId` | Client ID from your sign-in provider (for example, Google Client ID), or your Embedded Wallets client ID when using `.CUSTOM`. Required. `String`. | +| `name?` | Display name for the auth connection. If `nil`, the default name is used. `String`. | +| `description?` | Description for the sign-in button. If provided, the button renders at full width; otherwise it renders as an icon button. `String`. | +| `groupedAuthConnectionId?` | JWT token field that maps to a grouped auth connection ID. Must match the JWT auth connection ID configured in the dashboard. `String`. | +| `logoHover?` | Logo shown on mouse hover. `String`. | +| `logoLight?` | Light logo for dark backgrounds. `String`. | +| `logoDark?` | Dark logo for light backgrounds. `String`. | +| `mainOption?` | Show the sign-in button on the main list. Default is `false`. `Bool`. | +| `showOnModal?` | Show the sign-in button on the modal. Default is `true`. `Bool`. | +| `showOnDesktop?` | Show the sign-in button on desktop. Default is `true`. `Bool`. | +| `showOnMobile?` | Show the sign-in button on mobile. Default is `true`. `Bool`. | +| `jwtParameters?` | Default JWT sign-in options for this auth connection. Useful for Auth0 configuration. `ExtraLoginOptions`. | +| `isDefault?` | Whether this auth connection is the default connector. Used internally by the SDK. `Bool`. | ```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 +139,24 @@ public enum TypeOfLogin: String, Codable { import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.google, - clientId: "YOUR_GOOGLE_CLIENT_ID", - ) - ] - // focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets 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 +167,24 @@ let web3Auth = try await Web3Auth( import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.facebook, - clientId: "YOUR_FACEBOOK_CLIENT_ID", - ) - ] - // focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets 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 +195,24 @@ let web3Auth = try await Web3Auth( import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId:"YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.jwt, - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - ) - ] - // focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets 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 +221,8 @@ let web3Auth = try await Web3Auth( ## Configure extra sign-in options -Additional to the sign-in config during initialization, you can pass extra options to the `login` function to configure the sign-in flow for cases requiring additional info for enabling sign-in. The `ExtraLoginOptions` accepts the following parameters. +In addition to the auth connection config during initialization, you can pass extra options to the +`connectTo` function to configure the sign-in flow. `ExtraLoginOptions` accepts the following parameters. ### Parameters @@ -219,29 +236,31 @@ Additional to the sign-in config during initialization, you can pass extra optio -| Parameter | Description | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `additionalParams?` | Additional params in `[String:String]` format for OAuth login, use id_token(JWT) to authenticate with Web3Auth. | -| `domain?` | Your custom authentication domain as string. For example, if you are using Auth0, it can be `example.au.auth0.com`. | -| `client_id?` | Client ID as string, provided by your login provider used for custom verifier. | -| `leeway?` | The value used to account for clock skew in JWT expirations. The value is in the seconds, and ideally should no more than 60 seconds or 120 seconds at max. It takes integer value. | -| `verifierIdField?` | The field in JWT token which maps to verifier ID. Please make sure you selected correct JWT verifier ID in the developer dashboard. It accepts a string value. | -| `isVerifierIdCaseSensitive?` | Boolean to confirm Whether the verifier ID field is case sensitive or not. | -| `display?` | Allows developers the configure the display of UI. It accepts a string value. | -| `prompt?` | Prompt shown to the user during authentication process. It accepts a string value. | -| `max_age?` | Max time allowed without reauthentication. If the last time user authenticated is greater than this value, then user must reauthenticate. It accepts a string value. | -| `ui_locales?` | The space separated list of language tags, ordered by preference. For instance `fr-CA fr en`. | -| `id_token_hint?` | It denotes the previously issued ID token. It accepts a string value. | -| `id_token?` | JWT (ID token) to be passed for login. | -| `login_hint?` | It is used to send the user's email address during email passwordless login. It accepts a string value. | -| `acr_values?` | acr_values | -| `scope?` | The default scope to be used on authentication requests. The defaultScope defined in the Auth0Client is included along with this scope. It accepts a string value. | -| `audience?` | The audience, presented as the aud claim in the access token, defines the intended consumer of the token. It accepts a string value. | -| `connection?` | The name of the connection configured for your application. If null, it will redirect to the Auth0 Login Page and show the Login Widget. It accepts a string value. | -| `state?` | State | -| `response_type?` | Defines which grant to execute for the authorization server. It accepts a string value. | -| `nonce?` | Nonce | -| `redirect_uri?` | It can be used to specify the default URL, where your custom JWT verifier can redirect your browser to with the result. If you are using Auth0, it must be allowlisted in the Allowed Callback URLs in your Auth0's application. | +| Parameter | Description | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `additionalParams?` | Additional 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`. | +| `login_hint?` | Hint for the sign-in provider (for example, an email address). For passwordless flows, prefer `LoginParams.loginHint`. `String`. | +| `access_token?` | Access token for OAuth flows. `String`. | +| `flow_type?` | Email passwordless flow type. `EmailFlowType` (`.code` or `.link`). | +| `acr_values?` | Authentication context class reference values requested from the provider. `String`. | +| `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 +268,31 @@ Additional to the sign-in config during initialization, you can pass extra optio ```swift public struct ExtraLoginOptions: Codable { - let display: String? - let prompt: String? - let max_age: String? - let ui_locales: String? - let id_token_hint: String? - let id_token: String? - let login_hint: String? - let acr_values: String? - let scope: String? - let audience: String? - let connection: String? - let domain: String? - let client_id: String? - let redirect_uri: String? - let leeway: Int? - let verifierIdField: String? - let isVerifierIdCaseSensitive: Bool? - let additionalParams: [String : String]? + let display: String? + let prompt: String? + let max_age: String? + let ui_locales: String? + let id_token_hint: String? + let id_token: String? + var login_hint: String? + let acr_values: String? + let scope: String? + let audience: String? + let connection: String? + let domain: String? + let client_id: String? + let redirect_uri: String? + let leeway: Int? + let userIdField: String? + let isUserIdCaseSensitive: Bool? + let additionalParams: [String: String]? + let access_token: String? + let flow_type: EmailFlowType? +} + +public enum EmailFlowType: String, Codable { + case code = "code" + case link = "link" } ``` @@ -274,7 +300,7 @@ public struct ExtraLoginOptions: Codable { -### Single verifier example +### Single auth connection example -Auth0 has a special sign-in flow, called the SPA flow. This flow requires a `client_id` and `domain` -to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these -configurations in the `ExtraLoginOptions` object in the sign-in function. + +Auth0 uses the `.CUSTOM` auth connection type with Auth0's SPA flow. Unlike Firebase or custom JWT +servers where you pass a pre-obtained token in `LoginParams.idToken`, the SDK retrieves the JWT +`id_token` from Auth0 directly. Pass your Auth0 `client_id` and `domain` in `ExtraLoginOptions` in +the `connectTo` call. ```swift -import +import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId:"YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - // Optional loginConfig object - //focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.jwt, - clientId: "YOUR_AUTH0_CLIENT_ID", - ) - ] - //focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets 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 +354,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 sign-in flows. ```swift import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId:"YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .testnet, - // Optional loginConfig object - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // Get it from MetaMask Developer Dashboard - typeOfLogin: TypeOfLogin.jwt, - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - ) - ] - //focus-end - ) + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "your-auth-connection-id", // Get it from Embedded Wallets 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 +393,32 @@ let result = await web3Auth.login( -To use the email passwordless sign-in, you need to put the email into the `login_hint` parameter of -the `ExtraLoginOptions`. By default, the sign-in flow will be `code` flow, if you want to use the -`link` flow, you need to put `flow_type` into the `additionalParams` parameter of the -`ExtraLoginOptions`. + +For Email Passwordless sign-in, pass the email address as the `loginHint` parameter of `LoginParams`. +The default flow is `code` (OTP). To use a magic link flow instead, set `flow_type` to `.link` in +`extraLoginOptions`. ```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 +426,86 @@ let result = try await web3Auth.login( -To use the SMS Passwordless sign-in, send the phone number as the `login_hint` parameter of the `ExtraLoginOptions`. Please ensure the phone number takes the format: -+\{country_code}-\{phone_number}, that is, (+91-09xx901xx1). +For SMS Passwordless sign-in, pass the phone number as the `loginHint` parameter of `LoginParams`. +The phone number must use the format `+{country_code}-{phone_number}`, for example `+91-9911223344`. ```swift import Web3Auth -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - - // focus-start -let result = try await web3Auth.login(W3ALoginParams( - Web3AuthProvider.SMS_PASSWORDLESS, - // The phone number should be in format of +{country_code}-{phone_number} - extraLoginOptions: .init(loginHint: "+91-9911223344") -)) - // focus-end +let web3Auth = try await Web3Auth( + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth" + ) +) + +// focus-start +let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .SMS_PASSWORDLESS, + loginHint: "+91-9911223344" + ) +) +// focus-end ``` -### Aggregate verifier example +### Grouped auth connection example -You can use aggregate verifier to combine multiple sign-in methods to get the same address for the users regardless of their sign-in providers. For example, combining a Google and email passwordless sign-in, or Google and GitHub via Auth0 to access the same address for your user. +Grouped auth connections combine multiple sign-in methods so your users get the same address regardless +of how they sign in. For example, combine Google and Email Passwordless, or Google and GitHub via +Auth0, to resolve to the same address. ```swift import Web3Auth let web3Auth = try await Web3Auth( - W3AInitParams( - clientId: clientId, - network: network, - redirectUrl: "web3auth.ios-aggregate-example://auth", - // focus-start - loginConfig: [ - TypeOfLogin.google.rawValue: .init( - verifier: "aggregate-sapphire", - typeOfLogin: .google, - name: "Web3Auth-Aggregate-Verifier-Google-Example", - clientId: "YOUR_GOOGLE_CLIENT_ID", - verifierSubIdentifier: "w3a-google" - ), - TypeOfLogin.jwt.rawValue: .init( - verifier: "aggregate-sapphire", - typeOfLogin: .jwt, - clientId: "YOUR_AUTH0_CLIENT_ID", - verifierSubIdentifier: "w3a-a0-github" - ) - ], - // focus-end -)) - -func loginWithGoogle() async { - // focus-start - let result = try await web3Auth?.login( - W3ALoginParams( - loginProvider: .GOOGLE, + options: Web3AuthOptions( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + web3AuthNetwork: .SAPPHIRE_MAINNET, + redirectUrl: "com.yourapp.bundleid://auth", + // focus-start + authConnectionConfig: [ + AuthConnectionConfig( + authConnectionId: "aggregate-sapphire", + groupedAuthConnectionId: "w3a-google", + authConnection: .GOOGLE, + name: "Aggregate Login", + clientId: "YOUR_GOOGLE_CLIENT_ID" + ), + AuthConnectionConfig( + authConnectionId: "aggregate-sapphire", + groupedAuthConnectionId: "w3a-a0-email-passwordless", + authConnection: .CUSTOM, + name: "Aggregate Login", + clientId: "YOUR_AUTH0_CLIENT_ID" + ) + ] + // focus-end ) - ) - // focus-end +) + +func loginWithGoogle() async throws { + // focus-next-line + let result = try await web3Auth.connectTo(loginParams: LoginParams(authConnection: .GOOGLE)) } -func loginWithGitHub() async { - // focus-start - let result = try await web3Auth?.login( - W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: ExtraLoginOptions(display: nil, prompt: nil, max_age: nil, ui_locales: nil, id_token_hint: nil, id_token: nil, login_hint: nil, acr_values: nil, scope: nil, audience: nil, connection: "github", domain: "https://web3auth.au.auth0.com", client_id: nil, redirect_uri: nil, leeway: nil, verifierIdField: "email", isVerifierIdCaseSensitive: false, additionalParams: nil), +func loginWithGitHub() async throws { + // focus-start + let result = try await web3Auth.connectTo( + loginParams: LoginParams( + authConnection: .CUSTOM, + extraLoginOptions: ExtraLoginOptions( + connection: "github", + domain: "https://web3auth.au.auth0.com", + userIdField: "email", + isUserIdCaseSensitive: false + ) + ) ) - ) - // focus-end + // focus-end } ``` diff --git a/embedded-wallets/sdk/ios/advanced/dapp-share.mdx b/embedded-wallets/sdk/ios/advanced/dapp-share.mdx index c8c3970e20c..c0a8610df44 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 sign-in service via node operators:** This share is further split + amongst a network of nodes and retrieved via conventional authentication flows. +2. **`ShareB` is stored on the user's device:** Implementation is device and system specific. + For example, on mobile devices, the share could be stored in device storage secured via + 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 dapp share login flow, we need to reconstruct the Shares `A` and `B`. `Share B` is managed by the login service and is provided on successful authentication. Whereas in web platforms, `Share A` is stored in the browser context. We can still store it in the browser context for mobile devices, but this has a few risks like users accidentally deleting browser data. This is a bigger problem in mobile devices since the user doesn't realize that the browser is being used to login within the app and clearing the browser data can cause their logins to fail. Hence, to tackle this issue, Web3Auth issues a dapp share, that is, a backup share that can be stored by the app developer directly within their application and used to reconstruct the private key after successful login by the user. +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 delete browser data by mistake. +This is a bigger problem on mobile because users don't realize the browser is used to sign in +within the app, and clearing browser data can cause sign-in to fail. +To address this, Embedded Wallets issues a dapp share, a backup share that you can store +directly in your app and use to reconstruct the private key after a successful sign-in. ## Dapp share in iOS -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 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 sign in without repeating the full flow. 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 36612926a1a..666a25605ad 100644 --- a/embedded-wallets/sdk/ios/advanced/mfa.mdx +++ b/embedded-wallets/sdk/ios/advanced/mfa.mdx @@ -1,65 +1,83 @@ --- -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. +Four MFA level values are available. :::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. ::: ### MFA level options -| 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. | -| NONE | Skips the MFA setup screen. | +| MFA Level | Description | +| --------- | ------------------------------------------------------------ | +| DEFAULT | Shows the MFA screen every third sign-in. | +| OPTIONAL | Shows the MFA screen on every sign-in, but user can skip it. | +| MANDATORY | Makes it mandatory to set up MFA after first sign-in. | +| NONE | Skips the MFA setup screen. | ### Usage ```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. -| Parameter | Description | -| ---------------------- | ------------------------------------------------------------------------ | -| `deviceShareFactor?` | MFA setting for deviceShareFactor. It accepts `MfaSetting` as a value. | -| `backUpShareFactor?` | MFA setting for backUpShareFactor. It accepts `MfaSetting` as a value. | -| `socialBackupFactor?` | MFA setting for socialBackupFactor. It accepts `MfaSetting` as a value. | -| `passwordFactor?` | MFA setting for passwordFactor. It accepts `MfaSetting` as a value. | -| `passkeysFactor?` | MFA setting for passkeysFactor. It accepts `MfaSetting` as a value. | -| `authenticatorFactor?` | MFA setting for authenticatorFactor. It accepts `MfaSetting` as a value. | +| Parameter | Description | +| ---------------------- | -------------------------------------------------------------------------- | +| `deviceShareFactor?` | MFA setting for deviceShareFactor. It accepts `MfaSetting` as a value. | +| `backUpShareFactor?` | MFA setting for backUpShareFactor. It accepts `MfaSetting` as a value. | +| `socialBackupFactor?` | MFA setting for socialBackupFactor. It accepts `MfaSetting` as a value. | +| `passwordFactor?` | MFA setting for `passwordFactor`. It accepts `MfaSetting` as a value. | +| `passkeysFactor?` | MFA setting for `passkeysFactor`. It accepts `MfaSetting` as a value. | +| `authenticatorFactor?` | MFA setting for `authenticatorFactor`. It accepts `MfaSetting` as a value. | ```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/wallet-services.mdx b/embedded-wallets/sdk/ios/advanced/wallet-services.mdx new file mode 100644 index 00000000000..1a1fd3ac64e --- /dev/null +++ b/embedded-wallets/sdk/ios/advanced/wallet-services.mdx @@ -0,0 +1,182 @@ +--- +title: Wallet Services configuration +sidebar_label: Wallet Services +description: 'Web3Auth iOS SDK - 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` at no cost. +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..3be03a076f7 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: -| Parameter | Description | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `appName?` | Display name for the app in the UI. | -| `logoLight?` | App logo to be used in dark mode. It accepts URL as a string. | -| `logoDark?` | App logo to be used in light mode. It accepts URL as a string. | -| `defaultLanguage?` | Language which will be used by Web3Auth, app will use browser language if not specified. Default language is `Language.en`. Checkout `Language` for supported languages. | -| `mode?` | Theme mode for the login modal. Choose between `ThemeModes.auto`, `ThemeModes.light` or `ThemeModes.dark` background modes. Default value is `ThemeModes.AUTO`. | -| `theme?` | Used to customize the theme of the login modal. It accepts dictonary of `[String:String]` as a value. | -| `appUrl?` | URL to be used in the modal. It accepts URL as a string. | -| `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are nil, the default Web3Auth logo will be used for the loader. Default value is false. | +| Parameter | Description | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `appName?` | Display name for the app in the UI. | +| `logoLight?` | App logo to be used in dark mode. It accepts URL as a string. | +| `logoDark?` | App logo to be used in light mode. It accepts URL as a string. | +| `defaultLanguage?` | Language used by Embedded Wallets. Falls back to browser language if not specified. Default is `Language.en`. See `Language` for supported languages. | +| `mode?` | Theme mode for the sign-in modal. Choose between `ThemeModes.auto`, `ThemeModes.light` or `ThemeModes.dark` background modes. Default value is `ThemeModes.auto`. | +| `theme?` | Used to customize the theme of the sign-in modal. It accepts a dictionary of `[String: String]` as a value. | +| `appUrl?` | URL to be used in the modal. It accepts URL as a string. | +| `useLogoLoader?` | Use logo loader. If `logoDark` and `logoLight` are nil, the default Embedded Wallets logo is used for the loader. Default is false. | ```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/usage/README.mdx b/embedded-wallets/sdk/ios/usage/README.mdx index 03065666288..0463f04c017 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()`](./get-user-info.mdx) | Retrieves the authenticated user's information. | -### Private key functions +### Private key methods -| Function Name | Description | -| ------------------------------------------------------ | ------------------------------------------------------------------------------- | -| [`getPrivKey()`](./get-private-key.mdx) | Retrieve the user's secp256k1 private key for EVM-compatible chains. | -| [`getEd25519PrivKey()`](./get-ed25519-private-key.mdx) | Retrieve the user's ed25519 private key for chains like Solana, Near, Algorand. | +| Method | Description | +| ------------------------------------------------------ | -------------------------------------------------------------------------------- | +| [`getPrivateKey()`](./getPrivateKey.mdx) | Retrieves the user's secp256k1 private key for EVM-compatible chains. | +| [`getEd25519PrivateKey()`](./getEd25519PrivateKey.mdx) | Retrieves the user's Ed25519 private key for chains like Solana, Near, Algorand. | -### Security functions +### Security methods -| Function Name | Description | -| --------------------------------- | ------------------------------------------------- | -| [`enableMFA()`](./enable-mfa.mdx) | Enables Multi-Factor Authentication for the user. | -| [`manageMFA()`](./manage-mfa.mdx) | Allows users to manage their MFA settings. | +| Method | Description | +| --------------------------------- | ---------------------------------- | +| [`enableMFA()`](./enable-mfa.mdx) | Enables MFA for the user. | +| [`manageMFA()`](./manage-mfa.mdx) | Manages MFA settings for the user. | -### Wallet Services functions +### Wallet Services methods -| Function Name | Description | -| -------------------------------------------------------- | ----------------------------------------------------------------- | -| [`launchWalletServices()`](./launch-wallet-services.mdx) | Launches the templated wallet UI in WebView. | -| [`request()`](./request.mdx) | Opens templated transaction screens for signing EVM transactions. | +| Method | Description | +| -------------------------------------- | ---------------------------------------------------------------- | +| [`showWalletUI()`](./showWalletUI.mdx) | Launches the built-in wallet UI in WebView. | +| [`request()`](./request.mdx) | Opens built-in transaction screens for signing EVM transactions. | diff --git a/embedded-wallets/sdk/ios/usage/connectTo.mdx b/embedded-wallets/sdk/ios/usage/connectTo.mdx new file mode 100644 index 00000000000..c72ed1c9013 --- /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 sign-in method to be used. You can use any of the supported values: `.GOOGLE`, `.FACEBOOK`, `.REDDIT`, `.DISCORD`, `.TWITCH`, `.APPLE`, `.LINE`, `.GITHUB`, `.KAKAO`, `.LINKEDIN`, `.TWITTER`, `.WEIBO`, `.WECHAT`, `.EMAIL_PASSWORDLESS`, `.SMS_PASSWORDLESS`, and `.FARCASTER`. | +| `authConnectionId?` | The auth connection ID for the connection. Required for SFA mode when `idToken` is passed. Default value is `nil`. | +| `groupedAuthConnectionId?` | The grouped auth connection ID for grouped auth connections. It accepts `String` as a value. | +| `extraLoginOptions?` | It can be used to set the OAuth sign-in options for the corresponding `authConnection`. Default value is `nil`, and it accepts `ExtraLoginOptions` as a value. | +| `appState?` | It can be used to keep track of the app state when user will be redirected to app after sign-in. Default is `nil`, and it accepts a string value. | +| `mfaLevel?` | Customize the MFA screen shown to the user during authentication. Default value is `.DEFAULT`, which shows MFA screen every 3rd sign-in. It accepts `MFALevel` as a value. | +| `dappShare?` | Custom auth connection sign-ins can get a dapp share returned to them post successful sign-in. This is useful if the dapps want to use this share to allow users to sign in seamlessly. It accepts a string value. | +| `curve?` | It will be used to determine the public key encoded in the JWT token which is returned in `getUserInfo` after user sign-in. Private key returned by `getPrivateKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivateKey`. The default value is `.SECP256K1`. | +| `loginHint?` | Used to specify the user's email address or phone number for email/SMS passwordless sign-in flows. For SMS, the format should be: `+{country_code}-{phone_number}` (for example `+1-1234567890`). It accepts a string value. | +| `idToken?` | JWT token for SFA (Single Factor Auth) mode. When provided, enables direct authentication without the social sign-in browser flow. It accepts a string value. | + + + + + +```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/enable-mfa.mdx b/embedded-wallets/sdk/ios/usage/enable-mfa.mdx index e30dede8c84..2a565272415 100644 --- a/embedded-wallets/sdk/ios/usage/enable-mfa.mdx +++ b/embedded-wallets/sdk/ios/usage/enable-mfa.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/get-ed25519-private-key.mdx b/embedded-wallets/sdk/ios/usage/get-ed25519-private-key.mdx deleted file mode 100644 index 726c5c68b03..00000000000 --- a/embedded-wallets/sdk/ios/usage/get-ed25519-private-key.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Get Ed25519 private key -sidebar_label: Get Ed25519 private key -description: 'Web3Auth iOS SDK - getEd25519PrivKey | Embedded Wallets' ---- - -To retrieve the secp256k1 private key of the user., use `getEd25519PrivKey` method. This private key can be used to sign transactions on Solana, Near, Algorand, and other chains that use the ed25519 curve. - -## Usage - -```swift -let privateKey = web3Auth.getEd25519PrivKey(); -``` diff --git a/embedded-wallets/sdk/ios/usage/get-private-key.mdx b/embedded-wallets/sdk/ios/usage/get-private-key.mdx deleted file mode 100644 index 246981881de..00000000000 --- a/embedded-wallets/sdk/ios/usage/get-private-key.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Get Secp256k1 private key -sidebar_label: Get Secp256k1 private key -description: 'Web3Auth iOS SDK - getPrivKey | Embedded Wallets' ---- - -To retrieve the secp256k1 private key of the user, use `getPrivkey` method. The method returns an EVM compatible private key which can be used to sign transactions on EVM compatible chains. - -## Usage - -```swift -let privateKey = web3Auth.getPrivKey(); -``` diff --git a/embedded-wallets/sdk/ios/usage/get-user-info.mdx b/embedded-wallets/sdk/ios/usage/get-user-info.mdx index 55f7fbc6a02..4418fb3bd5c 100644 --- a/embedded-wallets/sdk/ios/usage/get-user-info.mdx +++ b/embedded-wallets/sdk/ios/usage/get-user-info.mdx @@ -4,15 +4,18 @@ sidebar_label: Get user info description: 'Web3Auth iOS SDK - getUserInfo | Embedded Wallets' --- -You can use the `getUserInfo` method to retrieve various details about the user, such as their login type, whether multi-factor authentication (MFA) is enabled, profile image, name, and other relevant information. +The `getUserInfo` method returns details about the user, including sign-in type, whether +multi-factor authentication (MFA) is enabled, profile image, and name. + +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/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/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/launch-wallet-services.mdx b/embedded-wallets/sdk/ios/usage/launch-wallet-services.mdx deleted file mode 100644 index 6785cdaac78..00000000000 --- a/embedded-wallets/sdk/ios/usage/launch-wallet-services.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Launch Wallet Services -sidebar_label: Show wallet UI -description: 'Web3Auth iOS SDK - launchWalletServices | Embedded Wallets' ---- - -import TabItem from '@theme/TabItem' -import Tabs from '@theme/Tabs' - -The `launchWalletServices` method launches a WebView which allows you to use the prebuilt wallet UI services. The method takes `ChainConfig` as the required input. Wallet Services is currently only available for EVM chains. - -:::note - -Access to Wallet Services is gated. You can use this feature in `sapphire_devnet` at no cost. The minimum [pricing plan](https://web3auth.io/pricing.html) to use this feature in a production environment is the **Scale Plan**. - -::: - -Wallet Services - -## Parameters - - - - - -| Parameter | Description | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `chainNamespace` | Custom configuration for your preferred blockchain. As of now only EVM supported. Default value is `ChainNamespace.eip155`. | -| `decimals?` | Number of decimals for the currency ticker. Default value is 18, and accepts `Int` as value. | -| `blockExplorerUrl?` | Blockchain's explorer URL. (for example, `https://etherscan.io`) | -| `chainId` | The chain ID of the selected blockchain `String`. | -| `displayName?` | Display Name for the chain. | -| `logo?` | Logo for the selected `chainNamespace` and `chainId`. | -| `rpcTarget` | RPC Target URL for the selected `chainNamespace` and `chainId`. | -| `ticker?` | Default currency ticker of the network (for example, `ETH`). | -| `tickerName?` | Name for currency ticker (for example, `Ethereum`). | - - - - - -```swift -public struct ChainConfig: Codable { - public init(chainNamespace: ChainNamespace = ChainNamespace.eip155, decimals: Int? = 18, blockExplorerUrl: String? = nil, chainId: String, displayName: String? = nil, logo: String? = nil, rpcTarget: String, ticker: String? = nil, tickerName: String? = nil) { - self.chainNamespace = chainNamespace - self.decimals = decimals - self.blockExplorerUrl = blockExplorerUrl - self.chainId = chainId - self.displayName = displayName - self.logo = logo - self.rpcTarget = rpcTarget - self.ticker = ticker - self.tickerName = tickerName - } -} - -``` - - - - -## Usage - -```swift -do { - // focus-start - try await web3Auth!.launchWalletServices( - chainConfig: ChainConfig( - chainId: "0xaa36a7", - rpcTarget: "https://eth-sepolia.public.blastapi.io" - ) - ) - // focus-end -} catch { - print(error.localizedDescription) - // Handle error -} -``` diff --git a/embedded-wallets/sdk/ios/usage/login.mdx b/embedded-wallets/sdk/ios/usage/login.mdx deleted file mode 100644 index 4b0bab540da..00000000000 --- a/embedded-wallets/sdk/ios/usage/login.mdx +++ /dev/null @@ -1,272 +0,0 @@ ---- -title: Login user -sidebar_label: Sign in a user -description: 'Web3Auth iOS SDK - login | Embedded Wallets' ---- - -import TabItem from '@theme/TabItem' -import Tabs from '@theme/Tabs' - -To login in a user, you can use the `login` method. It will trigger login flow will navigate the user to a browser model allowing the user to login into the service. You can pass in the supported providers to the login method for specific social logins (such as GOOGLE, APPLE, FACEBOOK) and do whitelabel login. - -## Parameters - -The login method accepts `W3ALoginParams` as a required parameter. - - - - - -| Parameter | Description | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `loginProvider` | It sets the OAuth login method to be used. You can use any of the supported values are `GOOGLE`, `FACEBOOK`, `REDDIT`, `DISCORD`, `TWITCH`, `APPLE`, `LINE`, `GITHUB`, `KAKAO`, `LINKEDIN`, `TWITTER`, `WEIBO`, `WECHAT`, `EMAIL_PASSWORDLESS`, `SMS_PASSWORDLESS`, and `FARCASTER`. | -| `extraLoginOptions?` | It can be used to set the OAuth login options for corresponding `loginProvider`. For instance, you'll need to pass user's email address as. Default value for the field is `nil`, and it accepts `ExtraLoginOptions` as a value. | -| `redirectUrl?` | URL where user will be redirected after successfull login. By default user will be redirected to same page where login will be initiated. Default value for the field is `nil`, and accepts `URL` as a value. | -| `appState?` | It can be used to keep track of the app state when user will be redirected to app after login. Default is `nil`, and it accepts a string value. | -| `mfaLevel?` | Customize the MFA screen shown to the user during OAuth authentication. Default value for field is `MFALevel.DEFAULT`, which shows MFA screen every 3rd login. It accepts `MFALevel` as a value. | -| `dappShare?` | Custom verifier logins can get a dapp share returned to them post successful login. This is useful if the dapps want to use this share to allow users to sign in without repeating the full flow. It accepts a string value. | -| `curve?` | It will be used to determine the public key encoded in the JWT token which returned in `getUserInfo` function after user login. This parameter won't change format of private key returned by We3Auth. Private key returned by `getPrivKey` is always secp256k1. To get the ed25519 key you can use `getEd25519PrivKey` method. The default value is `SUPPORTED_KEY_CURVES.SECP256K1`. | - - - - - -```swift -public struct W3ALoginParams: Codable { - public init() { - loginProvider = nil - dappShare = nil - extraLoginOptions = nil - redirectUrl = nil - appState = nil - mfaLevel = nil - curve = .SECP256K1 - } - - let loginProvider: String? - var dappShare: String? - let extraLoginOptions: ExtraLoginOptions? - let redirectUrl: String? - let appState: String? - let mfaLevel: MFALevel? - let curve: SUPPORTED_KEY_CURVES -} - -public enum Web3AuthProvider: String, Codable { - case GOOGLE = "google" - case FACEBOOK = "facebook" - case REDDIT = "reddit" - case DISCORD = "discord" - case TWITCH = "twitch" - case APPLE = "apple" - case LINE = "line" - case GITHUB = "github" - case KAKAO = "kakao" - case LINKEDIN = "linkedin" - case TWITTER = "twitter" - case WEIBO = "weibo" - case WECHAT = "wechat" - case EMAIL_PASSWORDLESS = "email_passwordless" - case JWT = "jwt" - case SMS_PASSWORDLESS = "sms_passwordless" - case FARCASTER = "farcaster" -} -``` - - - - -## Usage - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .GOOGLE)) -``` - -## Examples - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .GOOGLE)) -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .FACEBOOK)) -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .DISCORD)) -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .TWITCH)) -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network:.sapphire_mainnet, - redirectUrl: "bundleId://auth" - ) -) - -// focus-start -let result = try await web3Auth.login( - W3ALoginParams( - loginProvider: .EMAIL_PASSWORDLESS, - extraLoginOptions: .init(loginHint: "hello@web3auth.io") - ) -) -// focus-end -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable network: .sapphire_mainnet, redirectUrl: "bundleId://auth" )) - -// focus-start -let result = try await web3Auth.login( -W3ALoginParams( -Web3AuthProvider.SMS_PASSWORDLESS, -// The phone number should be in format of +{country_code}-{phone_number} -extraLoginOptions: .init(loginHint: "+91-9911223344") -) -) -// focus-end - -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" - ) -) - -// focus-next-line -let result = try await web3Auth.login(W3ALoginParams(loginProvider: .FARCASTER)) - -``` - - - - - -```swift -import Web3Auth - -let web3auth = try await Web3Auth(W3AInitParams( - clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable - network: .sapphire_mainnet, - redirectUrl: "bundleId://auth" -)) - -// focus-start -let result = try await web3Auth.login( - W3ALoginParams( - loginProvider: .JWT, - extraLoginOptions: .init(domain:"your-domain", id_token: "your_jwt_token") - ) -) -// focus-end -``` - - - diff --git a/embedded-wallets/sdk/ios/usage/logout.mdx b/embedded-wallets/sdk/ios/usage/logout.mdx index 4a11756d82d..88ae817dbae 100644 --- a/embedded-wallets/sdk/ios/usage/logout.mdx +++ b/embedded-wallets/sdk/ios/usage/logout.mdx @@ -4,10 +4,10 @@ sidebar_label: Sign out description: 'Web3Auth iOS SDK - logout | Embedded Wallets' --- -To logout the user and remove the session ID from the device you can use the `logout` method. The user will need to login again to use the dapp next time the dapp is opened. +To sign out the user and remove the session ID from the device, use the `logout` method. The user must sign in again to use the dapp the next time the dapp is opened. ## Usage ```swift -try await web3auth.logout() +try await web3Auth.logout() ``` diff --git a/embedded-wallets/sdk/ios/usage/manage-mfa.mdx b/embedded-wallets/sdk/ios/usage/manage-mfa.mdx index 0aeb2b67635..1d4c18c0a4f 100644 --- a/embedded-wallets/sdk/ios/usage/manage-mfa.mdx +++ b/embedded-wallets/sdk/ios/usage/manage-mfa.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 48a03e3f2a4..36e24911a1e 100644 --- a/embedded-wallets/sdk/ios/usage/request.mdx +++ b/embedded-wallets/sdk/ios/usage/request.mdx @@ -4,9 +4,16 @@ sidebar_label: Send requests description: 'Web3Auth iOS SDK - request | Embedded Wallets' --- -The `request` method facilitates the use of prebuilt transaction screens for signing transactions. The method will return [SignResponse](#signresponse). It can be used to sign transactions for any EVM chain and screens can be customized to match your branding. +The `request` method opens built-in transaction screens for signing transactions. +The method returns a `SignResponse?`. +Use it to sign transactions on any EVM chain. +You can white-label the screens to match your branding. -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.