JustPassMe Android SDK 🚀

JustPassMe is an awesome authentication library that lets you register and authenticate users using passkeys. Passkeys are secure and convenient ways to log in without passwords. No more forgetting passwords or resetting them every time! 😎

Setup 🛠

To use JustPassMe in your Android app, you need to

Create an organization in the JustPassMe dashboard and add the following details :

Add the Application Package Name to your organization in the JustPassMe dashboard:
- Navigate to your organization's settings page in the JustPassMe dashboard -> android app info
- locate the "Application Package Name" & “Android signatures” field and enter the package name for your application. Example (com.example.myapp)
- Add the SHA-256 fingerprint for your application in the “Android signatures” to your organization in the JustPassMe dashboard:
  - Open terminal and head to project root
  - Type this command cd android
  - Make sure gradle is 7.5.0 or more
  - Android Studio -> Settings -> Build, Execution, Deployment -> Build Tools -> Gradle -> download gradle 18 or higher
  - Type this command ./gradlew signingReport
  - Example: If your SHA-256 fingerprint is "A1:B2:C3:D4:E5:F6:G7:H8:I9:J1:K2:L3:M4:N5:O6:P7:Q8:R9:S1"
Bind your verification assets into your your app's build.gradle file:

android {
    defaultConfig {
        resValue("string", "host", "https://<YOUR_ORGANIZATION_ID>.accounts.justpass.me")
        resValue("string", "asset_statements", """
           [{
             "include": "https://<YOUR_ORGANIZATION_ID>.accounts.justpass.me/.well-known/assetlinks.json"
           }]
        """)
    }
}

Sync your project with Gradle files then add the following meta-data to your <application> tag in AndroidManifest.xml file:

<manifest>
    <application>
        <meta-data
            android:name="asset_statements"
            android:resource="@string/asset_statements" />
     </application>
</manifest>

Build your project to make the resValue generated in R class, it should build successfully.
(Optionl) You can validate your assetlinks.json is working by opening this link https://<YOUR_ORGANIZATION_ID>.accounts.justpass.me/.well-known/assetlinks.json in your browser and make sure your android package and SHA-256 fingerprint are listed in the file.
Start your backend integration, checkout our Backend Documentation By the end of this step you should have your passkey registration and login APIs ready to use in your app.

Installation 📥

To install JustPassMe in your Android app, you just need to add the following dependency to your app's build.gradle file:

implementation("tech.amwal.justpassme:justpassme:1.0.0-beta06")

Note : This is a beta version of the library and the API design may change before the stable release. Stay tuned for updates! 🔥

Getting Started 🏁

To use JustPassMe in your app, you need to do the following:

Create a JustPassMe instance with the activity as a parameter:

val justPassMe : JustPassMe = JustPassMe(activity)

After finishing the backend integration, you will need to know the API endpoints for both registration and login, Incase of using Firebase as your backend, checkout our Firebase Documentation your endpoints will be as follows:
- Backend
```
const val BASE_URL = "https://<YOUR_backend_DOMAIN>"
```
- Firebase
```
const val BASE_URL = "https://<YOUR_FIREBASE_PROJECT_ID>.cloudfunctions.net/ext-justpass-me-oidc/"
```

Registration 📝

To create a passkey for your logged in user, you need to do the following:

Construct the registration URL by getting it from your backend, incase of Firebase it will be appending "/register" to the BASE_URL:
- Backend
```
val registrationUrl = "${BASE_URL}/<YourRegistrationEndpoint>"
```
- Firebase
```
val registrationUrl = "${BASE_URL}/register"
```
Get your logged user's token or any Id that you wish to be retuned when the user login with Passkeys later.
- Note Incase of Firebase pass your currentUser token, checkout our Firebase Documentation
Required: Pass your token as a header value with the key “Authorization” and the prefix “Bearer” in a map like this:

val headers = mapOf("Authorization" to "Bearer $token")

Call the register method on the justPassMe instance and pass the registration URL, the headers map, and a callback function as parameters:

justPassMe.register(registrationUrl, headers){ authResponse ->
     when (authResponse) {
        is AuthResponse.Success -> {
            // Passkey was created
            }
        is AuthResponse.Error -> {
            // Reason behind the faliure
            authResponse.error
        }
     }
}

The callback function receives an authResponse object that represents one of two cases:

Success : A new passkey was created for the user and they can now log in with it. Hooray! 🙌
Error : An error message shows the reason behind the failure. Don’t worry, we’ll help you fix it! 💪

Login 🔑

To log in a user that has a passkey for your app, you need to do the following:

Construct the login by getting it from your Backend Endpoints, Incase of Firebase you get the URL by appending "/authenticate" to the BASE_URL:
- Backend
```
val loginUrl = "${BASE_URL}/<YourLoginEndpoint>"
```
- Firebase
```
val loginUrl = "${BASE_URL}/authenticate"
```
(Optional) IIf you want to pass any extra headers while logging in the user, you can create a map with the header key-value pairs like this:

val extraHeaders = mapOf("Header-Key" to "Header-Value")

Call the auth method on the justPassMe instance and pass the login URL, the extra headers map (if any), and a callback function as parameters:

justPassMe.auth(loginUrl, extraHeaders){ authResponse ->
     when (authResponse) {
        is AuthResponse.Success -> {
            // User loggedIn with passkey
            // You can use your token
            authResponse.token
            }
        is AuthResponse.Error -> {
            // Reason behind the faliure
            authResponse.error
        }
     }
}

The callback function receives an authResponse object that represents one of two cases:

Success: The user logged in with passkey successfully and you can use their token. Awesome! 😊
Error: An error message shows the reason behind the failure. Oops! 😬

That’s it! You have successfully integrated JustPassMe in your app and made it easier for your users.

iOS React Native