Project setup (Android)¶

The IDK consists of two parts: the runtime library (which contains the main logic), and the Gradle plugin (which applies user-defined theming to the IDK UI). Both parts reside in Digidentity's Maven repository.

Maven repository setup for the runtime library¶

Using the `dependencyResolutionManagement` block in the settings.gradle¶

dependencyResolutionManagement {
    repositories {
        maven {
            url 'https://jitpack.io'
        }
        maven {
            url 'https://digidentity.mycloudrepo.io/repositories/digidentity'
            credentials {
                username = "username"
                password = "password"
            }
        }
    }
}

Using the `allprojects` block in the build.gradle¶

allprojects {
    repositories {
        maven {
            url 'https://jitpack.io'
        }
        maven {
            url 'https://digidentity.mycloudrepo.io/repositories/digidentity'
            credentials {
                username = "username"
                password = "password"
            }
        }
    }
}

Note: JitPack is required for the IDK's transitive dependencies and must be explicitly specified.

Maven repository setup for the Gradle plugin¶

buildscript {
    repositories {
        maven {
            url 'https://digidentity.mycloudrepo.io/repositories/digidentity'
            credentials {
                username = "username"
                password = "password"
            }
        }
    }
    dependencies {
        classpath "com.digidentity:idk-theme-plugin:0.6.0"
    }
}

Java/Kotlin setup¶

The IDK requires at least Java 11. For that please add the following lines to the module-level build.gradle:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = '11'
    }
}

Runtime library dependency setup¶

dependencies {
    implementation "com.digidentity:idk:{idk-version}"

    implementation platform("com.google.firebase:firebase-bom:31.2.0")
    implementation "com.google.firebase:firebase-dynamic-links"
    implementation "com.google.firebase:firebase-messaging"
}

The IDK changelog can be found here.

Note: The IDK requires a set of Firebase libraries that must be explicitly specified. The example above contains a full list.

IDK theme Gradle plugin setup¶

Could be either:

plugins {
    id 'com.digidentity.idk-theme'
}

...

IDKTheme {
    sourceFile = "path-to-the-style-file.json"
}

or

apply plugin: 'com.digidentity.idk-theme'

...

IDKTheme {
    sourceFile = "path-to-the-style-file.json"
}

depending on whether you use the Gradle Plugin DSL.

Compose code generation¶

Since version 1.4.0 we have started integrating with Jetpack Compose, which requires that the IDK Theme Plugin generates Compose theme classes. This is similar to how the plugin already generates XML theme files.

As this is still at an incubating stage you can turn off Compose code generation, see the below example.

When custom fonts are specified in your style file the plugin will generate code to load them from the R class. The default R class is the one from the project that is running the plugin, but if you use non-transitive R classes then you may need to specify the correct R class to use, see the below example.

IDKTheme {
    sourceFile = "path-to-the-style-file.json"

    /**
     * Whether the plugin should generate Compose code, true by default. 
     * If the generated code is not working for you, set this to false.
     */
    composeCodeGenerationEnabled = true

    /**
     * Optional R class to use for referencing font resources. 
     * If not specified, the project's namespace will be used.
     */
    fontRClass = "com.example.myfonts.R"    
}

Push notifications setup¶

The IDK heavily relies on push notifications as a secondary communication channel, therefore they are an essential part of the setup.

Google Services Gradle plugin setup¶

Please include the following in the project-level build.config:

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.3.10'
    }
}

And on the module level apply the plugin:

apply plugin: 'com.google.gms.google-services'

Please keep in mind that the google-services.json file must be placed in the proper location.

The last step is to link FCM token updates and messages to the IDK. In case of Kotlin that would be:

import com.digidentity.idk.DigidentityIDK
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

class MessagingService : FirebaseMessagingService() {

    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        DigidentityIDK.handleNotification(
            this, 
            remoteMessage, 
            {
                Log.i("MessagingService", "IDK handled remote message.") 
            }, 
            { error: DigidentityIDKError ->
                Log.e("MessagingService", "IDK could not handle remote message.", error) 
            }
        )
    }

    override fun onNewToken(newToken: String) {
        DigidentityIDK.handleNewFirebaseToken(newToken)
    }

}

In case of Java add the following class:

import androidx.annotation.NonNull;

import com.digidentity.idk.DigidentityIDK;
import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;

public class MessagingService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
        DigidentityIDK.handleNotification(
            this, 
            remoteMessage,
            () -> { 
                Log.i("MessagingService", "IDK handled remote message.") 
            },
            (DigidentityIDKError error) -> { 
                Log.e("MessagingService", "IDK could not handle remote message.", error) 
            },
        );
    }

    @Override
    public void onNewToken(@NonNull String newToken) {
        DigidentityIDK.handleNewFirebaseToken(newToken);
    }

}

After that add the declaration of that service to your manifest file:

<service
    android:name=".MessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Minification setup¶

If using optimisers (ProGuard or R8), add the following lines to your rules:

-keep class com.digidentity.sdk.** { *; }
-keep class com.digidentity.idk.** { *; }
-keep class com.digidentity.bioldsdk.** { *; }

Apps built with AGP 7.1.x or 7.2.x use R8 versions 3.1.x and 3.2.x and they are known to cause runtime crashes in our 3D renderer when optimization is enabled. If using R8 with optimization enabled, please ensure that R8 is version 3.3.70 or higher:

buildscript {
    dependencies {
        // upgrade R8 as workaround for crash in Digidentity’s 3D rendering code 
        // (not needed if you are using AGP 7.3.0 or higher)
        classpath 'com.android.tools:r8:3.3.75'
    }
}

App check setup¶

To protect backend resources from abuse, the IDK relies on Firebase App Check, which in turn relies on Google Play Integrity. Please refer to the Google documentation to support this function in the mobile app.

Google Play configuration¶

Enable Play Integrity on Google Play Console

Go to App Integrity, open the Integrity API tab
Link your app project with Firebase
Consider raising your usage tier for the Integrity API.

Firebase configuration¶

The rest of the preparations are done in App Check section of Firebase console

Register your apps to use App Check with the Play Integrity provider:

Under App Check, open Apps and for each application using IDK do the following:
- Select app and press Play Integrity.
- In the expanded section, attach the SHA hash of your signing certificate.
- Set TTL to 30 minutes.
- Save the changes.

After configuration is completed, IDK will be able to perform App Check. No code changes required.

Consider raising your usage tier for the Integrity API¶

Please assess if the standard usage tier of the Play Integrity API is enough for your app.

The Digidentity IDK performs an integrity check once per hour.
If you have a high number of daily active users and/or long user sessions then you might exceed the standard limit of 10,000 daily API calls. You can find more information at Integrity API usage tiers.

If you need to raise the usage tier then you can use the below answers to fill out the contact form for increasing the maximum number of daily requests:

Q. How are you calling the Play Integrity API?
A. third party service I'm using in my app is calling the API, please specify: Digidentity IDK

Q. What type of API calls are you making?
A. Classic requests

Q. How often will you call the API for each user?
A. Once per hour

Q. Is there any PII or SPII used for the nonce
A. No

Q. How are you validating Play Integrity API responses?
A. Other: Firebase App Check

Q. How does your app retry in case of Play Integrity API errors
A. Other: The user can retry manually

Q. How will your app act when the Play Integrity API detects risky traffic?
A. Deny access to functionality