Skip to content

Commit 4d5bbf1

Browse files
wilwadewilwade
authored
Refactor the SDK Documentation to separate pages and apply feedback (#289)
# Problem Updates the documentation around the SDKs Closes #234 # Solution - Split up the documentation for the platforms - Updated mdbook - Fixed a grammatical issue in the Response.md file - Updated the Quick Start to reference the Button SDKs
1 parent 4208bd4 commit 4d5bbf1

File tree

9 files changed

+165
-163
lines changed

9 files changed

+165
-163
lines changed

‎.github/workflows/common/set-up-mdbook/action.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ runs:
1111
uses: jontze/action-mdbook@0765bef0c7c5792f93bf3ed3d487a0ca32c9da33
1212
with:
1313
token: ${{ inputs.token }}
14-
mdbook-version: "0.4.42" # Use a semver compatible string
14+
mdbook-version: "0.4.47" # Use a semver compatible string
1515
# Optional Plugins have to be enabled
1616
# use-linkcheck: true
1717
# linkcheck-version: "~0.7.7"

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ Releases are made via GitHub Releases with tags in the style: `vX.Y.Z`.
9292

9393
#### Mobile App Development
9494

95-
To learn more about using SIWF in your mobile app, see: [`docs/MobileAppSDK.md`](./docs/MobileAppSDK.md)
95+
To learn more about using SIWF in your mobile app, see: [`docs/SDK/Overview.md`](./docs/SDK/Overview.md)
9696

9797
<!-- CONTRIBUTING -->
9898

‎docs/src/Actions/Response.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Response Sections
2424

2525
- `userPublicKey`: The key for the user signing this request
2626
- `payloads`: Signed payloads from the user
27-
- `credentials`: User approved verified credentials from Frequency Access (or other SIWF-compatible services) such as email, phone, user keys, etc...
27+
- `credentials`: User-approved, verified credentials from Frequency Access (or other SIWF-compatible services) such as email, phone, user keys, etc...
2828

2929
### `userPublicKey`
3030

‎docs/src/MobileAppSDK.md

Lines changed: 0 additions & 153 deletions
This file was deleted.

‎docs/src/QuickStart.md

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,7 @@ For website interactions, just forward the user to the returned `authenticationU
4444

4545
## Step 2 (Android/iOS): Forward the User to an Embedded Browser
4646

47-
For mobile applications, it is recommended to use an embedded browser and set the `callbackDomain` in the `signedRequest` and the `callbackPath` to your application's Universal Link. This ensures that the user remains within the application environment and does not have to leave the app.
48-
49-
For more details, refer to the official documentation:
50-
51-
- [SafariViewController for iOS](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller)
52-
- [Chrome Custom Tabs for Android](https://developer.chrome.com/docs/android/custom-tabs/)
47+
[SDKs are provided](/SDK/Overview.md) for Android and iOS to perform the correct redirects and callback setups using the proper interactions specific to these platforms.
5348

5449
## Step 3: Callback Processing
5550

‎docs/src/SDK/Android.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Android SIWF SDK
2+
3+
## Quick Reference
4+
5+
- [SIWF Android SDK Source Code + Demo App](https://github.com/ProjectLibertyLabs/siwf-sdk-android)
6+
- [Maven Central Package](https://central.sonatype.com/artifact/io.projectliberty/siwf) `implementation("io.projectliberty:siwf:1.0.0")`
7+
8+
## 1. Installation
9+
10+
### Requirements
11+
- Android API level **24** or later
12+
- Java **11+**
13+
14+
### Installing the SIWF SDK
15+
To install the SIWF SDK via **Gradle**, add the following to your `build.gradle` file:
16+
17+
```gradle
18+
dependencies {
19+
implementation 'io.projectliberty:siwf:1.0.0'
20+
}
21+
```
22+
23+
[Maven Central Pacakge Page](https://central.sonatype.com/artifact/io.projectliberty/siwf)
24+
25+
26+
## 2. Displaying the SIWF Button
27+
28+
To create a SIWF Button in your Android app, use:
29+
30+
```kotlin
31+
import io.projectliberty.siwf.Siwf
32+
import io.projectliberty.models.SiwfButtonMode
33+
34+
Siwf.CreateSignInButton(
35+
mode = SiwfButtonMode.PRIMARY,
36+
authRequest = authRequest
37+
)
38+
```
39+
40+
## 3. Handling Authorization Callbacks
41+
42+
Update your `AndroidManifest.xml` with your own intent filters for authentication callbacks. Example:
43+
44+
```xml
45+
<activity
46+
android:name="io.projectliberty.helpers.AuthCallbackActivity"
47+
...
48+
<intent-filter android:autoVerify="true">
49+
...
50+
<data
51+
android:scheme="http"
52+
android:host="localhost"
53+
android:port="3000"
54+
android:path="/login/callback" />
55+
</intent-filter>
56+
<intent-filter android:autoVerify="true">
57+
... or ...
58+
<data
59+
android:scheme="siwfdemoapp"
60+
android:host="login" />
61+
</intent-filter>
62+
</activity>
63+
```
64+
65+
Then, use a `BroadcastReceiver()` to receive the authorization code with `AuthConstants.AUTH_INTENT_KEY`.
66+
67+
## 4. Process Authorization Code
68+
69+
On your backend service, process the authorization code and start your session.
70+
71+
Resources:
72+
- [SIWF Documentation on Processing a Result](https://projectlibertylabs.github.io/siwf/v2/docs/Actions/Response.html)
73+
- [Frequency Gateway SSO Tutorial](https://projectlibertylabs.github.io/gateway/GettingStarted/SSO.html)

‎docs/src/SDK/Overview.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Sign-In With Frequency (SIWF) SDK Integration Guide
2+
3+
The SIWF SDK provides a seamless authentication experience for your applications.
4+
These guides will walk you through integrating the SIWF SDK into your **iOS** or **Android** app.
5+
6+
### Platform Specific SDK Guides
7+
8+
- [Android](/SDK/Android.md)
9+
- [iOS](/SDK/iOS.md)
10+
11+
---
12+
13+
## General Overview
14+
15+
### 1. Installation
16+
17+
Add the platform specific package to your project.
18+
19+
### 2. Displaying the SIWF Button
20+
21+
The SIWF Button creation will require the [Signed Request Payload](/Actions/Start.html#step-1-generate-the-signed-request-payload) in either `base64url` encoded or structured form.
22+
You may also specify other options such as the button style (light/dark) and the network (Mainnet/Testnet) to use.
23+
24+
### 3. Handling Authorization Callbacks
25+
26+
You will need to create a redirect handler to receive the information from the Authorization.
27+
This is the redirect URL provided to the Signed Request Payload.
28+
That handler will receive the information Once the authorization is complete that can then be send and processed by your backend and initate the session.
29+
30+
See the platform specific details for how to create the callback handler.
31+
32+
### 4. Process Authorization Code
33+
34+
On your backend service, process the authorization code and start your session.
35+
The [Frequency Gateway Account Service](https://projectlibertylabs.github.io/gateway/GettingStarted/SSO.html) supports directing sending the result from the authorization process for processing.
36+
37+
Resources:
38+
- [SIWF Documentation on Processing a Result](https://projectlibertylabs.github.io/siwf/v2/docs/Actions/Response.html)
39+
- [Frequency Gateway SSO Tutorial](https://projectlibertylabs.github.io/gateway/GettingStarted/SSO.html)

‎docs/src/SDK/iOS.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# iOS SIWF SDK
2+
3+
## Quick Reference
4+
5+
- [SIWF iOS SDK Source Code + Demo App](https://github.com/ProjectLibertyLabs/siwf-sdk-ios)
6+
- [Swift Package](https://swiftpackageindex.com/ProjectLibertyLabs/siwf-sdk-ios) `https://github.com/ProjectLibertyLabs/siwf-sdk-ios.git`
7+
8+
## 1. Installation
9+
10+
### Requirements
11+
- iOS 15.0 or later
12+
- Swift Package Manager
13+
14+
### Installing the SIWF SDK
15+
You can install the SIWF SDK via **Swift Package Manager (SPM)**:
16+
17+
1. Open Xcode and navigate to **File → Add Packages**.
18+
2. Enter the repository URL:
19+
```
20+
https://github.com/ProjectLibertyLabs/siwf-sdk-ios.git
21+
```
22+
3. Select the latest stable version and add it to your project.
23+
24+
[Xcode Documentation Reference](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app)
25+
26+
## 2. Displaying the SIWF Button
27+
28+
To create a SIWF Button, use the `Siwf.createSignInButton` method:
29+
30+
```swift
31+
import Siwf
32+
33+
Siwf.createSignInButton(mode: .primary, authRequest: authRequest)
34+
```
35+
36+
## 3. Handling Authorization Callbacks
37+
38+
Use `onOpenURL` and `Siwf.handleRedirectUrl` to handle deep links and retreive the authentication code.
39+
40+
## 4. Process Authorization Code
41+
42+
On your backend service, process the authorization code and start your session.
43+
44+
Resources:
45+
- [SIWF Documentation on Processing a Result](https://projectlibertylabs.github.io/siwf/v2/docs/Actions/Response.html)
46+
- [Frequency Gateway SSO Tutorial](https://projectlibertylabs.github.io/gateway/GettingStarted/SSO.html)

‎docs/src/SUMMARY.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,6 @@
1313
- [Delegations](Delegations.md)
1414
- [Payloads](Payloads.md)
1515
- [Data Structures](DataStructures/All.md)
16-
- [Mobile SDK](MobileAppSDK.md)
16+
- [SIWF SDK](SDK/Overview.md)
17+
- [Android](SDK/Android.md)
18+
- [iOS](SDK/iOS.md)

0 commit comments

Comments
 (0)