From d0a95ef794e4926ee94980aa03154f506c0b70b7 Mon Sep 17 00:00:00 2001 From: AyushBherwani1998 Date: Wed, 2 Oct 2024 22:31:25 +0530 Subject: [PATCH 01/37] revamp ios docs --- docs/sdk/pnp/ios/custom-authentication.mdx | 244 +++++------ docs/sdk/pnp/ios/initialize.mdx | 19 +- docs/sdk/pnp/ios/install.mdx | 2 +- docs/sdk/pnp/ios/mfa.mdx | 216 ++++------ docs/sdk/pnp/ios/usage.mdx | 420 +++++++++---------- src/common/sdk/pnp/ios/_enable-mfa.mdx | 22 +- src/common/sdk/pnp/ios/_initialize.mdx | 6 - src/common/sdk/pnp/ios/_sms_passwordless.mdx | 16 +- 8 files changed, 435 insertions(+), 510 deletions(-) diff --git a/docs/sdk/pnp/ios/custom-authentication.mdx b/docs/sdk/pnp/ios/custom-authentication.mdx index 151d0ca16..3dea68bf9 100644 --- a/docs/sdk/pnp/ios/custom-authentication.mdx +++ b/docs/sdk/pnp/ios/custom-authentication.mdx @@ -9,41 +9,30 @@ import Tabs from "@theme/Tabs"; import GrowthPlanNote from "@site/src/common/docs/_growth_plan_note.mdx"; import SMSPasswordless from "@site/src/common/sdk/pnp/ios/_sms_passwordless.mdx"; +## Configuration + To use custom authentication (Using Social providers or Login providers like Auth0, AWS Cognito, -Firebase etc. or even your own custom JWT login) you can add the configuration to the `loginConfig` -parameter of the `W3AInitParams` object during the initialization. +Firebase etc. or even your own custom JWT login) you can add the configuration using the +`loginConfig` parameter during the initialization. The `loginConfig` parameter is a key value map. The key should be one of the `Web3AuthProvider` in its string form, and the value should be a `W3ALoginConfig` struct. To use custom authentication, first you'll need to configure your own verifier in the Web3Auth -Dashboard in Custom Authentication section. - - +Dashboard in "Custom Authentication" section. +[Learn how to create a custom verifier](/auth-provider-setup/verifiers). :::tip Create Custom Verifier -Check out how to create a **[Custom Verifier](/auth-provider-setup/verifiers)** on the Web3Auth -Dashboard. +Learn how to create a [Custom Verifier](/auth-provider-setup/verifiers) on the Web3Auth Dashboard. ::: -:::info using dapp share - -- dApp Share is only returned for the Custom verifiers. -- Also, 2FA should be enabled for the account using it. Use `mfaLevel = MFALevel.MANDATORY` in the - `W3ALoginParams` during login. See **[MFA](/sdk/pnp/ios/mfa)** for more details. - -::: - -Once the custom verifier is created, you need to specify the details of your verifier in the -`W3ALoginConfig` struct, the parameters of the struct are as follows: - -## `W3ALoginConfig` + -### Arguments +### Parameters -`W3ALoginConfig` +After creating the verifier, you can use the following parameters in the `W3ALoginConfig`. - ```swift public struct W3ALoginConfig: Codable { let verifier: String @@ -91,33 +79,16 @@ public struct W3ALoginConfig: Codable { let showOnDesktop: Bool? let showOnMobile: 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 } +```` + -### `typeOfLogin` - -```swift -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 -} -``` - +### Usage -```swift title="Usage" -web3Auth = await Web3Auth( +```swift +import Web3Auth + +let web3Auth = try await Web3Auth( W3AInitParams( clientId: "YOUR_CLIENT_ID", network: .sapphire_mainnet, // focus-start loginConfig: [ Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // get it from web3auth dashboard + verifier: "YOUR_VERIFIER_NAME", // Get it from web3auth dashboard typeOfLogin: TypeOfLogin.google, clientId: "YOUR_GOOGLE_CLIENT_ID", ) ] // focus-end -)) -``` + ) +) +```` +```swift +import Web3Auth -```swift title="Usage" -web3Auth = await Web3Auth( - W3AInitParams( - clientId: "YOUR_CLIENT_ID", - network: .sapphire_mainnet, - // focus-start - loginConfig: [ - Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // get it from web3auth dashboard - typeOfLogin: TypeOfLogin.facebook, - clientId: "YOUR_FACEBOOK_CLIENT_ID", - ) - ] - // focus-end -)) -``` +let web3Auth = try await Web3Auth( W3AInitParams( clientId: "YOUR_CLIENT_ID", network: +.sapphire_mainnet, // focus-start loginConfig: [ Web3AuthProvider.JWT.rawValue: .init( +verifier: "YOUR_VERIFIER_NAME", // Get it from web3auth dashboard typeOfLogin: TypeOfLogin.facebook, +clientId: "YOUR_FACEBOOK_CLIENT_ID", ) ] // focus-end ) ) +```` +```swift +import Web3Auth -```swift title="Usage" -web3Auth = await Web3Auth( +let web3Auth = try await Web3Auth( W3AInitParams( clientId:"YOUR_CLIENT_ID", network: .sapphire_mainnet, // focus-start loginConfig: [ Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // get it from web3auth dashboard + verifier: "YOUR_VERIFIER_NAME", // Get it from web3auth dashboard typeOfLogin: TypeOfLogin.jwt, - clientId: "YOUR_CLIENT_ID", // get it from web3auth dashboard + clientId: "YOUR_CLIENT_ID", ) ] // focus-end -)) -``` + ) +) +```` -## `ExtraLoginOptions` for special login methods +## Configure Extra Login Options -Additional to the `W3ALoginConfig` you can pass extra options to the `login` function to configure -the login flow for cases requiring additional info for enabling login. The `extraLoginOptions` -accepts the following parameters: +Additional to the login config during initialization, you can pass extra options to the `login` +function to configure the login flow for cases requiring additional info for enabling login. The +`ExtraLoginOptions` accepts the following parameters. + +### Parameters -## Single Verifier +### Single Verifier Example -### Using Auth0 Login + + Auth0 has a special login flow, called the SPA flow. This flow requires a `client_id` and `domain` to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these configurations in the `ExtraLoginOptions` object in the login function. ```swift -web3Auth = await Web3Auth( +import + +let web3Auth = try await Web3Auth( W3AInitParams( clientId:"YOUR_CLIENT_ID", network: .sapphire_mainnet, @@ -280,37 +259,42 @@ web3Auth = await Web3Auth( //focus-start loginConfig: [ Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // get it from web3auth dashboard for auth0 configuration + verifier: "YOUR_VERIFIER_NAME", // Get it from Web3auth dashboard typeOfLogin: TypeOfLogin.jwt, - clientId: "YOUR_AUTH0_CLIENT_ID", // auth0's client id, get it from auth0 dashboard + clientId: "YOUR_AUTH0_CLIENT_ID", ) ] //focus-end ) ) -let result = await web3Auth.login(W3ALoginParams(selectedLoginProvider, - // focus-start + // 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-end -)) + ) +) +// focus-end ``` -### Custom JWT 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. ```swift +import Web3Auth -web3Auth = await Web3Auth( +let web3Auth = try await Web3Auth( W3AInitParams( clientId:"YOUR_CLIENT_ID", network: .testnet, @@ -318,74 +302,94 @@ web3Auth = await Web3Auth( // focus-start loginConfig: [ Web3AuthProvider.JWT.rawValue: .init( - verifier: "YOUR_VERIFIER_NAME", // get it from web3auth dashboard + verifier: "YOUR_VERIFIER_NAME", // Get it from web3auth dashboard typeOfLogin: TypeOfLogin.jwt, - clientId: "BPi5PB_UiIZ-cPz1GtV5i1I2iOSOHuimiXBI0e-Oe_u6X3oVAbCiAZOTEBtTXw4tsluTITPqA8zMsfxIKMjiqNQ", // get it from web3auth dashboard + clientId: "YOUR_WEB3AUTH_CLIENT_ID", ) ] //focus-end ) ) + // focus-start let result = await web3Auth.login( W3ALoginParams( Web3AuthProvider.JWT, - // focus-next-line extraLoginOptions: .init(domain:"your-domain", id_token: "your_jwt_token") ) ) +// focus-end ``` -### Email Passwordless + -- To use the `EMAIL_PASSWORDLESS` login, you need to put the email into the `login_hint` field of - the `extraLoginOptions`. + +To use the Email Passwordless login, you need to put the email into the `login_hint` parameter of +the `ExtraLoginOptions`. By default, the login flow will be `code` flow, if you want to use the +`link` flow, you need to put `flow_type` into the `additionalParams` parameter of the +`ExtraLoginOptions`. ```swift -let result = await Web3Auth().login(W3ALoginParams( - Web3AuthProvider.EMAIL_PASSWORDLESS, - // focus-next-line - extraLoginOptions: .init(loginHint: "hello@web3auth.io") +import Web3Auth + +let web3auth = try await Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" )) + + // focus-start +let result = try await web3Auth.login( + W3ALoginParams( + Web3AuthProvider.EMAIL_PASSWORDLESS, + extraLoginOptions: .init(loginHint: "hello@web3auth.io") +)) +// focus-end ``` -### SMS Passwordless + + + To use the SMS Passwordless login, send the phone number as the `login_hint` parameter of the `ExtraLoginOptions`. Please make sure the phone number is in the format of +\{country_code}-\{phone_number}, i.e. (+91-09xx901xx1). + + -## Aggregate Verifier +### Aggregate Verifier Example You can use aggregate verifier to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and Email Passwordless login, or Google and GitHub via Auth0 to access the same address for your user. ```swift +import Web3Auth -let web3Auth = 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 +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 { diff --git a/docs/sdk/pnp/ios/initialize.mdx b/docs/sdk/pnp/ios/initialize.mdx index fb61d3109..5fbbafc34 100644 --- a/docs/sdk/pnp/ios/initialize.mdx +++ b/docs/sdk/pnp/ios/initialize.mdx @@ -10,24 +10,23 @@ import Initialization from "@site/src/common/sdk/pnp/ios/_initialize.mdx"; After installation, the next step to use Web3Auth is to initialize the SDK. However, the initialization can be done in two ways, -- [Creating `Web3Auth.plist`](#creating-web3authplist) -- [Using `Web3Auth` instance](#using-web3auth-instance) +- [Using Plist File](#using-plist-file) +- [Using Constructor](#using-web3auth-instance) Please note that these are the most critical steps where you need to pass on different parameters according to the preference of your project. Additionally, Whitelabeling and Custom Authentication have to be configured within this step, if you wish to customize your Web3Auth Instance. -## Creating `Web3Auth.plist` - -### Setup `Web3Auth.plist` +## Using Plist File -## Using `Web3Auth` instance +## Using Constructor - +If you don't want to create a plist file and want to use optional configuration parameters, you can +construct the Web3Auth instance with -### `W3AInitParams` object +### Parameters The `Web3Auth` constructor takes an object called `W3AInitParams` as input. Below are the available fields of the `W3AInitParams` object. @@ -43,3 +42,7 @@ fields of the `W3AInitParams` object. | `chainNamespace?` | Chain Namespace [`eip155` and `solana`]. It takes `ChainNamespace` as a value. | | `mfaSettings?` | Allows developers to configure the Mfa settings for authentication. It takes `MfaSettings` as a value. | | `sessionTime?` | It allows developers to configure the session management time. Session Time is in seconds, default is 86400 seconds which is 1 day. `sessionTime` can be max 7 days | + +### Initialize Web3Auth Flutter + + diff --git a/docs/sdk/pnp/ios/install.mdx b/docs/sdk/pnp/ios/install.mdx index 5db736542..b2305c42f 100644 --- a/docs/sdk/pnp/ios/install.mdx +++ b/docs/sdk/pnp/ios/install.mdx @@ -16,6 +16,6 @@ import Whitelist from "@site/src/common/sdk/pnp/ios/ios-whitelist.mdx"; -## Configuration +## Configure Redirection diff --git a/docs/sdk/pnp/ios/mfa.mdx b/docs/sdk/pnp/ios/mfa.mdx index 7e6e173e9..0a1148460 100644 --- a/docs/sdk/pnp/ios/mfa.mdx +++ b/docs/sdk/pnp/ios/mfa.mdx @@ -9,23 +9,22 @@ import Tabs from "@theme/Tabs"; import MFAMinimumPlan from "@site/src/common/docs/_mfa_minimum_plan.mdx"; import EnableMFAMethod from "@site/src/common/sdk/pnp/ios/_enable-mfa.mdx"; -The Multi Factor Authentication feature refers to the ability of the user to create a backup share -(recovery phrase). This helps them login into a new device and also to recover their account if they -lose their original device. +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 off-chain 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. -You can set the mfaLevel within the `loginParams` to customize when mfa screen should be shown to -user. It currently accepts 4 values: +## Enable using the MFA Level -- **`default`** - Setting the mfaLevel to default will present the MFA screen to user on every third - login. `mfaLevel = MFALevel.DEFAULT` -- **`optional`** - Setting mfaLevel to optional will present the MFA screen to user on every login - but user will have the option to skip it. `mfaLevel = MFALevel.OPTIONAL` -- **`mandatory`** - Setting mfaLevel to mandatory will make it mandatory for user to setup MFA after - login. `mfaLevel = MFALevel.MANDATORY` -- **`none`** - Setting mfaLevel to none will skip the mfa setup screen totally. - `mfaLevel = MFALevel.NONE` +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. :::caution Note @@ -35,78 +34,62 @@ enabled MFA on other dApps. This is because MFA cannot be turned off once it is ::: -```swift -Web3Auth().login(W3ALoginParams(loginProvider: provider, mfaLevel = MFALevel.MANDATORY)) -``` +### MFA Level Options -```swift title="Usage" -import Foundation -import Web3Auth +| 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 | -class ViewModel: ObservableObject { - var web3Auth: Web3Auth? - @Published var loggedIn: Bool = false - @Published var user: Web3AuthState? - @Published var isLoading = false - @Published var navigationTitle: String = "" - - func setup() async { - guard web3Auth == nil else { return } - await MainActor.run(body: { - isLoading = true - navigationTitle = "Loading" - }) - web3Auth = await Web3Auth(W3AInitParams( - clientId: clientId, network: network - )) - await MainActor.run(body: { - if self.web3Auth?.state != nil { - user = web3Auth?.state - loggedIn = true - } - isLoading = false - navigationTitle = loggedIn ? "UserInfo" : "SignIn" - }) - } +### Usage - func login(provider: Web3AuthProvider) { - Task { - do { - let result = try await web3Auth.login( - W3ALoginParams( - // provider can be .GOOGLE, .FACEBOOK, .APPLE etc - loginProvider: provider, - // focus-next-line - mfaLevel: MFALevel.MANDATORY - )) - await MainActor.run(body: { - user = result - loggedIn = true - }) - - } catch { - print("Error") - } - } - } -} +```swift +import Web3Auth +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" +)) + +let result = try await web3Auth.login( + W3ALoginParams( + loginProvider: .GOOGLE, + // focus-next-line + mfaLevel: .MANDATORY + ) +) ``` -## Using the `mfaSettings` to configure MFA Order - -:::note +## Explicitly enable MFA -This is a paid feature and the minimum [pricing plan](https://web3auth.io/pricing.html) to use this -SDK in a production environment is the **SCALE Plan**. You can use this feature in `sapphire_devnet` -for free. + -::: +## Configure MFA Settings You can configure the order of MFA or enable/disable MFA type by passing the `mfaSettings` object in `Web3AuthOptions`. -`MfaSettings` +:::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. + +::: + +### Parameters - MfaSettings + +`MfaSettings` allows you to set the type of the MFA. -`MfaSettings` +### Parameters - MfaSetting + +`MfaSetting` allows you to setup MFA setting for a particular MFA type. - -```swift -let result = try await Web3Auth( - W3AInitParams( - clientId: "YOUR_CLIENT_ID", - network: .sapphire_devnet, - loginConfig: [ - TypeOfLogin.google.rawValue: .init( - // Get it from Web3Auth Dashboard - verifier: "YOUR_VERIFIER_ID", - typeOfLogin: .google, - name: "Web3Auth-Aggregate-Verifier-Google-Example", - clientId: "YOUR_GOOGLE_CLIENT_ID", - // Get it from Web3Auth Dashboard - verifierSubIdentifier: "YOUR_VERIFIER_SUB_ID" - ) - ], - 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"]), - 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) - ) - )).login( - W3ALoginParams( - loginProvider: .GOOGLE, - dappShare: nil, - 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: nil, domain: nil, client_id: nil, redirect_uri: nil, leeway: nil, verifierIdField: nil, isVerifierIdCaseSensitive: nil, additionalParams: nil), - mfaLevel: .DEFAULT, - curve: .SECP256K1 - )) -``` +### Usage -:::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. - -::: - -## Using `enableMFA` method to trigger MFA setup flow for users +```swift +import Web3Auth - +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + 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) + ) + ) + // focus-end +)) + +let result = try await web3Auth.login( + W3ALoginParams( + loginProvider: .GOOGLE, + // focus-next-line + mfaLevel: .MANDATORY + ) +) +``` diff --git a/docs/sdk/pnp/ios/usage.mdx b/docs/sdk/pnp/ios/usage.mdx index 5188351a5..222e937ba 100644 --- a/docs/sdk/pnp/ios/usage.mdx +++ b/docs/sdk/pnp/ios/usage.mdx @@ -13,16 +13,14 @@ import EnableMFAMethod from "@site/src/common/sdk/pnp/ios/_enable-mfa.mdx"; ## Logging in a User -### `login()` +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, etc., and +do whitelabel login. -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, etc., and do whitelabel login. `Web3Auth.login()` takes in -`W3ALoginParams` as a required input. +### Parameters -#### Arguments - -`W3ALoginParams` +The login method accepts `W3ALoginParams` as a required parameter. - -### `getPrivkey()` - -Use getPrivkey() to get the private key of the user. The method returns an EVM compatible private -key which can be used to sign transactions on EVM compatible chains. - -### `getEd25519PrivKey()` - -Use getEd25519PrivKey() to get the Ed25519 private key of the user. This private key can be used to -sign transactions on Solana. +### Usage -### `getUserInfo()` +```swift +import Web3Auth -Use getUserInfo() to get the user info of the user. +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" +)) -#### UserInfo Response +// focus-next-line +let result = try await web3Auth.login(W3ALoginParams(loginProvider: .GOOGLE)) +``` - +### Examples -```swift title="Usage" -func login(provider: Web3AuthProvider) { - Task { - do { - let result = try await Web3Auth().login(W3ALoginParams(loginProvider: provider)) - // Perform action upon success - } catch { - print("Error") - } - } -} +```swift +import Web3Auth + +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" +)) + // focus-next-line -login(provider: .GOOGLE) +let result = try await web3Auth.login(W3ALoginParams(loginProvider: .GOOGLE)) ``` -```swift title="Usage" -func login(provider: Web3AuthProvider) { - Task { - do { - let result = try await Web3Auth().login(W3ALoginParams(loginProvider: provider)) - // Perform action upon success - } catch { - print("Error") - } - } -} +```swift +import Web3Auth + +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" +)) + // focus-next-line -login(provider: .FACEBOOK) +let result = try await web3Auth.login(W3ALoginParams(loginProvider: .FACEBOOK)) ``` -```swift title="Usage" -func login(provider: Web3AuthProvider) { - Task { - do { - let result = try await Web3Auth().login(W3ALoginParams(loginProvider: provider)) - // Perform action upon success - } catch { - print("Error") - } - } -} +```swift +import Web3Auth + +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" +)) + // focus-next-line -login(provider: .DISCORD) +let result = try await web3Auth.login(W3ALoginParams(loginProvider: .DISCORD)) ``` -```swift title="Usage" -func login(provider: Web3AuthProvider) { - Task { - do { - let result = try await Web3Auth().login(W3ALoginParams(loginProvider: provider)) - // Perform action upon success - } catch { - print("Error") - } - } -} +```swift +import Web3Auth + +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" +)) + // focus-next-line -login(provider: .TWITCH) +let result = try await web3Auth.login(W3ALoginParams(loginProvider: .TWITCH)) ``` -```swift title="Usage" -func login(provider: Web3AuthProvider) { - Task { - do { - let result = try await Web3Auth().login( - W3ALoginParams( - loginProvider: provider, - extraLoginOptions: .init(loginHint: "hello@web3auth.io") - )) - // Perform action upon success - } catch { - print("Error") - } - } -} -// focus-next-line -login(provider: .EMAIL_PASSWORDLESS) -``` +```swift +import Web3Auth + +let web3auth = Web3Auth(W3AInitParams( clientId: "YOUR_WEB3AUTH_CLIENT_ID", 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 + +```` @@ -228,132 +208,114 @@ login(provider: .EMAIL_PASSWORDLESS) -```swift title="Usage" -do { - let result = try await Web3Auth().login(W3ALoginParams(loginProvider: .Farcaster)) - // Perform action upon success -} catch { - print("Error") -} -``` +```swift +import Web3Auth + +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" +)) + +// focus-next-line +let result = try await web3Auth.login(W3ALoginParams(loginProvider: .FARCASTER)) +```` + -```swift title="Usage" -func login(provider: Web3AuthProvider) { - Task { - do { - let result = try await Web3Auth().login(W3ALoginParams( - selectedLoginProvider, - // focus-next-line - extraLoginOptions: .init(domain:"your-domain", id_token: "your_jwt_token") - )) - - // Perform action upon success - } catch { - print("Error") - } - } -} -// focus-next-line -login(provider: .JWT) +```swift +import Web3Auth + +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + 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 ``` -## Session Management +## Retrieve Private Key -The Session Management feature allows you to check the existing sessions with Web3Auth. The -`Web3AuthState` will allow users to remain authenticated with Web3Auth for 1 day by default, or a -maximum of 7 days, or until the user logout or session data is cleared. +Web3Auth supports two widely used cryptographic curves, Secp256k1 and Ed25519, making it +chain-agnostic and compatible with multiple blockchain networks. +[Learn more about how to connect different blockchains](/docs/connect-blockchain). + +### Secp256k1 Private Key -The `Web3Auth` initialization accepts a `sessionTime` parameter. +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. ```swift -let sessionTime = 86400 // 1 day +let privateKey = web3Auth.getPrivKey(); ``` -```swift title="Usage" -import Foundation -// IMP START - Quick Start -import Web3Auth -// IMP END - Quick Start - -class ViewModel: ObservableObject { - var web3Auth: Web3Auth? - @Published var loggedIn: Bool = false - @Published var user: Web3AuthState? - @Published var isLoading = false - @Published var navigationTitle: String = "" - - func setup() async { - guard web3Auth == nil else { return } - await MainActor.run(body: { - isLoading = true - navigationTitle = "Loading" - }) - - - web3Auth = await Web3Auth(W3AInitParams( - clientId: "", - network: .sapphire_mainnet, - // focus-next-line - sessionTime: 86400, // 1 day - - )) - - await MainActor.run(body: { - if self.web3Auth?.state != nil { - // focus-next-line - user = web3Auth?.state - loggedIn = true - } - isLoading = false - navigationTitle = loggedIn ? "UserInfo" : "SignIn" - }) - } +### Ed25519 Private Key - func login(provider: Web3AuthProvider) { - Task { - do { +To retrieve the secp256k1 private key of the user., use `getEd25519PrivKey` method. This private key +can be used to sign transactions on Solana. - let result = try await web3Auth?.login( - W3ALoginParams(loginProvider: provider) - ) +```swift +let privateKey = web3Auth.getEd25519PrivKey(); +``` - await MainActor.run(body: { - user = result - loggedIn = true - }) +## Retrive User Information - } catch { - print("Error") - } - } - } +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. - func logout() throws { - Task { - try await web3Auth?.logout() - await MainActor.run(body: { - loggedIn = false - }) - } - } +### Usage +```swift +let web3AuthUserInfo = web3Auth.getUserInfo(); ``` -## Logging out a user +### UserInfo Response + + -### `Web3Auth().logout()` +## Session Management -This method will logout the user and remove the session id from the device. The user will need to -login again to use the dApp next time the dApp is opened. +The Session Management feature allows you to check the existing sessions with Web3Auth. The +`Web3AuthState` will allow users to remain authenticated with Web3Auth for 1 day by default, or a +maximum of 7 days, or until the user logout or session data is cleared. + +The `W3AInitParams` initialization accepts a `sessionTime` parameter. + +### Usage ```swift -await Web3Auth().logout() +import Web3Auth + +let web3auth = Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth", + // focus-next-line + sessionTime: 86400 // 1 Day +)) +``` + +## Logging out a user + +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. + +```swift +try await web3auth.logout() ``` ## Enable MFA for a user @@ -374,9 +336,7 @@ environment is the **Scale Plan**. ::: -### Arguments - -`ChainConfig` +### Parameters -```swift title="Usage" +```swift do { // focus-next-line - let isMFAEnabled = try await self.web3Auth.enableMFA() + let isMFAEnabled = try await web3Auth.enableMFA() } catch { - print(error.localizedDescription) - // Handle Error + print(error.localizedDescription) + // Handle Error } ``` -```swift title="Usage" +```swift do { - let loginParams = W3ALoginParams( - .JWT, - extraLoginOptions: .init(id_token: "your_jwt_token") - ) + let loginParams = W3ALoginParams( + .JWT, + extraLoginOptions: .init(id_token: "your_jwt_token") + ) // focus-next-line - let isMFAEnabled = try await self.web3Auth.enableMFA(loginParams) + +let isMFAEnabled = try await web3Auth.enableMFA(loginParams) } catch { print(error.localizedDescription) // Handle Error } ``` - ``` diff --git a/src/common/sdk/pnp/ios/_initialize.mdx b/src/common/sdk/pnp/ios/_initialize.mdx index 8f6d75944..cd81235e9 100644 --- a/src/common/sdk/pnp/ios/_initialize.mdx +++ b/src/common/sdk/pnp/ios/_initialize.mdx @@ -1,6 +1,3 @@ -If you don't want to create a plist file and want to use optional configuration parameters, you can -construct the Web3Auth instance with - ```swift import Web3Auth @@ -10,6 +7,3 @@ let web3auth = Web3Auth(W3AInitParams( redirectUrl: "bundleId://auth" )) ``` - -After creating a `Web3Auth` instance using one of the above methods, you can use the instance to -call various methods. diff --git a/src/common/sdk/pnp/ios/_sms_passwordless.mdx b/src/common/sdk/pnp/ios/_sms_passwordless.mdx index f0c0633e5..269ca3130 100644 --- a/src/common/sdk/pnp/ios/_sms_passwordless.mdx +++ b/src/common/sdk/pnp/ios/_sms_passwordless.mdx @@ -1,9 +1,17 @@ -```swift title="Usage" -let result = await Web3Auth().login(W3ALoginParams( +```swift +import Web3Auth + +let web3auth = try await Web3Auth(W3AInitParams( + clientId: "YOUR_WEB3AUTH_CLIENT_ID", + network: .sapphire_mainnet, + redirectUrl: "bundleId://auth" +)) + + // focus-start +let result = try await web3Auth.login(W3ALoginParams( Web3AuthProvider.SMS_PASSWORDLESS, - // focus-start // The phone number should be in format of +{country_code}-{phone_number} extraLoginOptions: .init(loginHint: "+91-9911223344") - // focus-end )) + // focus-end ``` From 34c27a0b41935fc3d802b57250264c6b7032323a Mon Sep 17 00:00:00 2001 From: AyushBherwani1998 Date: Thu, 3 Oct 2024 12:09:33 +0530 Subject: [PATCH 02/37] revamp android docs --- .../sdk/pnp/android/custom-authentication.mdx | 301 ++++++------ docs/sdk/pnp/android/initialize.mdx | 116 +---- docs/sdk/pnp/android/install.mdx | 17 +- docs/sdk/pnp/android/mfa.mdx | 195 +++----- docs/sdk/pnp/android/usage.mdx | 453 +++++++----------- src/common/sdk/pnp/android/_initialize.mdx | 23 +- src/common/sdk/pnp/android/_installation.mdx | 10 +- src/common/sdk/pnp/android/_logout.mdx | 13 +- .../sdk/pnp/android/_set-result-url.mdx | 4 +- .../sdk/pnp/android/_sms_passwordless.mdx | 19 +- 10 files changed, 471 insertions(+), 680 deletions(-) diff --git a/docs/sdk/pnp/android/custom-authentication.mdx b/docs/sdk/pnp/android/custom-authentication.mdx index a42bc03c3..b55251879 100644 --- a/docs/sdk/pnp/android/custom-authentication.mdx +++ b/docs/sdk/pnp/android/custom-authentication.mdx @@ -9,40 +9,30 @@ import Tabs from "@theme/Tabs"; import GrowthPlanNote from "@site/src/common/docs/_growth_plan_note.mdx"; import SMSPasswordless from "@site/src/common/sdk/pnp/android/_sms_passwordless.mdx"; +## Configuration + To use custom authentication (Using Social providers or Login providers like Auth0, AWS Cognito, -Firebase etc. or even your own custom JWT login) you can add the configuration to the `loginConfig` -parameter of the `Web3AuthOptions` object during the initialization. +Firebase etc. or even your own custom JWT login) you can add the configuration using `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 `LoginConfigItem` instance. -First, configure your own verifier in the Web3Auth Dashboard to use custom authentication. - - +To use custom authentication, first you'll need to configure your own verifier in the Web3Auth +Dashboard in "Custom Authentication" section. +[Learn how to create a custom verifier](/auth-provider-setup/verifiers). :::tip Create Custom Verifier -Check out how to create a **[Custom Verifier](/auth-provider-setup/verifiers)** on the Web3Auth -Dashboard. - -::: - -:::info using dapp share - -- dApp Share is only returned for the Custom verifiers. -- Also, 2FA should be enabled for the account using it. Use `mfaLevel = MFALevel.MANDATORY` in the - `LoginParams` during login. See **[MFA](/sdk/pnp/android/mfa)** for more details. +Learn how to create a [Custom Verifier](/auth-provider-setup/verifiers) on the Web3Auth Dashboard. ::: -Then, you should specify the details of your verifier in the `LoginConfigItem` struct, the details -of this struct are as follows: - -## `LoginConfigItem` + -### Arguments +### Parameters -`LoginConfigItem` +After creating the verifier, you can use the following parameters in the `LoginConfigItem`. - - -### `typeOfLogin` - -```kotlin enum class TypeOfLogin { @SerializedName("google") GOOGLE, @@ -135,6 +117,11 @@ enum class TypeOfLogin { } ``` + + + +### Usage + -```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("google" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard + verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = TypeOfLogin.GOOGLE, - clientId = getString(R.string.google_client_id) // google's client id + clientId = getString(R.string.google_client_id) // Google's client id )) // focus-end ) ) + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.login( + LoginParams(Provider.GOOGLE) +) +// focus-end ``` +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions -```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( - context = this, - clientId = getString (R.string.web3auth_project_id), - network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object - // focus-start - loginConfig = hashMapOf("facebook" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard - typeOfLogin = TypeOfLogin.FACEBOOK, - clientId = getString(R.string.facebook_client_id) // facebook's client id - )) - // focus-end - ) -) -``` +val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // +Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, redirectUrl = +Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("facebook" to +LoginConfigItem( verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = +TypeOfLogin.FACEBOOK, clientId = getString(R.string.facebook_client_id) // Facebook's client id )) +// focus-end ) ) + +// focus-start val loginCompletableFuture: CompletableFuture = web3Auth.login( +LoginParams(Provider.Facebook) ) // focus-end +```` +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions -```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard + verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = TypeOfLogin.JWT, - clientId = getString (R.string.auth0_project_id) // auth0's client id + clientId = getString (R.string.auth0_project_id) // Auth0's client id )) // focus-end ) ) -``` + +// focus-start +val loginCompletableFuture: CompletableFuture = web3Auth.login( + LoginParams(Provider.JWT) +) +// focus-end +```` +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions -```kotlin title="Usage" -web3Auth = Web3Auth ( - Web3AuthOptions ( - context = this, - clientId = getString (R.string.web3auth_project_id), - network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object - // focus-start - loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard - typeOfLogin = TypeOfLogin.JWT, - )) - // focus-end - ) -) -``` +val web3Auth = Web3Auth( Web3AuthOptions( context = this, clientId = "YOUR_WEB3AUTH_CLIENT_ID", // +Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, redirectUrl = +Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("jwt" to +LoginConfigItem( verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = +TypeOfLogin.JWT, )) // focus-end ) ) - +// focus-start val loginCompletableFuture: CompletableFuture = web3Auth.login( +LoginParams(Provider.JWT) ) // focus-end +```` + -## `ExtraLoginOptions` for special login methods +## Configure Extra Login Options Additional to the `LoginConfig` you can pass extra options to the `login` function to configure the login flow for cases requiring additional info for enabling login. The `ExtraLoginOptions` accepts -the following parameters: +the following parameters. + +### Parameters - -## Single Verifier +### Single Verifier Usage -### Using Auth0 Login + + + Auth0 has a special login flow, called the SPA flow. This flow requires a `client_id` and `domain` to be passed, and Web3Auth will get the JWT `id_token` from Auth0 directly. You can pass these configurations in the `ExtraLoginOptions` object in the login function. -```tsx -web3Auth = Web3Auth ( - Web3AuthOptions ( +```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard for auth0 configuration + verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = TypeOfLogin.JWT, - clientId = getString (R.string.auth0_client_id) // auth0's client id, get it from auth0 dashboard + clientId = getString (R.string.auth0_project_id) // Auth0's client id )) // focus-end ) ) -val loginCompletableFuture: CompletableFuture = - web3Auth.login(LoginParams(Provider.JWT, - // focus-start - extraLoginOptions = ExtraLoginOptions( - domain: "https://username.us.auth0.com", // domain of your auth0 app - verifierIdField: "sub", // The field in jwt token which maps to verifier id. - ) - // focus-end - )) +val loginCompletableFuture: CompletableFuture = web3Auth.login( + LoginParams( + Provider.JWT, + // focus-start + extraLoginOptions = ExtraLoginOptions( + domain: "https://username.us.auth0.com", // Domain of your Auth0 app + verifierIdField: "sub", // The field in jwt token which maps to verifier id. + ) + // focus-end + ) +) ``` -### Custom JWT 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. ```kotlin -web3Auth = Web3Auth ( - Web3AuthOptions ( +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard network = Network.MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf("jwt" to LoginConfigItem( - verifier = "verifier-name", // get it from web3auth dashboard for auth0 configuration + verifier = "verifier-name", // Get it from Web3Auth dashboard typeOfLogin = TypeOfLogin.JWT, )) // focus-end ) ) -val loginCompletableFuture: CompletableFuture = - web3Auth.login(LoginParams(Provider.JWT, - // focus-start - extraLoginOptions = ExtraLoginOptions( - id_token: "Your JWT id token", - ) - // focus-end - )) +val loginCompletableFuture: CompletableFuture = web3Auth.login( + LoginParams( + Provider.JWT, + // focus-start + extraLoginOptions = ExtraLoginOptions( + id_token: "Your JWT id token", + ) + // focus-end + ) +) ``` -### Email Passwordless + -To use the `EMAIL_PASSWORDLESS` login, you need to put the email into the `login_hint` field of the -`extraLoginOptions`. + +To use the Email Passwordless login, you need to put the email into the `login_hint` parameter of +the `ExtraLoginOptions`. By default, the login flow will be `code` flow, if you want to use the +`link` flow, you need to put `flow_type` into the `additionalParams` parameter of the +`ExtraLoginOptions`. ```kotlin +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( + context = this, + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + network = Network.MAINNET, + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), + ) +) + val loginCompletableFuture: CompletableFuture = web3Auth.login( LoginParams( Provider.EMAIL_PASSWORDLESS, @@ -398,28 +424,33 @@ val loginCompletableFuture: CompletableFuture = web3Auth.login ) ``` -### SMS Passwordless + + To use the SMS Passwordless login, send the phone number as the `login_hint` parameter of the `ExtraLoginOptions`. Please make sure the phone number is in the format of +\{country_code}-\{phone_number}, i.e. (+91-09xx901xx1). + + -## Aggregate Verifier +### Aggregate Verifier Usage You can use aggregate verifier to combine multiple login methods to get the same address for the users regardless of their login providers. For example, combining a Google and Email Passwordless login, or Google and GitHub via Auth0 to access the same address for your user. ```kotlin -web3Auth = Web3Auth ( - Web3AuthOptions ( +import com.web3auth.core.Web3Auth +import com.web3auth.core.types.Web3AuthOptions + +val web3Auth = Web3Auth( + Web3AuthOptions( context = this, - clientId = getString (R.string.web3auth_project_id), - network = Network.SAPPHIRE_MAINNET, - redirectUrl = Uri.parse ("{YOUR_APP_PACKAGE_NAME}://auth"), - // Optional loginConfig object + clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard + network = Network.MAINNET, + redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth"), // focus-start loginConfig = hashMapOf( "google" to LoginConfigItem( @@ -441,20 +472,20 @@ web3Auth = Web3Auth ( ) ) -// Google Login // focus-start +// Google Login web3Auth.login(LoginParams(Provider.GOOGLE)) // focus-end -// Auth0 Login // focus-start +// Auth0 Login web3Auth.login(LoginParams( Provider.JWT, extraLoginOptions = ExtraLoginOptions( domain = "https://web3auth.au.auth0.com", verifierIdField = "email", - isVerifierIdCaseSensitive = false) + isVerifierIdCaseSensitive = false ) -) +)) // focus-end ``` diff --git a/docs/sdk/pnp/android/initialize.mdx b/docs/sdk/pnp/android/initialize.mdx index f9cf64645..cf68f3d69 100644 --- a/docs/sdk/pnp/android/initialize.mdx +++ b/docs/sdk/pnp/android/initialize.mdx @@ -17,21 +17,13 @@ However, Initialization is a two-step process: 1. [Creating a Web3Auth Instance](#create-web3auth-instance) 2. [Setting a Result URL](#set-result-url) +## Create Web3Auth Instance + Please note that these are the most critical steps where you must pass on different parameters according to the preference of your project. Additionally, You must configure Whitelabeling and Custom Authentication within this step if you wish to customize your Web3Auth Instance. -## Create Web3Auth Instance - -In your activity, create a `Web3Auth` instance with your Web3Auth project's configurations. - -```kotlin -web3Auth = Web3Auth(Web3AuthOptions) -``` - -### Arguments - -#### `Web3AuthOptions` +### Parameters The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. @@ -80,112 +72,12 @@ data class Web3AuthOptions( ``` - -### Instance +### Initialize Web3Auth -### Session Management - -The Session Management feature allows you to check the existing sessions with Web3Auth. The -`sessionResponse()` will allow users to remain authenticated with Web3Auth for up to 1 day default, -or a maximum of 7 days, or until they logout or session data is cleared. To change the default -session time, you can pass `sessionTime` in `Web3AuthOptions`. - -```kotlin -// Call sessionResponse() in onCreate() to check for any existing session. -val sessionResponse: CompletableFuture = web3Auth.initialize() -sessionResponse.whenComplete { _, error -> - if (error == null) { - Log.d("MainActivity_Web3Auth", "User already logged in") - // Add your logic - } else { - Log.d("MainActivity_Web3Auth", error.message ?: "Something went wrong") - // Ideally, you should initiate the login function here. - } -} -``` - -:::note - -If you're looking for `refreshToken` to maintain the JWT session, use this method instead to extend -the session. - -::: - ## Set Result URL - -## Example - -```kotlin -class MainActivity : AppCompatActivity() { - // ... - private lateinit var web3Auth: Web3Auth - - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - setContentView(R.layout.activity_main) - - web3Auth = Web3Auth( - Web3AuthOptions(context = this, - clientId = getString(R.string.web3auth_project_id), - network = Network.MAINNET, - redirectUrl = Uri.parse("{YOUR_APP_PACKAGE_NAME}://auth") - ) - ) - - // Handle user signing in when app is not alive - web3Auth.setResultUrl(intent?.data) - - // Calls sessionResponse() to check for any existing session. - val sessionResponse: CompletableFuture = web3Auth.initialize() - sessionResponse.whenComplete { _, error -> - if (error == null) { - Log.d("MainActivity_Web3Auth", "User already logged in") - // Add your logic - } else { - Log.d("MainActivity_Web3Auth", error.message ?: "Something went wrong") - // Ideally, you should initiate the login function here. - } - } - - // Setup UI and event handlers - val signInButton = findViewById