FAQ and troubleshooting
What is the minimum Android version?
Section titled “What is the minimum Android version?”Android 7.0 (API 24): minSdk = 24. The sample app is built with a Java 17 toolchain. See Installation.
Gradle can’t resolve com.techsign:rkyc-cnn or returns 401.
Section titled “Gradle can’t resolve com.techsign:rkyc-cnn or returns 401.”The SDK is in Techsign’s private Maven repository. Check that the repository is declared with name = "techsign" and credentials(PasswordCredentials::class), and that techsignUsername and techsignPassword are set in ~/.gradle/gradle.properties (or as ORG_GRADLE_PROJECT_techsignUsername / ORG_GRADLE_PROJECT_techsignPassword on CI). Never put them in the repository.
Can I use the SDK with Kotlin?
Section titled “Can I use the SDK with Kotlin?”Yes. The SDK is a Java library and works with Kotlin directly. Every page shows Kotlin and Java, and the Quickstart wraps the callbacks in coroutines:
val result = proveId<CheckIdReturnModel> { ServerCall.verifyIDPhoto(CheckIDModel(base64, transactionId), it) }Can I test on the emulator?
Section titled “Can I test on the emulator?”Only partly. Document capture and liveness need a real camera, and the NFC step needs a phone with NFC. Test the full flow on real devices.
The camera screen is black or the models don’t load.
Section titled “The camera screen is black or the models don’t load.”Request the CAMERA permission at runtime before showing the screen, and make sure noCompress includes tflite and lite. Call startCapture() (document) or startFaceCapture() (liveness, hologram) after the fragment is added.
Does it work with Jetpack Compose?
Section titled “Does it work with Jetpack Compose?”The camera screens are Fragments. Host them in a FragmentContainerView (for example inside AndroidView) or in a Fragment-based screen of your app.
Tokens and security
Section titled “Tokens and security”Where do I put my Prove ID API credentials?
Section titled “Where do I put my Prove ID API credentials?”Only on your server. The app gets a token from your server after the user signs in to your app, and passes it to the SDK with Authentication.setApiKey(token). See Authentication.
A call fails with UnauthorizedException (401). What should I do?
Section titled “A call fails with UnauthorizedException (401). What should I do?”The token has expired or is invalid. Ask your server for a new one, call Authentication.setApiKey(newToken) (and update your own HTTP client), then retry the step that failed.
Can I store the token to reuse it later?
Section titled “Can I store the token to reuse it later?”No. Keep it in memory for the current verification and clear it with Authentication.setApiKey(null) when the flow ends.
Where should I decide whether the user is verified?
Section titled “Where should I decide whether the user is verified?”On your server. Send the transactionId to your server, check that it belongs to the signed-in user, and read the result with GET /id/id-info-with-tid/{transactionId}. See Results.
How long are document images and videos kept on the device?
Section titled “How long are document images and videos kept on the device?”They shouldn’t be kept at all. Images stay in memory as Bitmaps; delete video files as soon as they have been sent, also when sending fails.
Which calls need my own HTTP client?
Section titled “Which calls need my own HTTP client?”Only chip authentication (/id/ca/prepare, and /id/validate-and-save with the chip authentication fields) and sending the photocopy check result. Everything else is in ServerCall. Use the same token.
Which phones can read the ID card chip?
Section titled “Which phones can read the ID card chip?”Phones with NFC. Check with NfcAdapter.getDefaultAdapter(context) != null, and ask the user to turn NFC on when isEnabled is false. Hide the NFC step on phones without NFC.
Reading fails with AuthenticationFailed or ConnectionError.
Section titled “Reading fails with AuthenticationFailed or ConnectionError.”The document moved or is too far from the antenna. Ask the user to remove the phone case, place the document against the back of the phone and hold it still until reading finishes. Set isoDep.timeout = 60_000.
Reading fails with InvalidMrzKey.
Section titled “Reading fails with InvalidMrzKey.”The serial number, date of birth or expiry date doesn’t match the chip. Show the values read from the document and let the user correct them.
What date format does the NFC reader expect?
Section titled “What date format does the NFC reader expect?”read() takes java.util.Date values. The document capture result gives the dates as dd.MM.yyyy; parse them with a non-lenient SimpleDateFormat("dd.MM.yyyy", Locale.US).
Should I use chip authentication?
Section titled “Should I use chip authentication?”Yes, if your risk policy needs proof that the chip isn’t cloned. It needs a small backend call during reading; see Chip authentication.
Liveness
Section titled “Liveness”Which gesture should I ask for?
Section titled “Which gesture should I ask for?”The one in gestureType from the transaction start: EYE, MOUTH, HEAD-VERTICAL, HEAD-HORIZONTAL, or MULTIDIR_… for several head directions. See Liveness.
I set GESTURE_TYPE but onVideoCaptured is never called.
Section titled “I set GESTURE_TYPE but onVideoCaptured is never called.”With gesture control on (IS_GESTURE_CONTROL_ENABLED = true) the video arrives in GestureListener.gestureControlled(model) as model.videoPath. onVideoCaptured is used for passive video only.
A setting from a previous run is still active.
Section titled “A setting from a previous run is still active.”LivenessBaseFragment settings are static. Set all of them before every create().
onMultiFaceDetected or onVideoCanceled is called.
Section titled “onMultiFaceDetected or onVideoCanceled is called.”More than one face is in the frame, or the face left the frame during recording. Ask the user to be alone in the frame and keep their face inside the oval, then start again with startFaceCapture().
Coverage and open questions
Section titled “Coverage and open questions”What isn’t covered in these guides yet?
Section titled “What isn’t covered in these guides yet?”These topics appear in the sample apps or the API Reference but are not walked through here yet. Use the API Reference (and ask Techsign) rather than inventing a mobile flow:
- International document templates (
getCountryTemplates,checkTemplateIDCard,addSecondaryTemplate) transferTransaction- Trust Engine / blacklist
- Voice approval (
POST /face/verify-with-voice) - Client settings
Token and role questions for your Prove ID contact
Section titled “Token and role questions for your Prove ID contact”Confirm before go-live (see Security model):
- Whether a
client_credentialstoken from/oauth/access_tokenis accepted for the mobileid/*/face/*calls you need (sample apps use username/password login for demos). - Whether a transaction-scoped token can be issued to the device.
- Which least-privilege API roles exist for the mobile flow.
- Control list and recommended pass/fail thresholds for your organisation.