Skip to content

Commit 4e14751

Browse files
update sfa js docs
1 parent a26c8e0 commit 4e14751

File tree

2 files changed

+87
-111
lines changed

2 files changed

+87
-111
lines changed

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

Lines changed: 87 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -14,50 +14,35 @@ 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-session-id) | 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

34-
`connect(loginParams: LoginParams)`
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/).
3538

36-
To log a user in the Web3Auth SFA JS SDK, you need to call the `connect()` function.
39+
### LoginParams
3740

38-
| Variable | Description |
39-
| ------------- | -------------------------- |
40-
| `loginParams` | Mandatory login Parameters |
41-
42-
#### Returns
43-
44-
```tsx
45-
connect(loginParams: LoginParams): Promise<IProvider | null>
46-
```
47-
48-
#### `LoginParams`
49-
50-
`connect(loginParams: LoginParams)`
51-
52-
On successful login, the `connect()` function returns a `IProvider` instance. This instance contains
53-
the corresponding provider for your selected blockchain. You can use this provider to connect your
54-
user to the blockchain and perform transactions.
55-
56-
On unsuccessful login, this function will return a `null` value.
41+
The method accepts `LoginParams` as an input.
5742

5843
<SFALoginParams />
5944

60-
#### `TorusSubVerifierInfo`
45+
### TorusSubVerifierInfo
6146

6247
<Tabs
6348
defaultValue="table"
@@ -69,7 +54,7 @@ On unsuccessful login, this function will return a `null` value.
6954

7055
<TabItem value="table">
7156

