Skip to content

Commit d38b33c

Browse files
AyushBherwani1998AyushBherwani1998
authored
Merge pull request #1065 from Web3Auth/sfa-flutter-v6
Add Flutter v6 docs
2 parents df7b8c4 + 9ddb716 commit d38b33c

File tree

10 files changed

+305
-51
lines changed

10 files changed

+305
-51
lines changed

‎docs/migration-guides/sfa-flutter-v5-to-v6.mdx‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: SFA Flutter SDK - v5 to v6
3+
description: "SFA Flutter SDK - v5 to v6 | Documentation - Web3Auth"
4+
sidebar_label: v5 to v6
5+
---
6+
7+
This migration guide provides steps for upgrading from version v5 to v6 of the SFA Flutter SDK. The
8+
guide outlines significant changes and enhancements, including the support of `logout` method, and
9+
changes in `LoginParams`.
10+
11+
## Breaking Changes
12+
13+
### `SingleFactAuthFlutter` is now renamed to `SingleFactorAuthFlutter`
14+
15+
In v6, we have fixed the typo for the `SingleFactAuthFlutter`. Now you can use
16+
`SingleFactorAuthFlutter` to initialize the SDK.
17+
18+
```dart
19+
// remove-next-line
20+
final singleFactAuthFlutter = SingleFactAuthFlutter();
21+
// add-next-line
22+
final singleFactorAuthFlutter = SingleFactorAuthFlutter();
23+
```
24+
25+
### `SFAParams` is now renamed to `Web3AuthOptions`
26+
27+
In v6, we try to improve the developer experience by renaming the `SFAParams` to `Web3AuthOptions`.
28+
The change has been made to align with naming conventions across Web3Auth SDKs.
29+
30+
```dart
31+
final singleFactorAuthFlutter = SingleFactorAuthFlutter();
32+
33+
await singleFactorAuthFlutter.init(
34+
// focus-start
35+
// remove-next-line
36+
SFAParams(
37+
// add-next-line
38+
Web3AuthOptions(
39+
network: Web3AuthNetwork.mainnet,
40+
clientId: "YOUR_WEB3AUTH_CLIENT_ID",
41+
),
42+
// focus-end
43+
);
44+
```
45+
46+
### `SFAKey` is now renamed to `SessionData`
47+
48+
In v6, the `SFAKey` is now renamed to `SessionData`. This change was made to align with the naming
49+
conventions across Web3Auth SDKs. Please check the [SessionData](#sessiondata) type for more
50+
details.
51+
52+
```dart
53+
// remove-next-line
54+
final SFAKey key = await singleFactorAuthFlutter.connect(
55+
// add-next-line
56+
final SessionData sessionData = await singleFactorAuthFlutter.connect(
57+
LoginParams(
58+
verifier: 'YOUR_VERIFIER_NAME',
59+
verifierId: "VERIFIER_ID",
60+
idToken: "ID_TOKEN",
61+
),
62+
);
63+
```
64+
65+
### isSessionIdExists is replaced with isConnected
66+
67+
The `isSessionIdExists` method is replaced with the `isConnected` method to check whether the user
68+
is logged in Web3Auth or not. Please note, the `isConnected` method should be used after the
69+
`initialize` method.
70+
71+
```dart
72+
// remove-next-line
73+
final bool isSessionIdExists = await singleFactorAuthFlutter.isSessionIdExists();
74+
// add-next-line
75+
final bool isConnected = await singleFactorAuthFlutter.isConnected();
76+
```
77+
78+
### Changes in `LoginParams`
79+
80+
In v6, the `aggregateVerifier` is replaced with `subVerifierInfoArray`. The `subVerifierInfoArray`
81+
can be used to pass the sub verifier details when using an aggregate verifier.
82+
83+
Earlier, while using an aggregate verifier, the `verifier` was used to pass the sub verifier name.
84+
After v6, the `verifier` will take the aggregate verifier name, and sub verifier details can be
85+
passed in `subVerifierInfoArray`.
86+
87+
```dart
88+
final loginParams = LoginParams(
89+
// remove-next-line
90+
verifier: "SUB_VERIFIER_NAME",
91+
// add-next-line
92+
verifier: "AGGREGATE_VERIFIER_NAME",
93+
verifierId: "VERIFIER_ID",
94+
idToken: "ID_TOKEN",
95+
// remove-next-line
96+
aggregateVerifier: "AGGREGATE_VERIFIER_NAME",
97+
// add-next-line
98+
subVerifierInfoArray: [
99+
TorusSubVerifierInfo(
100+
"SUB_VERIFIER_NAME",
101+
"ID_TOKEN",
102+
),
103+
],
104+
);
105+
```
106+
107+
## Additional Features
108+
109+
Apart from the breaking changes, we have added couple of new functions in v6 to improve the
110+
developer experience.
111+
112+
### logout Method
113+
114+
The `logout` method is added to the SDK to log out the user and clear the session data. Please note,
115+
that this method only logout the user and invalides the Web3Auth session, and not the OAuth provider
116+
session.
117+
118+
```dart
119+
try {
120+
await singleFactorAuthFlutter.logout();
121+
} catch (e) {
122+
// Handle the error
123+
}
124+
```
125+
126+
### getSessionData Method
127+
128+
The `getSessionData` method is added to the SDK to get the session data. You can use this method to
129+
retrive the session data for an existing session. The method will return `null` if the user does not
130+
have an existing session. Please note, the `getSessionData` method should be used after the
131+
`initialize` method.
132+
133+
#### Usage
134+
135+
```dart
136+
final SessionData? sessionData = await singleFactorAuthFlutter.getSessionData();
137+
138+
if (sessionData == null) {
139+
// User does not have an existing session
140+
}
141+
```
142+
143+
#### SessionData
144+
145+
The `SessionData` has the following properties to retrive the relevant session information.
146+
147+
| Name | Description |
148+
| --------------- | ------------------------------------------------------------------------- |
149+
| `privateKey` | Retrieves the user's private key. |
150+
| `publicAddress` | Retrieves the user's public address. |
151+
| `userInfo?` | Retrieves the user's information like email, name, verifier id, and more. |
152+
| `signatures?` | Retrieves the node's signatures that are returned for request. |

‎docs/sdk/sfa/sfa-android/usage.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ you'll see an Error message.
1717

1818
:::
1919

20+
## Functionality Overview
21+
2022
The SingleFactorAuth instance natively provides the following methods:
2123

2224
| Method | Description |
@@ -152,8 +154,12 @@ We have included Session Management in this SDK, so calling the `getSessionData`
152154
user's `SessionData` without re-logging in the user if a user has an active session. Otherwise, it
153155
will return `null`.
154156

157+
:::tip
158+
155159
Please note, you should use this method after the `initialize` method.
156160

161+
:::
162+
157163
### Usage
158164

159165
```kotlin

‎docs/sdk/sfa/sfa-flutter/initialize.mdx‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@ successful use of Web3Auth SFA Flutter.
1616

1717
## Parameters
1818

19-
Construct and configure the `init` method with the `SFAParams`
19+
The `init` method requires a `Web3AuthOptions` object. Please note that these are the important
20+
parameters to configure the SDK.
2021

2122
<Tabs
2223
defaultValue="table"
@@ -39,12 +40,12 @@ Construct and configure the `init` method with the `SFAParams`
3940
<TabItem value="class">
4041

4142
```dart
42-
class SFAParams {
43+
class Web3AuthOptions {
4344
final Web3AuthNetwork network;
4445
final String clientId;
4546
final int sessionTime;
4647
47-
SFAParams(
48+
Web3AuthOptions(
4849
{required this.network,
4950
required this.clientId,
5051
this.sessionTime = 86400});
@@ -75,7 +76,11 @@ enum Web3AuthNetwork {
7576

7677
## Initialize Web3AuthFlutter
7778

78-
Initialize the `Web3AuthFlutter` plugin at the very beginning such as in the overriden `initState`
79-
function.
79+
To initialize the SDK, you can use the `init` method. Once, the SDK is initialized, you can use the
80+
`initialize` method to initialize the SDK with existing session. After successful initialization,
81+
you can use the `getSessionData` method to check if the user is logged in or not.
82+
83+
Please note, the `initialize` method will throw an error if there is no active session present. You
84+
can swallow the error or handle it gracefully in your app.
8085

8186
<Initialization />

‎docs/sdk/sfa/sfa-flutter/usage.mdx‎

Lines changed: 96 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,16 @@ you'll see an Error message.
1919

2020
:::
2121

22+
## Functionality Overview
23+
2224
The SingleFactorAuth instance natively provides the following methods:
2325

24-
- [connect](#login-user) - Use to login user and retrive private key pair.
25-
- [initialize](#session-management) - This method helps to achieve session management. It
26-
authenticates user if the session is present, avoiding re-logging.
26+
| Method | Description |
27+
| ------------------------------------------ | ------------------------------------------------------------ |
28+
| [connect](#login-user) | Use to login user and retrieve private key pair. |
29+
| [logout](#logout-user) | Use to logout existing user. |
30+
| [connected](#check-users-logged-in-status) | Use to check whether the user is logged in or not. |
31+
| [getSessionData](#get-session-data) | This method helps to get the session data for valid session. |
2732

2833
## Login User
2934

@@ -48,12 +53,13 @@ method. The method accepts `LoginParams`, and returns `SFAKey`.
4853
>
4954

5055
<TabItem value="table">
51-
| Parameter | Description |
52-
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53-
| `verifier` | The `verifier` parameter takes the name of the ustom verifier from the Web3Auth Dashboard. This is a required field that must be a `String`. If you're using an aggregate verifier, make sure to pass the sub-verifier name. |
54-
| `verifierId` | The `verifierID` takes the JWT verifier ID to be used for JWT/ID token verification. It can be an email, sub, or custom value available in the JWT token. |
55-
| `idToken` | The `idToken` accepts a JWT token obtained from the user's login provider. |
56-
| `aggregateVerifier?` | The `aggregateVerifier` parameter takes the name of the Aggregate verifier from the Web3Auth Dashboard. |
56+
57+
| Parameter | Description |
58+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
59+
| `verifier` | The `verifier` parameter takes the name of the custom verifier from the Web3Auth Dashboard. This is a required field that must be a `String`. If you're using an aggregate verifier, make sure to pass the aggregate verifier name. |
60+
| `verifierId` | The `verifierID` takes the JWT verifier ID to be used for JWT/ID token verification. It can be an email, sub, or custom value available in the JWT token. |
61+
| `idToken` | The `idToken` accepts a JWT token obtained from the user's login provider. |
62+
| `subVerifierInfoArray?` | Sub verifier info. Usually used during the aggregate verifier. It takes `List<TorusSubVerifierInfo>` as a value. |
5763

5864
</TabItem>
5965

@@ -99,36 +105,96 @@ class LoginParams {
99105

100106
<TabItem value="single-verifier">
101107
```dart
102-
Future<SFAKey> connect() {
103-
return _singleFactorAuthFlutterPlugin.connect(LoginParams(
104-
verifier: 'YOUR_VERIFIER_NAME',
105-
verifierId: 'YOUR_VERIFIER_ID',
106-
idToken: 'YOUR_ID_TOKEN',
107-
),
108-
);
109-
}
110-
```
108+
final loginParams = LoginParams(
109+
verifier: 'YOUR_VERIFIER_NAME',
110+
verifierId: 'YOUR_VERIFIER_ID',
111+
idToken: 'YOUR_ID_TOKEN',
112+
);
113+
114+
try { final sessionData = await singleFactorAuthFlutter.connect(loginParams); } catch (e) { //
115+
Handle error }
116+
117+
````
111118
</TabItem>
112119
<TabItem value="aggregate-verifier">
120+
113121
```dart
114-
Future<SFAKey> connect() {
115-
return _singleFactorAuthFlutterPlugin.connect(LoginParams(
116-
verifier: 'YOUR_VERIFIER_NAME',
117-
verifierId: 'YOUR_VERIFIER_ID',
118-
idToken: 'YOUR_ID_TOKEN',
119-
aggregateVerifier: 'YOUR_AGGREGATE_VERIFIER_NAME',
120-
));
122+
123+
final subVerifierInfoArray = [
124+
TorusSubVerifierInfo(
125+
'YOUR_SUB_VERIFIER_NAME',
126+
'YOUR_ID_TOKEN',
127+
),
128+
];
129+
130+
final loginParams = LoginParams(
131+
verifier: 'YOUR_AGGREGATE_VERIFIER_NAME',
132+
verifierId: 'YOUR_VERIFIER_ID',
133+
idToken: 'YOUR_ID_TOKEN',
134+
subVerifierInfoArray: subVerifierInfoArray,
135+
);
136+
137+
try {
138+
final sessionData = await singleFactorAuthFlutter.connect(loginParams);
139+
} catch (e) {
140+
// Handle error
121141
}
122-
```
142+
````
143+
123144
</TabItem>
124145
</Tabs>
125146
126-
## Session Management
147+
## Logout User
127148
128-
We have included Session Management in this SDK, so calling the initialize function to get the
129-
SFAKey value without re-logging in the user if a user has an active session will return the SFAKey,
130-
otherwise, it will throw an error.
149+
To logout the current user, you can use the `logout` method. Please note, the method will not logout
150+
the user from the authentication provider, it'll only logout and invalidate the Web3Auth session.
151+
152+
### Usage
153+
154+
```dart
155+
try {
156+
await singleFactorAuthFlutter.logout();
157+
// Logged out successfully
158+
} catch (e) {
159+
// Handle error
160+
}
161+
```
162+
163+
## Check User's Logged In Status
164+
165+
You can use the `connected` method to check whether the user is logged in Web3Auth or not. Please
166+
note, you should call this method after the `initialize` method if you want to check the user's
167+
connection status for an existing session.
168+
169+
### Usage
170+
171+
```dart
172+
final isConnected = await singleFactorAuthFlutter.connected();
173+
```
174+
175+
## Get Session Data
176+
177+
We have included Session Management in this SDK, so calling the `getSessionData` will retrive the
178+
user's `SessionData` without re-logging in the user if a user has an active session. Otherwise, it
179+
will return `null`.
180+
181+
:::tip
182+
183+
Please note, you should use this method after the `initialize` method.
184+
185+
:::
131186

132187
### Usage
133188

134189
<SessionManagement />
190+
191+
### Response
192+
193+
The `SessionData` has the following properties to retrive the relevant session information.
194+
195+
| Name | Description |
196+
| --------------- | ------------------------------------------------------------------------- |
197+
| `privateKey` | Retrieves the user's private key. |
198+
| `publicAddress` | Retrieves the user's public address. |
199+
| `userInfo?` | Retrieves the user's information like email, name, verifier id, and more. |
200+
| `signatures?` | Retrieves the node's signatures that are returned for request. |

0 commit comments

Comments
 (0)