Skip to main content
This page takes you from an empty project to your first test webhook. It uses your test key and the demo platform zktls-demo, so you need no real account anywhere, and an emulator is enough.

Before you start

  • Your test key (zk_test_…) from Register your app.
  • A webhook endpoint that checks the signature, and its signing secret. Webhooks has the code for Node and Python. The URL must be public HTTPS. To try it on your own machine, run that code and expose it with a tunnel, for example cloudflared tunnel --url http://localhost:3000, then set the webhook you registered to the tunnel’s URL plus the sample’s path, for example https://<name>.trycloudflare.com/webhooks/cr3dentials. Change that webhook’s URL rather than adding a new one: its signing secret stays the same. A quick tunnel gets a new URL each time it starts, so update the webhook after a restart.
  • Android 7.0 (API 24) or later, with compileSdk 36.
  • Kotlin 2.1 or later. The AAR carries Kotlin 2.2 metadata.
The AAR includes the native core for arm64-v8a, armeabi-v7a, x86_64 and x86. Its 64-bit libraries are 16 KB-page aligned for Android 15 and later.

1. Install

From mavenCentral(), which Android projects include by default:
The AAR merges its permissions, its foreground service and its R8 keep rules into your app. You don’t need extra ProGuard rules. It brings JNA, kotlinx-coroutines, androidx.webkit, Google Play Integrity and the Kotlin standard library as Maven dependencies, each under its own licence. The files on Maven Central are signed with the Cr3dentials OpenPGP key, fingerprint E8588B38D6FDCC59E6C03011AE4CC59A87AD0C0B.

2. Configure

Call Zktls.configure once, when your app starts, in your Application class:
Name the class in your manifest’s <application android:name=".YourApp">. The app key is publishable, so it can live in your code or your build config. Use the test key in debug builds and the live key in release builds.

3. Verify

Zktls.verify is a suspend function. Pass it the activity on screen, the platform ids and your reference. It shows the SDK’s screens as dialogs over that activity, and returns when the user leaves the flow:
lifecycleScope comes from androidx.lifecycle:lifecycle-runtime-ktx, which Android Studio’s new projects include. Any coroutine scope works. The outcome tells your app only how each platform ended. The results go to your server, by webhook. Don’t wait in the app for them: show your own next step as soon as verify returns. The fields are in The outcome, and the refusal codes are in Errors. To finish later, call verify again with the platforms that were not started. It is a new verification, and you can pass the same reference:
To start from your server, have your server create a token with POST /partner/verification-tokens and pass it to the app. The token carries the platforms and the reference:

4. Test with zktls-demo

1

Run your app

Run it on an emulator or a phone, with your test key, and tap the button that calls verify(activity, listOf("zktls-demo"), reference).
2

Go through the screens

Tap Start on the intro, then Continue on the sign-in notice.
3

Sign in to the demo bank

Enter any user name and the password demo, which the page shows.
4

See the outcome

The SDK hands the run to an attester and shows All done. verify returns with zktls-demo as PlatformStatus.DONE.
5

Get the webhooks

Within seconds, your endpoint receives a platform.finished with "test": true and the demo bank’s latest transfer, and a verification.finished, in either order. Both carry your reference.
Zktls.configure hasn’t run before verify. Call it in Application.onCreate, and check that the manifest names your Application class.
Read the code you caught in Errors. With a test key, platform_unavailable means a platform other than zktls-demo.
Check that your webhook is Active in the Partner Portal and returns a 2xx, and look under Webhooks → Logs. If your endpoint answers 4xx because the signature check fails, check the secret and that you sign the raw body (Webhooks).

5. Theme and strings

The layout of the screens is fixed. You set the colours, the logo and the wording, when you configure:
Colours are ARGB colour ints, such as ContextCompat.getColor(this, R.color.brand), and logo is a drawable resource id. A null, or ZktlsTheme() with no arguments, keeps the SDK’s own look. English ships built in. Override any string by its key, for example with your own translations. Words in braces are filled in by the SDK, so keep them in your text:

Things to know

  • The screens. They are dialogs over the activity you pass. The SDK has no activity of its own, so keep that activity in front until verify returns.
  • Stopping. Not now on the intro, Stop here between platforms, Cancel on the sign-in notice, or closing a sign-in page or pressing Back on it, each end the flow. The platform the user was on, and every later one, are not started.
  • Where the page may go. The sign-in page stays on the platform’s domains and on the third-party sign-in providers the platform uses. If the user follows a link anywhere else, that platform ends as failed.
  • Your app’s web data. On Android System WebView 123 and later, each run has its own WebView profile. On older WebViews, the run wipes your app’s WebView cookies, web storage and cache before and after, so don’t start a verification while your own WebViews’ data matters.
  • The foreground service. The SDK runs its shortService, ZkTlsSessionService, during each hand-off. You add no lifecycle code.
  • The notification. It reads “Verifying”, in a channel named “Verification”. To translate or rebrand it, define zktls_session_notification_title, zktls_session_channel_name and the drawable zktls_session_notification_icon in your app’s resources.
  • Logging. Log the verificationId, the statuses, the reasons and the refusal codes. Your Partner API key and webhook secret never belong in the app at all.

Before you submit

  • Live keys need Play Integrity. A live key works only in a build installed from Google Play (an internal testing track is enough), on a device with Google Play services that passes Play’s device integrity check. Builds installed from Android Studio or as an APK, emulators, and phones without Google Play services show “This device can’t be verified” and throw device_not_verified. To try a live key with a build from Android Studio on a phone with Google Play services, ask us to allow development builds for your app; we turn it off before your release. Develop with the test key, and try the live key with an internal testing build on a phone.
  • Your registered app. The build’s package name must be the one you registered with us.
  • The live key in release builds. A test key in a release build runs only zktls-demo.
  • The manifest. The SDK adds INTERNET, ACCESS_NETWORK_STATE and FOREGROUND_SERVICE (type shortService). It asks for no runtime permission.
Work through the release checklist for the Google Play Data safety answers and the foreground service declaration.