72-
| Parameter | Description |
57+
| Name | Description |
7358
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
7459
| `verifier` | Name of the verifier. It's a `string` mandatory parameter. |
7560
| `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. |
@@ -88,7 +73,7 @@ export interface TorusSubVerifierInfo {
8873
</TabItem>
8974
</Tabs>
9075

91-
#### Usage
76+
### Usage
9277

9378
<Tabs
9479
defaultValue="single"
@@ -102,9 +87,12 @@ export interface TorusSubVerifierInfo {
10287

10388
```js
10489
await web3auth.connect({
105-
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().
106-
verifierId: "verifier-id-value", // e.g. `Yux1873xnibdui` or `[email protected]` replace with your verifier id(sub or email)'s value.
107-
idToken: "JWT Token", // replace with your newly created unused JWT Token.
90+
// Get the verifier name from the Web3Auth Dashboard
91+
verifier: "YOUR_VERIFIER_NAME",
92+
// Pass the JWT token verification value selected for verifier.
93+
verifierId: "YOUR_VERIFIER_ID",
94+
// Pass your JWT token
95+
idToken: "YOUR_JWT_TOKEN",
10896
});
10997
```
11098

@@ -114,13 +102,18 @@ await web3auth.connect({
114102

115103
```js
116104
await web3auth.connect({
117-
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().
118-
verifierId: "verifier-id-value", // e.g. `Yux1873xnibdui` or `[email protected]` replace with your verifier id(sub or email)'s value.
119-
idToken: "JWT Token", // replace with your newly created unused JWT Token.
105+
// Get the aggregate verifier name from the Web3Auth Dashboard
106+
verifier: "YOUR_AGGREGATE_VERIFIER_NAME",
107+
// Pass the JWT token verification value selected for sub verifier.
108+
verifierId: "YOUR_VERIFIER_ID",
109+
// Pass your JWT token
110+
idToken: "YOUR_JWT_TOKEN",
120111
subVerifierInfoArray: [
121112
{
122-
verifier: "sub-verifier-name", // e.g. `google`
123-
idToken: "JWT Token", // replace with your newly created unused JWT Token.
113+
// Get the sub verifier name from the Web3Auth Dashboard
114+
verifier: "YOUR_SUB_VERIFIER_NAME",
115+
// Pass the JWT token
116+
idToken: "YOUR_JWT_TOKEN",
124117
},
125118
],
126119
});
@@ -132,41 +125,40 @@ await web3auth.connect({
132125

133126
## Get a native provider
134127

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

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

139-
#### Returns
133+
### Usage
140134

141135
```js
142-
get provider(): IProvider | null;
136+
const provider = web3auth.provider;
137+
// Use the provider to interact with the blockchain
143138
```
144139

145140
## Get sessionId
146141

147-
`sessionId()`
142+
The method returns the session id for the current active session as the string.
148143

149-
Returns the sessionId of the user as a string.
150-
151-
#### Returns
144+
### Usage
152145

153146
```js
154-
get sessionId(): string;
147+
const sessionId = web3auth.sessionId;
155148
```
156149

157150
## Authenticate the user
158151

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

163-
#### Returns
155+
### Usage
164156

165157
```js
166-
authenticateUser(): Promise<UserAuthInfo>;
158+
const userAuthInfo = await web3auth.authenticateUser();
167159
```
168160

169-
#### `UserAuthInfo`
161+
### Response
170162

171163
```ts
172164
export type UserAuthInfo = {
@@ -176,15 +168,11 @@ export type UserAuthInfo = {
176168

177169
## Add a new chain
178170

179-
`addChain(chainConfig: CustomChainConfig)`
180-
181-
Add chain configuration to the web3auth instance.
171+
To add a new chain to your Web3Auth provider instance you can use the `addChain` method.
182172

183-
| Variable | Description |
184-
| ------------- | --------------------------------------------------------------------- |
185-
| `chainConfig` | Mandatory chain-specific configuration as a `CustomChainConfig` type. |
173+
### Parameters
186174

187-
#### `CustomChainConfig`
175+
The method accepts a `CustomChainConfig` object as an input.
188176

189177
<Tabs
190178
defaultValue="table"
@@ -196,19 +184,19 @@ Add chain configuration to the web3auth instance.
196184

197185
<TabItem value="table">
198186

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

213201
</TabItem>
214202

@@ -275,32 +263,32 @@ export type CustomChainConfig = {
275263

276264
## Switch the chain
277265

278-
`switchChain(params: {chainId: string;})`
279-
280-
Switch to one of the added chains
281-
282-
| Variable | Description |
283-
| --------- | ---------------------------------------------------------------------- |
284-
| `chainId` | Id of the chain to switch to. It's a mandatory parameter as a `string` |
285-
286-
## Logging out the user
266+
To switch the chain for the provider instance you need to call the `switchChain` method. Please make
267+
sure, you have first added the chain using the [addChain](#add-a-new-chain) method.
287268

288-
`logout()`
269+
### Parameters
289270

290-
Logs out the user and clears the session.
271+
| Name | Description |
272+
| --------- | ---------------------------------------------------------------- |
273+
| `chainId` | The hex chain ID of the blockchain network you want to switch to |
291274

292-
:::tip Note
275+
### Usage
293276

294-
`@web3auth/single-factor-auth` SDK only works for users who have **not enabled MFA**.
277+
```ts
278+
// Switches the chain to the Polygon network
279+
await web3auth.switchChain({ chainId: "0x89" });
280+
```
295281

296-
:::
282+
## Logging out the user
297283

298-
:::danger MFA enabled users
284+
To logout the user and clear the session, call the `logout` method. Please note, this method only
285+
clears the Web3Auth session, and doesn't clears the OAuth session.
299286

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

303-
:::
289+
```ts
290+
await web3auth.logout();
291+
```
304292

305293
## Wallet Services Plugin Methods
306294

@@ -337,13 +325,3 @@ You can use the `showWalletUI` function to show the templated wallet UI services
337325
You can use the wallet services provider to integrate prebuilt transaction confirmation screens into
338326
your application. Upon successful completion, you can retrieve the signature for the request.
339327
[Learn more about transaction confirmation screens](./wallet-services/usage#transaction-confirmation-screens).
340-
341-
## Example
342-
343-
### Custom JWT Example
344-
345-
<SFAWebCustomJWTExample />
346-
347-
### Firebase JWT Example
348-
349-
<SFAWebFirebaseJWTExample />

src/common/sdk/sfa/_sfa_login_params.mdx

Lines changed: 0 additions & 2 deletions
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)