Skip to content

Commit ed18025

Browse files
authored
Merge pull request #1059 from Web3Auth/sfa-web-improvements
Update SFA JS docs
2 parents a7a2d4e + d562262 commit ed18025

File tree

2 files changed

+88
-112
lines changed

2 files changed

+88
-112
lines changed

docs/sdk/sfa/sfa-js/usage.mdx

+88-110
Original file line numberDiff line numberDiff line change
@@ -14,57 +14,42 @@ Once you've installed and successfully initialized Web3Auth, you can use it to a
1414
users. Further, you can use the native provider given by Web3Auth to connect the users to the
1515
respective blockchain network.
1616

17-
Natively, the instance of Web3Auth (called web3auth in our examples) returns the following
18-
functions:
19-
20-
- `connect()` - Logs in the User using the `verifier`, `verifierId` & `idToken`, which are
21-
mandatory, while `subVerifierInfoArray` and `serverTimeOffset` are optional.
22-
- `provider()` - Returns the native provider that can be used to make different blockchain
23-
transactions.
24-
- `sessionId()` - Returns the sessionId of the user as a string.
25-
- `authenticateUser()` - Returns a promise of the `UserAuthInfo` object containing the `idToken` of
26-
the user.
27-
- `addChain()` - Add chain configuration to the web3auth instance.
28-
- `switchChain()` - Switches the chainId to one of the added chainIds.
29-
- `getUserInfo()` - Returns the user information.
30-
- `logout()` - Log out the user from the web3auth instance.
17+
## Functionality Overview
18+
19+
Natively, the instance of Web3Auth (called web3auth in our examples) has the following
20+
methods/getters:
21+
22+
| Name | Description |
23+
| ------------------------------------------ | --------------------------------------------------------------------------------------- |
24+
| [connect](#logging-in-your-user) | Use this method to login a user to Web3Auth SFA JS SDK. |
25+
| [provider](#get-a-native-provider) | Returns the native provider that can be used to make different blockchain transactions. |
26+
| [sessionId](#get-sessionid) | Returns the sessionId of the user as a string. |
27+
| [authenticateUser](#authenticate-the-user) | Returns a promise of the `UserAuthInfo` object containing the `idToken` of the user. |
28+
| [addChain](#add-a-new-chain) | Add chain configuration to the web3auth instance. |
29+
| [switchChain](#switch-the-chain) | Switches the chainId to one of the added chainIds. |
30+
| [getUserInfo](#get-user-info) | Returns the user information. |
31+
| [logout](#logging-out-the-user) | Log out the user from the web3auth instance. |
3132

3233
## Logging in your User
3334

35+
To log in a user using the Web3Auth SFA JS SDK, call the `connect` method. This method returns an
36+
`IProvider` instance upon successful authentication which can then be used to interact with various
37+
blockchain networks. For more details, [refer to the provider documentation](./providers/).
38+
3439
:::tip
3540

3641
Please refer to the [Authentication](./authentication) section for more details on the setting up
3742
your verifier and other authentication parameters.
3843

3944
:::
4045

41-
`connect(loginParams: LoginParams)`
42-
43-
To log a user in the Web3Auth SFA JS SDK, you need to call the `connect()` function.
44-
45-
| Variable | Description |
46-
| ------------- | -------------------------- |
47-
| `loginParams` | Mandatory login Parameters |
48-
49-
#### Returns
50-
51-
```tsx
52-
connect(loginParams: LoginParams): Promise<IProvider | null>
53-
```
54-
55-
#### `LoginParams`
46+
### LoginParams
5647

57-
`connect(loginParams: LoginParams)`
58-
59-
On successful login, the `connect()` function returns a `IProvider` instance. This instance contains
60-
the corresponding provider for your selected blockchain. You can use this provider to connect your
61-
user to the blockchain and perform transactions.
62-
63-
On unsuccessful login, this function will return a `null` value.
48+
The method accepts `LoginParams` as an input.
6449

6550
<SFALoginParams />
6651

67-
#### `TorusSubVerifierInfo`
52+
### TorusSubVerifierInfo
6853

6954
<Tabs
7055
defaultValue="table"
@@ -76,7 +61,7 @@ On unsuccessful login, this function will return a `null` value.
7661

7762
<TabItem value="table">
7863

79-
| Parameter | Description |
64+
| Name | Description |
8065
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
8166
| `verifier` | Name of the verifier. It's a `string` mandatory parameter. |
8267
| `idToken` | A newly created `JWT Token` that has not already been sent to Web3Auth or a `Duplicate Token` error will be thrown. It's a `string` mandatory parameter. |
@@ -95,7 +80,7 @@ export interface TorusSubVerifierInfo {
9580
</TabItem>
9681
</Tabs>
9782

98-
#### Usage
83+
### Usage
9984

10085
<Tabs
10186
defaultValue="single"
@@ -109,9 +94,12 @@ export interface TorusSubVerifierInfo {
10994

11095
```js
11196
await web3auth.connect({
112-
verifier: "verifier-name", // e.g. `web3auth-sfa-verifier` replace with your verifier name, and it has to be on the same network passed in init().
113-
verifierId: "verifier-id-value", // e.g. `Yux1873xnibdui` or `[email protected]` replace with your verifier id(sub or email)'s value.
114-
idToken: "JWT Token", // replace with your newly created unused JWT Token.
97+
// Get the verifier name from the Web3Auth Dashboard
98+
verifier: "YOUR_VERIFIER_NAME",
99+
// Pass the JWT token verification value selected for verifier.
100+
verifierId: "YOUR_VERIFIER_ID",
101+
// Pass your JWT token
102+
idToken: "YOUR_JWT_TOKEN",
115103
});
116104
```
117105

@@ -121,13 +109,18 @@ await web3auth.connect({
121109

122110
```js
123111
await web3auth.connect({
124-
verifier: "aggregate-verifier-name", // e.g. `web3auth-aggregate-verifier` replace with your verifier name, and it has to be on the same network passed in init().
125-
verifierId: "verifier-id-value", // e.g. `Yux1873xnibdui` or `[email protected]` replace with your verifier id(sub or email)'s value.
126-
idToken: "JWT Token", // replace with your newly created unused JWT Token.
112+
// Get the aggregate verifier name from the Web3Auth Dashboard
113+
verifier: "YOUR_AGGREGATE_VERIFIER_NAME",
114+
// Pass the JWT token verification value selected for sub verifier.
115+
verifierId: "YOUR_VERIFIER_ID",
116+
// Pass your JWT token
117+
idToken: "YOUR_JWT_TOKEN",
127118
subVerifierInfoArray: [
128119
{
129-
verifier: "sub-verifier-name", // e.g. `google`
130-
idToken: "JWT Token", // replace with your newly created unused JWT Token.
120+
// Get the sub verifier name from the Web3Auth Dashboard
121+
verifier: "YOUR_SUB_VERIFIER_NAME",
122+
// Pass the JWT token
123+
idToken: "YOUR_JWT_TOKEN",
131124
},
132125
],
133126
});
@@ -139,41 +132,40 @@ await web3auth.connect({
139132

140133
## Get a native provider
141134

142-
`provider()`
135+
The method returns the provider instance that can be used to interact with different blockchain
136+
networks. Please note, if there's no active session, the method will return `null`.
143137

144-
Returns the native provider that can be used to make different blockchain transactions.
138+
Please refer to the [provider documentation](./providers/) for more details.
145139

146-
#### Returns
140+
### Usage
147141

148142
```js
149-
get provider(): IProvider | null;
143+
const provider = web3auth.provider;
144+
// Use the provider to interact with the blockchain
150145
```
151146

152147
## Get sessionId
153148

154-
`sessionId()`
149+
The method returns the session id for the current active session as the string.
155150

156-
Returns the sessionId of the user as a string.
157-
158-
#### Returns
151+
### Usage
159152

160153
```js
161-
get sessionId(): string;
154+
const sessionId = web3auth.sessionId;
162155
```
163156

164157
## Authenticate the user
165158

166-
`authenticateUser()`
167-
168-
Returns a promise of the `UserAuthInfo` object containing the `idToken` of the user.
159+
The method authenticates the connected user, and returns user auth info containing the Web3Auth JWT
160+
token. You can use the idToken for backend verification.
169161

170-
#### Returns
162+
### Usage
171163

172164
```js
173-
authenticateUser(): Promise<UserAuthInfo>;
165+
const userAuthInfo = await web3auth.authenticateUser();
174166
```
175167

176-
#### `UserAuthInfo`
168+
### Response
177169

178170
```ts
179171
export type UserAuthInfo = {
@@ -183,15 +175,11 @@ export type UserAuthInfo = {
183175

184176
## Add a new chain
185177

186-
`addChain(chainConfig: CustomChainConfig)`
178+
To add a new chain to your Web3Auth provider instance you can use the `addChain` method.
187179

188-
Add chain configuration to the web3auth instance.
180+
### Parameters
189181

190-
| Variable | Description |
191-
| ------------- | --------------------------------------------------------------------- |
192-
| `chainConfig` | Mandatory chain-specific configuration as a `CustomChainConfig` type. |
193-
194-
#### `CustomChainConfig`
182+
The method accepts a `CustomChainConfig` object as an input.
195183

196184
<Tabs
197185
defaultValue="table"
@@ -203,19 +191,19 @@ Add chain configuration to the web3auth instance.
203191

204192
<TabItem value="table">
205193

206-
| Parameter | Description |
207-
| ------------------ | ----------------------------------------------------------------------------------------------- |
208-
| `chainNamespace` | Namespace of the chain. It's a mandatory parameter as a `ChainNamespaceType` type. |
209-
| `chainId` | The chain id of the chain. It's a mandatory parameter as a `string`. |
210-
| `rpcTarget` | RPC target URL for the chain. It's a mandatory parameter as a `string`. |
211-
| `wsTarget` | Web socket target URL for the chain. It's an optional parameter as a `string`. |
212-
| `displayName` | Display Name for the chain. It's an optional parameter as a `string`. |
213-
| `blockExplorerUrl` | URL of the block explorer. It's an optional parameter as a `string`. |
214-
| `ticker` | Default currency ticker of the network (e.g: ETH). It's an optional parameter as a `string`. |
215-
| `tickerName` | Name for currency ticker (e.g: `Ethereum`). It's an optional parameter as a `string`. |
216-
| `decimals` | Number of decimals for the currency ticker (e.g: 18). It's an optional parameter as a `number`. |
217-
| `logo` | Logo for the token. It's an optional parameter as a `string`. |
218-
| `isTestnet` | Whether the network is testnet or not. It's an optional parameter as a `boolean`. |
194+
| Name | Description |
195+
| ------------------- | ------------------------------------------------------------------------------------------ |
196+
| `chainNamespace` | Namespace of the chain. It `ChainNamespaceType` type. |
197+
| `chainId` | The chain id of the network in Hex format. |
198+
| `rpcTarget` | RPC target URL for the chain. The RPC url is used to interact with the blockchain network. |
199+
| `wsTarget?` | Web socket target URL for the chain. |
200+
| `displayName?` | Display Name for the chain. |
201+
| `blockExplorerUrl?` | Blockchain explorer URL for the network. |
202+
| `ticker?` | Network's native currency ticker (e.g: ETH for Ethereum) |
203+
| `tickerName?` | Network's native currency name (e.g: `Ethereum`). |
204+
| `decimals?` | Network's native currency decimal precision (e.g: 18 for Ethereum). Default value is 18. |
205+
| `logo?` | Logo for the token. |
206+
| `isTestnet?` | Whether the network is testnet or not. |
219207

220208
</TabItem>
221209

@@ -282,32 +270,32 @@ export type CustomChainConfig = {
282270

283271
## Switch the chain
284272

285-
`switchChain(params: {chainId: string;})`
286-
287-
Switch to one of the added chains
288-
289-
| Variable | Description |
290-
| --------- | ---------------------------------------------------------------------- |
291-
| `chainId` | Id of the chain to switch to. It's a mandatory parameter as a `string` |
273+
To switch the chain for the provider instance you need to call the `switchChain` method. Please make
274+
sure, you have first added the chain using the [addChain](#add-a-new-chain) method.
292275

293-
## Logging out the user
294-
295-
`logout()`
276+
### Parameters
296277

297-
Logs out the user and clears the session.
278+
| Name | Description |
279+
| --------- | ---------------------------------------------------------------- |
280+
| `chainId` | The hex chain ID of the blockchain network you want to switch to |
298281

299-
:::tip Note
282+
### Usage
300283

301-
`@web3auth/single-factor-auth` SDK only works for users who have **not enabled MFA**.
284+
```ts
285+
// Switches the chain to the Polygon network
286+
await web3auth.switchChain({ chainId: "0x89" });
287+
```
302288

303-
:::
289+
## Logging out the user
304290

305-
:::danger MFA enabled users
291+
To logout the user and clear the session, call the `logout` method. Please note, this method only
292+
clears the Web3Auth session, and doesn't clears the OAuth session.
306293

307-
For MFA enabled users, you'll see
308-
`Error("User has already enabled mfa, please use the @webauth/webauth-web sdk for login with mfa");`
294+
### Usage
309295

310-
:::
296+
```ts
297+
await web3auth.logout();
298+
```
311299

312300
## Wallet Services Plugin Methods
313301

@@ -344,13 +332,3 @@ You can use the `showWalletUI` function to show the templated wallet UI services
344332
You can use the wallet services provider to integrate prebuilt transaction confirmation screens into
345333
your application. Upon successful completion, you can retrieve the signature for the request.
346334
[Learn more about transaction confirmation screens](./wallet-services/usage#transaction-confirmation-screens).
347-
348-
## Example
349-
350-
### Custom JWT Example
351-
352-
<SFAWebCustomJWTExample />
353-
354-
### Firebase JWT Example
355-
356-
<SFAWebFirebaseJWTExample />

src/common/sdk/sfa/_sfa_login_params.mdx

-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
import TabItem from "@theme/TabItem";
22
import Tabs from "@theme/Tabs";
33

4-
#### `LoginParams`
5-
64
<Tabs
75
defaultValue="table"
86
values={[

0 commit comments

Comments
 (0)