Skip to content

Commit 692fc30

Browse files
shahbaz17shahbaz17
authored
Merge pull request #969 from Web3Auth/sfa-ios-9
[SFA iOS] Update the docs for latest v9.0.x
2 parents 0cac254 + a06984a commit 692fc30

File tree

8 files changed

+257
-35
lines changed

8 files changed

+257
-35
lines changed

‎docs/migration-guides/sfa-ios-v8-to-v9.mdx

+162
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: SFA iOS SDK - v8 to v9
3+
description: "SFA iOS SDK - v8 to v9 | Documentation - Web3Auth"
4+
sidebar_label: v8 to v9
5+
---
6+
7+
This migration guide provides steps for upgrading from version v8 to v9 of the SFA iOS SDK. The
8+
guide outlines significant changes and enhancements.
9+
10+
## Breaking Changes
11+
12+
### Web3AuthNetwork Changes
13+
14+
In v9, we have removed the nested enum and refactored the Web3AuthNetwork. Please checkout the table
15+
below for the changes.
16+
17+
| Old Value | New Value |
18+
| ---------------------------- | ----------------- |
19+
| .sapphire(.SAPPHIRE_MAINNET) | .SAPPHIRE_MAINNET |
20+
| .sapphire(.SAPPHIRE_DEVNET) | .SAPPHIRE_DEVNET |
21+
| .legacy(.MAINNET) | .MAINNET |
22+
| .legacy(.TESTNET) | .TESTNET |
23+
| .legacy(.CYAN) | .CYAN |
24+
| .legacy(.AQUA) | .AQUA |
25+
26+
### SFAParams Changes
27+
28+
In v9, we try to improve the developer experience by renaming the `SFAParams` to `Web3AuthOptions`.
29+
It has been renamed to align with naming conventions across Web3Auth SDKs. Along with this, we have
30+
renamed couple of constructor parameters.
31+
32+
- `web3AuthClientId` is renamed to `clientId`.
33+
- `network` is renamed to `web3AuthNetwork`.
34+
35+
[Checkout Web3AuthOptions for available parameters](/docs/sdk/core-kit/sfa-ios/initialize#parameters).
36+
37+
```swift
38+
// remove-start
39+
let singleFactorAuthArgs = SFAParams(
40+
web3AuthClientId: "YOUR_WEB3AUTH_CLIENT_ID",
41+
network: .sapphire(.SAPPHIRE_MAINNET)
42+
)
43+
// remove-end
44+
45+
// add-start
46+
let web3AuthOptions = Web3AuthOptions(
47+
clientId: "YOUR_WEB3AUTH_CLIENT_ID",
48+
web3AuthNetwork: .SAPPHIRE_MAINNET
49+
)
50+
// add-end
51+
52+
let singleFactoreAuth = SingleFactorAuth(
53+
// remove-next-line
54+
params: SFAParams
55+
// add-next-line
56+
params: web3AuthOptions
57+
)
58+
```
59+
60+
### SFAKey is replaced with SessionData
61+
62+
In v9, we removed the `SFAKey` and added the `SessionData` object to return the relveant session
63+
information like private key, address, user information, and signatures.
64+
65+
```swift
66+
// remove-next-line
67+
let sfaKey: SFAKey = try await singleFactoreAuth.connect(loginParams: loginParams)
68+
// add-next-line
69+
let sessionData: SessionData = try await singleFactoreAuth.connect(loginParams: loginParams)
70+
```
71+
72+
### getTorusKey method is now private
73+
74+
The `getTorusKey` method is now private and can no longer be accessible. You can use the `connect`
75+
method to login user.
76+
77+
```swift
78+
let loginParams = LoginParams(
79+
verifier: "YOUR_VERIFIER_NAME",
80+
verifierId: "VERIFIER_ID",
81+
idToken: "ID_TOKEN"
82+
)
83+
84+
// focus-start
85+
// remove-next-line
86+
let torusKey: TorusSFAKey = try await singleFactoreAuth.getTorusKey(loginParams: loginParams)
87+
// add-next-line
88+
let sessionData: SessionData = try await singleFactoreAuth.connect(loginParams: loginParams)
89+
// focus-end
90+
```
91+
92+
### initialize method changes
93+
94+
Starting v9, the `initialize` method will not return any value. To check whether the user already
95+
has an existing session, please use the `getSessionData` method. The `getSessionData` method will
96+
return `nil` if the user does not have an existing session.
97+
98+
```swift
99+
// remove-next-line
100+
let sfaKey: SFAKey = try await singleFactoreAuth.initialize()
101+
// add-next-line
102+
try await singleFactoreAuth.initialize()
103+
104+
// add-start
105+
let sessionData = singleFactoreAuth.getSessionData()
106+
if sessionData == nil {
107+
// User does not have an existing session
108+
}
109+
// add-end
110+
```
111+
112+
## Additional Features
113+
114+
Apart from the breaking changes, we have added couple of new functions in v9 to improve the
115+
developer experience.
116+
117+
### logout Method
118+
119+
The `logout` method is added to the SDK to log out the user and clear the session data. Please note,
120+
that this method only logout the user and invalides the Web3Auth session, and not the OAuth provider
121+
session.
122+
123+
```swift
124+
try await singleFactoreAuth.logout()
125+
```
126+
127+
### getSessionData Method
128+
129+
The `getSessionData` method is added to the SDK to get the session data. You can use this method to
130+
retrive the session data for an existing session. The method will return `nil` if the user does not
131+
have an existing session.
132+
133+
#### Usage
134+
135+
```swift
136+
let sessionData = singleFactoreAuth.getSessionData()
137+
138+
if sessionData == nil {
139+
// User does not have an existing session
140+
}
141+
```
142+
143+
#### SessionData
144+
145+
The `SessionData` has the following four functions to retrive the relevant session information.
146+
147+
| Function Name | Description |
148+
| ------------------ | ------------------------------------------------------------------------- |
149+
| `getPrivateKey` | Retrieves the user's private key. |
150+
| `getPublicAddress` | Retrieves the user's public address. |
151+
| `getUserInfo` | Retrieves the user's information like email, name, verifier id, and more. |
152+
| `getSignatures` | Retrieves the node's signatures that are returned for request. |
153+
154+
### connected Method
155+
156+
The `connected` method can be used to check whether the user is logged in Web3Auth or not. Please
157+
note, you should call this method after the `initialize` method if you want to check the user's
158+
connection status for an existing session.
159+
160+
```swift
161+
let isConnected = singleFactoreAuth.connected()
162+
```

‎docs/sdk/core-kit/sfa-ios/initialize.mdx

+11-9
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,22 @@ description: "Web3Auth SFA Swift SDK - Initialization | Documentation - Web3Auth
66

77
import Initialization from "@site/src/common/sdk/core-kit/sfa/ios/_sfa-ios-initialization.mdx";
88

9-
After Installation, the next step to use Web3Auth is to Initialize the SDK. Please note that these
10-
are the most critical steps where you need to pass on different parameters according to the
11-
preference of your project.
9+
After Installation, the next step to use Web3Auth is to create an instance, and initialize the SDK.
10+
Please note that these are the most critical steps where you need to pass on different parameters
11+
according to the preference of your project.
1212

1313
## Parameters
1414

15-
The `SingleFactoreAuth` constructor takes an object called `SingleFactorAuthArgs` as input. The
15+
The `SingleFactoreAuth` constructor takes an object called `Web3AuthOptions` as input. The
1616
constructor parameters are listed below
1717

18-
| Parameter | Description |
19-
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
20-
| `web3AuthClientId` | Your Web3Auth Client Id from [Web3Auth Dashboard](https://dashboard.web3auth.io/). |
21-
| `network` | The Web3auth network to be used by the SDK. Supported values are `.sapphire(.SAPPHIRE_MAINNET)`, `.sapphire(.SAPPHIRE_DEVNET)`, `.legacy(.MAINNET)`, `.legacy(.TESTNET)`, `.legacy(.CYAN)`, and `.legacy(.AQUA)` |
22-
| `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. |
18+
| Parameter | Description |
19+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
20+
| `clientId` | Your Web3Auth Client Id from [Web3Auth Dashboard](https://dashboard.web3auth.io/). |
21+
| `web3AuthNetwork` | The Web3auth network to be used by the SDK. Supported values are `.SAPPHIRE_MAINNET`, `.SAPPHIRE_DEVNET`, `.MAINNET`, `.TESTNET`, `.CYAN`, and `.AQUA` |
22+
| `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. |
23+
| `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. |
24+
| `storageServerUrl?` | Specifies the storage server URL. The default value is `https://session.web3auth.io`. |
2325

2426
## Initialize SingleFactorAuth
2527

‎docs/sdk/core-kit/sfa-ios/usage.mdx

+64-18
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,15 @@ you'll see an Error message.
2222
The SingleFactorAuth instance natively provides the following methods:
2323

2424
- [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.
25+
- [logout](#logout-user) - Use to logout existing user.
26+
- [connected](#check-users-logged-in-status) - Use to check whether the user is logged in or not.
27+
- [getSessionData](#get-session-data) - This method helps to get the session data for valid session.
2728

2829
## Login User
2930

30-
To obtain a user's private key using the Web3Auth SFA Flutter SDK, you can call the `connect`
31-
method. The method accepts `LoginParams`, and returns `SFAKey`.
31+
To obtain a user's private key using the Web3Auth SFA iOS SDK, you can call the `connect` method.
32+
The method accepts `LoginParams`, and returns `SessionData`.
33+
[Please checkout the SessionData response for more details](#response).
3234

3335
### Parameters
3436

@@ -48,6 +50,7 @@ method. The method accepts `LoginParams`, and returns `SFAKey`.
4850
| `verifierId` | The verifierId used for the verification. It takes `String` as a value. |
4951
| `idToken` | The idToken of the user obtained from login provider. It takes `String` as a value. |
5052
| `subVerifierInfoArray?` | Sub verifier info. Usually used during aggregate verifier. It takes `[TorusSubVerifierInfo]` as a value. |
53+
| `serverTimeOffset?` | Specifies the server time offset in seconds. |
5154

5255
</TabItem>
5356

@@ -59,19 +62,16 @@ public class LoginParams {
5962
public let verifierId: String
6063
public let idToken: String
6164
public let subVerifierInfoArray: [TorusSubVerifierInfo]?
65+
public let serverTimeOffset: Int?
66+
public let fallbackUserInfo: UserInfo?
6267

63-
public init(verifier: String, verifierId: String, idToken: String) {
64-
self.verifier = verifier
65-
self.verifierId = verifierId
66-
self.idToken = idToken
67-
subVerifierInfoArray = nil
68-
}
69-
70-
public init(verifier: String, verifierId: String, idToken: String, subVerifierInfoArray: [TorusSubVerifierInfo]) {
68+
public init(verifier: String, verifierId: String, idToken: String, subVerifierInfoArray: [TorusSubVerifierInfo]? = nil, serverTimeOffset: Int? = nil, fallbackUserInfo: UserInfo? = nil) {
7169
self.verifier = verifier
7270
self.verifierId = verifierId
7371
self.idToken = idToken
7472
self.subVerifierInfoArray = subVerifierInfoArray
73+
self.serverTimeOffset = serverTimeOffset
74+
self.fallbackUserInfo = fallbackUserInfo
7575
}
7676
}
7777

@@ -94,18 +94,64 @@ public struct TorusSubVerifierInfo {
9494
```swift
9595
let loginParams = LoginParams(verifier: "YOUR_VERIFIER_NAME", verifierId: "YOUR_VERIFIER_ID", idToken: "YOUR_ID_TOKEN")
9696
do {
97-
let sfaKey = try await singleFactoreAuth.connect(loginParams: loginParams)
97+
let sfaKey = try await singleFactorAuth.connect(loginParams: loginParams)
98+
} catch {
99+
// Handle error
100+
}
101+
```
102+
103+
## Logout User
104+
105+
To logout the current user, you can use the `logout` method. Please note, the method will not logout
106+
the user from the authentication provider, it'll only logout and invalidate the Web3Auth session.
107+
108+
### Usage
109+
110+
```swift
111+
do {
112+
try await singleFactorAuth.logout()
98113
} catch {
99114
// Handle error
100115
}
101116
```
102117

103-
## Session Management
118+
## Check User's Logged In Status
119+
120+
You can use the `connected` method to check whether the user is logged in Web3Auth or not. Please
121+
note, you should call this method after the `initialize` method if you want to check the user's
122+
connection status for an existing session.
123+
124+
### Usage
125+
126+
```swift
127+
let isConnected = singleFactorAuth.connected()
128+
```
129+
130+
## Get Session Data
104131

105-
We have included Session Management in this SDK, so calling the initialize function to get the
106-
SFAKey value without re-logging in the user if a user has an active session will return the SFAKey,
107-
otherwise, it will throw an error.
132+
We have included Session Management in this SDK, so calling the `getSessionData` will retrive the
133+
user's `SessionData` without re-logging in the user if a user has an active session. Otherwise, it
134+
will return `nil`.
108135

109136
### Usage
110137

111-
<SessionManagement />
138+
```swift
139+
let sessionData = singleFactorAuth.getSessionData()
140+
141+
if(sessionData != nil) {
142+
// User is logged in
143+
} else {
144+
// User is not logged in
145+
}
146+
```
147+
148+
### Response
149+
150+
The `SessionData` has the following four functions to retrive the relevant session information.
151+
152+
| Function Name | Description |
153+
| ------------------ | ------------------------------------------------------------------------- |
154+
| `getPrivateKey` | Retrieves the user's private key. |
155+
| `getPublicAddress` | Retrieves the user's public address. |
156+
| `getUserInfo` | Retrieves the user's information like email, name, verifier id, and more. |
157+
| `getSignatures` | Retrieves the node's signatures that are returned for request. |

‎sidebars.ts

+5-1
Original file line numberDiff line numberDiff line change
@@ -1611,7 +1611,11 @@ const sidebars: SidebarsConfig = {
16111611
{
16121612
type: "category",
16131613
label: "Migration Guides",
1614-
items: ["migration-guides/sfa-ios-v7-to-v8", "migration-guides/sfa-ios-v2-to-v4"],
1614+
items: [
1615+
"migration-guides/sfa-ios-v8-to-v9",
1616+
"migration-guides/sfa-ios-v7-to-v8",
1617+
"migration-guides/sfa-ios-v2-to-v4",
1618+
],
16151619
},
16161620
...sdkQuickLinks,
16171621
],

‎src/common/sdk/core-kit/sfa/ios/_sfa-ios-cocoapods.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ To install the Web3Auth SingleFactorAuth SDK using Cocoapods, follow the below s
33
1. Open the Podfile, and add the SingleFactorAuth pod:
44

55
```sh
6-
pod 'SingleFactorAuth', '~> 8.0.0'
6+
pod 'SingleFactorAuth', '~> 9.0.2'
77
```
88

99
2. Once added, use `pod install` command to download the SingleFactorAuth dependency.

‎src/common/sdk/core-kit/sfa/ios/_sfa-ios-initialization.mdx

+12-4
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,21 @@
1+
The `initialize` method is responsible for authorizing the existing sessions, and initializing the
2+
SDK. If the existing session is not valid, it'll throw an error.
3+
14
```swift
25
import SingleFactorAuth
36

4-
let sfaParams = SFAParams(
5-
web3AuthClientId: "YOUR_WEB3AUTH_CLIENT_ID",
6-
network: .sapphire(.SAPPHIRE_MAINNET)
7+
let options = Web3AuthOptions(
8+
clientId: "YOUR_WEB3AUTH_CLIENT_ID",
9+
web3AuthNetwork: .SAPPHIRE_MAINNET,
10+
// Sets a session for 2 days, takes the input
11+
// in seconds.
12+
sessionTime: 172800
713
)
814

915
do {
10-
let singleFactoreAuth = try SingleFactorAuth(params: sfaParams)
16+
let singleFactoreAuth = try SingleFactorAuth(params: options)
17+
18+
try await singleFactoreAuth.initialize()
1119
} catch {
1220
// Handle error
1321
}

‎src/common/sdk/core-kit/sfa/ios/_sfa-ios-spm.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
https://github.com/Web3Auth/single-factor-auth-swift
77
```
88

9-
From the `Dependency Rule` dropdown, select `Exact Version` and enter `8.0.0` as the version.
9+
From the `Dependency Rule` dropdown, select `Exact Version` and enter `9.0.2` as the version.
1010

1111
1. When finished, Xcode will automatically begin resolving and downloading your dependencies in the
1212
background.

‎src/common/versions.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ export const pnpUnrealVersion = `4.1.x`;
88

99
export const sfaWebVersion = `8.0.x`;
1010
export const sfaAndroidVersion = `1.2.0`;
11-
export const sfaIOSVersion = `8.0.0`;
11+
export const sfaIOSVersion = `9.0.2`;
1212
export const sfaRNVersion = `2.0.x`;
1313
export const sfaFlutterVersion = `5.2.0`;
1414
export const sfaNodeJSVersion = `7.4.x`;

0 commit comments

Comments
 (0)