From 11e778f691cca586c45c60d09554cdf96e7bb6b3 Mon Sep 17 00:00:00 2001 From: AyushBherwani1998 Date: Fri, 8 Nov 2024 08:10:08 +0530 Subject: [PATCH] update documentation --- .../sfa-android-v1.2.0-to-v2.0.0.mdx | 145 ++++++++++++++++++ docs/sdk/sfa/sfa-android/initialize.mdx | 33 ++-- docs/sdk/sfa/sfa-android/usage.mdx | 81 ++++++++-- docs/sdk/sfa/sfa-ios/initialize.mdx | 2 +- sidebars.ts | 1 + .../android/_sfa-android-initialization.mdx | 15 +- .../sdk/sfa/android/_sfa-android-install.mdx | 2 +- .../_sfa-android-session-management.mdx | 19 ++- src/common/versions.ts | 2 +- 9 files changed, 263 insertions(+), 37 deletions(-) create mode 100644 docs/migration-guides/sfa-android-v1.2.0-to-v2.0.0.mdx diff --git a/docs/migration-guides/sfa-android-v1.2.0-to-v2.0.0.mdx b/docs/migration-guides/sfa-android-v1.2.0-to-v2.0.0.mdx new file mode 100644 index 000000000..d26748b09 --- /dev/null +++ b/docs/migration-guides/sfa-android-v1.2.0-to-v2.0.0.mdx @@ -0,0 +1,145 @@ +--- +title: SFA Android SDK - v1.x.x to v2.0.0 +description: "SFA Android SDK - v1.x.x to v2.0.0 | Documentation - Web3Auth" +sidebar_label: v1.x.x to v2.0.0 +--- + +This migration guide provides steps for upgrading from version v1.x.x to v2.0.0 of the SFA Android +SDK. The guide outlines significant changes and enhancements. + +## Breaking Changes + +### SFAParams Changes + +In v2, we try to improve the developer experience by renaming the `SFAParams` to `Web3AuthOptions`. +It has been renamed to align with naming conventions across Web3Auth SDKs. Along with this, there +has been change in the positional parameter. + +[Checkout Web3AuthOptions for available parameters](/docs/sdk/core-kit/sfa-android/initialize#parameters). + +```kotlin +// remove-start +val singleFactorAuthArgs = SFAParams( + Web3AuthNetwork.MAINNET, + "YOUR_WEB3AUTH_CLIENT_ID" +) +// remove-end + +// add-start +val web3AuthOptions = Web3AuthOptions( + "YOUR_WEB3AUTH_CLIENT_ID", + Web3AuthNetwork.MAINNET +) +// add-end + +val singleFactoreAuth = SingleFactorAuth( + // remove-next-line + singleFactorAuthArgs, + // add-next-line + web3AuthOptions, + this.applicationContext +) +``` + +### SFAKey is replaced with SessionData + +In v2, we removed the `SFAKey` and added the `SessionData` object to return the relveant session +information like private key, address, user information, and signatures. + +```kotlin +// remove-next-line +val sfaKey: SFAKey = singleFactoreAuth.connect(loginParams: loginParams) +// add-next-line +val sessionData: SessionData = singleFactoreAuth.connect(loginParams: loginParams) +``` + +### initialize method changes + +Starting v2, the `initialize` method will return `SessionData` instead of `SFAKey`. The method will +return `null` if the user does not have an existing session, and in case of an invalid existing +session, it will throw an error. + +```kotlin +// remove-start +val keyCF = singleFactorAuth.initialize(this.applicationContext) +keyCF.whenComplete { key, error -> + if (error != null) { + // No existing session + } else { + // Existing session + } +} +// remove-end + +// add-start +val sessionDataCF = singleFactorAuth.initialize(this.applicationContext) + +sessionDataCF.whenComplete {sessionData, error -> + if(error != null) { + // Session is no longer valid, or something went wrong + // Initiate the login flow again + } else if(sessionData == null) { + // No active session found + } else { + // Session is present + // You can use the sessionData to get the public address, private key, + // userInfo, and signatures. + Log.i("Public address", sessionData.publicAddress) + } +} +// add-end +``` + +### isSessionIdExists is replaced with isConnected + +The `isSessionIdExists` method is replaced with the `isConnected` method to check whether the user +is logged in Web3Auth or not. + +```kotlin +// remove-next-line +val isSessionIdExists = singleFactoreAuth.isSessionIdExists() +// add-next-line +val isConnected = singleFactoreAuth.isConnected() +``` + +## Additional Features + +Apart from the breaking changes, we have added couple of new functions in v2 to improve the +developer experience. + +### logout Method + +The `logout` method is added to the SDK to log out the user and clear the session data. Please note, +that this method only logout the user and invalides the Web3Auth session, and not the OAuth provider +session. + +```kotlin +singleFactoreAuth.logout() +``` + +### getSessionData Method + +The `getSessionData` method is added to the SDK to get the session data. You can use this method to +retrive the session data for an existing session. The method will return `null` if the user does not +have an existing session. + +#### Usage + +```kotlin +val sessionData: SessionData = singleFactoreAuth.getSessionData() + +if (sessionData == null) { + // User does not have an existing session +} +``` + +#### SessionData + +The `SessionData` has the following properties to retrive the relevant session information. + +| Name | Description | +| --------------- | ------------------------------------------------------------------------- | +| `privateKey` | Retrieves the user's private key. | +| `publicAddress` | Retrieves the user's public address. | +| `userInfo?` | Retrieves the user's information like email, name, verifier id, and more. | +| `signatures?` | Retrieves the node's signatures that are returned for request. | diff --git a/docs/sdk/sfa/sfa-android/initialize.mdx b/docs/sdk/sfa/sfa-android/initialize.mdx index 51dca3c66..7c389c15c 100644 --- a/docs/sdk/sfa/sfa-android/initialize.mdx +++ b/docs/sdk/sfa/sfa-android/initialize.mdx @@ -7,24 +7,35 @@ description: "Web3Auth Single Factor Auth Android SDK - Initialize | Documentati import TabItem from "@theme/TabItem"; import Tabs from "@theme/Tabs"; -import Initialization from "@site/src/common/sdk/sfa/android/_sfa-android-initialization.mdx"; +import Initialization from "@site/src/common/sdk/core-kit/sfa/android/_sfa-android-initialization.mdx"; +import SessionManagement from "@site/src/common/sdk/core-kit/sfa/android/_sfa-android-session-management.mdx"; Once you have installed the Web3Auth SDK, the next crucial step is to initialize it. This step requires passing various parameters that align with your project preferences. It's important to note that the initialization process is critical to the successful use of Web3Auth. -### Parameters +## Parameters -In your activity, create a `SingleFactorAuth` instance with `SFAParams`. You can define the Web3Auth -network, client id, and other parameters during initialization. +In your activity, create a `SingleFactorAuth` instance with `Web3AuthOptions`. You can define the +Web3Auth network, client id, and other parameters during initialization. -| Parameter | Description | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `network` | The Web3auth network is to be used by the SDK. Supported values are `Web3AuthNetwork.SAPPHIRE_MAINNET`, `Web3AuthNetwork.SAPPHIRE_DEVNET` ,`Web3AuthNetwork.MAINNET`, `Web3AuthNetwork.TESTNET`, `Web3AuthNetwork.CYAN`, and `Web3AuthNetwork.AQUA` | -| `clientId` | The clientId for your Web3Auth project. You can get it from [Web3Auth dashboard](https://dashboard.web3auth.io/). | -| `sessionTime` | Specifies the session duration in seconds. By default, the value is set to 86400 seconds (1 day), with a maximum session duration of up to 7 days. | -| `serverTimeOffset` | Specify a custom server time offset. The default value is 0. | +| Parameter | Description | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `network` | The Web3auth network is to be used by the SDK. Supported values are `Web3AuthNetwork.SAPPHIRE_MAINNET`, `Web3AuthNetwork.SAPPHIRE_DEVNET` ,`Web3AuthNetwork.MAINNET`, `Web3AuthNetwork.TESTNET`, `Web3AuthNetwork.CYAN`, and `Web3AuthNetwork.AQUA` | +| `clientId` | The clientId for your Web3Auth project. You can get it from [Web3Auth dashboard](https://dashboard.web3auth.io/). | +| `sessionTime` | Specifies the session duration in seconds. By default, the value is set to 86400 seconds (1 day), with a maximum session duration of up to 7 days. | +| `serverTimeOffset` | Specify a custom server time offset. The default value is 0. | +| `storageServerUrl?` | Specifies the storage server URL. The default value is `https://session.web3auth.io`. | -### Initialize SingleFactorAuth +## Create Instance + +## Initialize + +To initialize the SDK, you can use the `initialize` method. We have included Session Management in +this SDK, so you can use the method to get the `SessionData` without re-logging in the user. If a +user has an active session, it will return the `SessionData`, otherwise, it will throw an error for +inactive session. + + diff --git a/docs/sdk/sfa/sfa-android/usage.mdx b/docs/sdk/sfa/sfa-android/usage.mdx index edf64b4dd..1bdee879b 100644 --- a/docs/sdk/sfa/sfa-android/usage.mdx +++ b/docs/sdk/sfa/sfa-android/usage.mdx @@ -7,8 +7,6 @@ description: "Web3Auth Single Factor Auth Android SDK - Usage | Documentation - import TabItem from "@theme/TabItem"; import Tabs from "@theme/Tabs"; -import SessionManagement from "@site/src/common/sdk/sfa/android/_sfa-android-session-management.mdx"; - After successfully installing and initializing SingleFactorAuth, you can use it to authenticate your users and obtain their private and public keys. @@ -22,13 +20,16 @@ you'll see an Error message. The SingleFactorAuth instance natively provides the following methods: - [connect](#login-user) - Use to login user and retrive private key pair. -- [initialize](#session-management) - This method helps to achieve session management. It - authenticates user if the session is present, avoiding re-logging. +- [logout](#logout-user) - Use to logout existing user. +- [connected](#check-users-logged-in-status) - Use to check whether the user is logged in or not. +- [getSessionData](#get-session-data) - This method helps to get the session data for valid session. ## Login User -To obtain a user's private key using the Web3Auth SFA Android SDK, you can call the `connect` -method. The method accepts `LoginParams`, and returns `SFAKey`. +To obtain a user's private key, and relevant session data using the Web3Auth SFA Android SDK, you +can call the `connect` method. The method accepts `LoginParams`, and returns `SessionData`. + +Please checkout the [SessionData](#response) for more details. ### Parameters @@ -92,27 +93,75 @@ class TorusSubVerifierInfo( ### Usage ```kotlin +import com.web3auth.singlefactorauth.types.SessionData +import com.web3auth.singlefactorauth.types.LoginParams +import android.content.Context + val loginParams = LoginParams( "YOUR_VERIFIER_NAME", "YOUR_VERIFIER_ID_VALUE", "YOUR_ID_TOKEN" ); + +val context: Context = "YOUR_APPLICATION_CONTEXT" + // focus-next-line -val sfaKey = singleFactorAuth.connect(loginParams); +val sessionData: SessionData = singleFactorAuth.connect(loginParams, context); +``` + +## Logout User + +To logout the current user, you can use the `logout` method. Please note, the method will not logout +the user from the authentication provider, it'll only logout and invalidate the Web3Auth session. + +### Usage + +```kotlin +import android.content.Context +val context: Context = "YOUR_APPLICATION_CONTEXT" + +singleFactorAuth.logout() ``` -## Session Management +## Check User's Logged In Status -We have included Session Management in this SDK, so calling the initialize function to get the -SFAKey value without re-logging in the user if a user has an active session will return the SFAKey, -otherwise, it will throw an error. +You can use the `connected` method to check whether the user is logged in Web3Auth or not. Please +note, you should call this method after the `initialize` method if you want to check the user's +connection status for an existing session. -### Parameter +### Usage + +```kotlin +val isConnected = singleFactorAuth.connected() +``` -| Parameter | Description | -| --------- | ---------------------------------- | -| `ctx` | Takes in android activity context. | +## Get Session Data + +We have included Session Management in this SDK, so calling the `getSessionData` will retrive the +user's `SessionData` without re-logging in the user if a user has an active session. Otherwise, it +will return `null`. + +Please note, you should use this method after the `initialize` method. ### Usage - +```kotlin +val sessionData = singleFactorAuth.getSessionData() + +if(sessionData != null) { + // User is logged in +} else { + // User is not logged in +} +``` + +### Response + +The `SessionData` has the following properties to retrive the relevant session information. + +| Name | Description | +| --------------- | ------------------------------------------------------------------------- | +| `privateKey` | Retrieves the user's private key. | +| `publicAddress` | Retrieves the user's public address. | +| `userInfo?` | Retrieves the user's information like email, name, verifier id, and more. | +| `signatures?` | Retrieves the node's signatures that are returned for request. | diff --git a/docs/sdk/sfa/sfa-ios/initialize.mdx b/docs/sdk/sfa/sfa-ios/initialize.mdx index 940363b23..e717ca015 100644 --- a/docs/sdk/sfa/sfa-ios/initialize.mdx +++ b/docs/sdk/sfa/sfa-ios/initialize.mdx @@ -23,6 +23,6 @@ constructor parameters are listed below | `serverTimeOffset` | Specifies the server time offset in seconds. This parameter is used to adjust the server time to the local time. The default value is 0 seconds. | | `storageServerUrl?` | Specifies the storage server URL. The default value is `https://session.web3auth.io`. | -## Initialize SingleFactorAuth +## Create instance diff --git a/sidebars.ts b/sidebars.ts index 1277518a0..873f88847 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1593,6 +1593,7 @@ const sidebars: SidebarsConfig = { type: "category", label: "Migration Guides", items: [ + "migration-guides/sfa-android-v1.2.0-to-v2.0.0", "migration-guides/sfa-android-v0.4.0-to-v1", "migration-guides/sfa-android-v0.1.0-to-v0.3.0", ], diff --git a/src/common/sdk/sfa/android/_sfa-android-initialization.mdx b/src/common/sdk/sfa/android/_sfa-android-initialization.mdx index 2c1700aca..d7fa04268 100644 --- a/src/common/sdk/sfa/android/_sfa-android-initialization.mdx +++ b/src/common/sdk/sfa/android/_sfa-android-initialization.mdx @@ -1,5 +1,16 @@ ```kotlin +import android.content.Context +import com.web3auth.singlefactorauth.SingleFactorAuth +import com.web3auth.singlefactorauth.types.Web3AuthOptions +import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork + // You can get the client id for your Web3Auth project from Web3Auth dashboard. -val sfaParams = SFAParams(Web3AuthNetwork.SAPPHIRE_MAINNET, "YOUR_WEB3AUTH_CLIENT_ID") -val singleFactorAuth = SingleFactorAuth(sfaParams) +val web3AuthOptions = Web3AuthOptions( + "YOUR_WEB3AUTH_CLIENT_ID", + Web3AuthNetwork.SAPPHIRE_MAINNET +) + +val context: Context = "YOUR_APPLICATION_CONTEXT" + +val singleFactorAuth = SingleFactorAuth(web3AuthOptions, context) ``` diff --git a/src/common/sdk/sfa/android/_sfa-android-install.mdx b/src/common/sdk/sfa/android/_sfa-android-install.mdx index 0d6c28a04..3f413fc88 100644 --- a/src/common/sdk/sfa/android/_sfa-android-install.mdx +++ b/src/common/sdk/sfa/android/_sfa-android-install.mdx @@ -18,6 +18,6 @@ Then, in your app-level `build.gradle` dependencies section, add the following: dependencies { // ... // focus-next-line - implementation 'com.github.web3auth:single-factor-auth-android:1.2.0' + implementation 'com.github.web3auth:single-factor-auth-android:2.1.0' } ``` diff --git a/src/common/sdk/sfa/android/_sfa-android-session-management.mdx b/src/common/sdk/sfa/android/_sfa-android-session-management.mdx index 83a3b44cb..d3a5f9e3a 100644 --- a/src/common/sdk/sfa/android/_sfa-android-session-management.mdx +++ b/src/common/sdk/sfa/android/_sfa-android-session-management.mdx @@ -1,11 +1,20 @@ ```kotlin -val sfakeyCF = singleFactorAuth.initialize(this.applicationContext) +import android.content.Context -sfakeyCF.whenComplete {sfaKey, error -> - if(error == null) { +val context: Context = "YOUR_APPLICATION_CONTEXT" +val sessionDataCF = singleFactorAuth.initialize(context) + +sessionDataCF.whenComplete {sessionData, error -> + if(error != null) { + // Session is no longer valid, or something went wrong + // Initiate the login flow again + } else if(sessionData == null) { + // No active session found + } else { // Session is present + // You can use the sessionData to get the public address, private key, + // userInfo, and signatures. + Log.i("Public address", sessionData.publicAddress) } - - // Session is not present } ``` diff --git a/src/common/versions.ts b/src/common/versions.ts index 15d1f3510..fe3f45314 100644 --- a/src/common/versions.ts +++ b/src/common/versions.ts @@ -7,7 +7,7 @@ export const pnpUnityVersion = `5.x.x`; export const pnpUnrealVersion = `4.1.x`; export const sfaWebVersion = `9.2.x`; -export const sfaAndroidVersion = `1.2.0`; +export const sfaAndroidVersion = `2.1.0`; export const sfaIOSVersion = `9.0.2`; export const sfaRNVersion = `2.0.x`; export const sfaFlutterVersion = `5.2.0`;