-
Notifications
You must be signed in to change notification settings - Fork 176
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #981 from Web3Auth/sfa-android-v2
[SFA Android] Update documentation & add migration guide
- Loading branch information
Showing
9 changed files
with
263 additions
and
37 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
15 changes: 13 additions & 2 deletions
15
src/common/sdk/sfa/android/_sfa-android-initialization.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
19 changes: 14 additions & 5 deletions
19
src/common/sdk/sfa/android/_sfa-android-session-management.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters