Android
Initial Setup
The LoginID Android SDK enables you to add passkey authentication in your native Android application without having to redirect the user to any pages outside your application.
The SDK leverages the Credential Manager API for creating and syncing passkeys with Google Password Manager.
Required settings:
- Host Digital Asset Links JSON file
- Tenant Base URL
- Application ID
The LoginID Android Mobile SDK requires Android 9+ (API 28+) for compatibility.
Configure assetlinks.json File
To make your app work with the SDK, you need to link your app to your website. This is done by using a file called Digital Asset Links. You must create this file and then place it on your website.
Find package name
If you need to find the package name of your Android app you can find it in your app's build.gradle
file under the defaultConfig
section.
Generate SHA-256 Fingerprint of Your App's Signing Key
The SHA256 fingerprint is a unique hash value generated from the app's certificate, which is used to identify the app's authenticity and integrity.
You can find your app's SHA256 fingerprint by using the keytool utility that comes with the Java Development Kit (JDK). And run the following command while replacing KEYSTORE_PATH
with the path to your keystore file, KEYSTORE_ALIAS
with your key alias, KEYSTORE_PASSWORD
and KEY_PASSWORD
are replaced with the actual passwords for your keystore and key.
keytool -list -v -keystore KEYSTORE_PATH \
-alias KEYSTORE_ALIAS \
-storepass KEYSTORE_PASSWORD \
-keypass KEY_PASSWORD
This command will output various certificate information, including the SHA256 fingerprint.
The keytool command can be found at $JAVA_HOME/bin if it isn't globally available.
When you're developing an app locally, it's simpler to use your default debug keystore for testing purposes. Find where your debug keystore is located and run the command on that.
Replace the arguments with the default values for the debug keystore.
- KEYSTORE_ALIAS: androiddebugkey
- KEYSTORE_PASSWORD: android
- KEY_PASSWORD: android
In a production environment, you should opt for a dedicated keystore. If you need to find your SHA256 fingerprint, especially for Google Play Console related tasks, you can do so directly within the Google Play Console.
Host assetlinks.json
file on Your Website Directory
Host the file under the correct path <WEBSITE_DOMAIN>/.well-known/assetlinks.json
in the root directory of your website.
Here is an example of the minimum required fields in the file:
[
{
relation: [
"delegate_permission/common.handle_all_urls",
"delegate_permission/common.get_login_creds",
],
target: {
namespace: "android_app",
package_name: "<PACKAGE_NAME>",
sha256_cert_fingerprints: ["<SHA256_FINGERPRINT>"],
},
},
];
Use the following example as a template and replace PACKAGE_NAME
and SHA256_FINGERPRINT
with your values.
Declare Association in the Android App
To associate your Android app, update your strings.xml
file with the website's URL.
<resources>
<string name="asset_statements" translatable="false">
[{
\"include\": \"<WEBSITE_DOMAIN>/.well-known/assetlinks.json\"
}]
</string>
</resources>
Then modify the AndroidManifest.xml
to include a meta-data element referencing this URL.
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
...
<application
...
<meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
...
</application>
</manifest>
Create Web Application
Create a new tenant to obtain the tenant base URL
and application ID
.
Add SDK to Existing Application
Create an SDK Instance
- Java
- Kotlin
import services.LoginIDService
//...
public class MyApplication extends AppCompatActivity {
private LoginIDServiceConfig config = new LoginIDServiceConfig(
"<BASE_URL>",
"<APP_ID>"
);
private LoginIDService loginIdService = new LoginIDService(config);
protected void onCreate() {
super.onCreate();
// any other configurations
// ...
// ...
}
}
import services.LoginIDService
//...
class MyApplication : Application() {
private val config = LoginIDServiceConfig(
"<BASE_URL>",
"<APP_ID>"
)
private val loginIdService = LoginIDService(config)
override fun onCreate() {
super.onCreate()
// any other configurations
// ...
// ...
}
}
API Reference
registerWithPasskey
Sign up a user for passkey authentication.
public void registerWithPasskey(
@NonNull final Activity activity,
@NonNull final String username,
@Nullable final CreatePasskeyOptions options
)
Where:
CreatePasskeyOptions {
mfa: string[]
token: string
displayName: string
usernameType: string
}
Parameter | Type | Required | Details |
---|---|---|---|
activity | Activity | true | The context used to launch any UI needed; use an activity context to make sure the UI will be launched within the same task stack. |
username | String | true | Username of the customer to be registered. |
options | CreatePasskeyOptions | false | Additional options for the sign-up process. |
options.mfa | List<String> | false | Pass a mfa signup option with your passkey. |
options.token | String | false | Pass your authorization token if your application is protected. |
options.displayName | String | false | A human-palatable name for the user account, intended only for display on your passkeys and modals. |
options.usernameType | String | false | Specify username type validation. |
authenticateWithPasskey
Sign in a previously registered user with a passkey.
public void authenticateWithPasskey(
@NonNull final Activity activity,
@NonNull final String username,
@Nullable final GetPasskeyOptions options
)
Where:
GetPasskeyOptions {
token: string;
usernameType: string;
}
Parameter | Type | Required | Details |
---|---|---|---|
activity | Activity | true | The context used to launch any UI needed; use an activity context to make sure the UI will be launched within the same task stack. |
username | String | true | Username of the customer to sign-in with. |
options | GetPasskeyOptions | false | Additional options for the sign-in process. |
options.token | String | false | Pass your authorization token if your application is protected. |
options.usernameType | String | false | Specify username type validation. |
Errors
LoginIDError
Can occur during the authentication process. It is designed to encapsulate detailed information about login-related errors, making it easier to handle and debug issues related to user authentication.
Field | Type | Details |
---|---|---|
msgCode | string | The error code associated with the login error. Defaults to unknown_error . |
msg | string | The detailed message or description of the error. Defaults to unknown error . |