@cr3dentials/zktls-react-native is a thin bridge over the native iOS and Android SDKs: the native SDK does the work, and JavaScript drives it through one API on both platforms. This page takes you from an empty project to your first test webhook, with your test key and the demo platform zktls-demo, so you need no real account anywhere.
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.
- React Native 0.80 or later, with the New Architecture: the bridge is a Turbo Module.
- iOS 14.0 or later, and Android 7.0 (API 24) or later, as the native SDKs require.
1. Install
Podfile, because CocoaPods takes a pod from the first source that has it, then run pod install:
Expo
The package’s config plugin writes those two sources into the Podfile, soexpo prebuild can regenerate it. Add the plugin to app.json (or app.config.js), then prebuild:
2. Configure
CallZktls.configure once, when your app starts:
3. Verify
Zktls.verify takes the platform ids and your reference, and resolves when the user leaves the flow:
verify resolves. 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:
4. Test with zktls-demo
1
Run your app
Run a development build on a simulator, an emulator or a phone, with your test key, and tap the button that calls
Zktls.verify(['zktls-demo'], reference).2
Choose the demo platform
Tap it on the platform list. On its consent screen, tick both boxes and tap Continue to verification.
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 the list shows the platform as Verified. Tap Done:
verify resolves with zktls-demo as '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.5. Theme and strings
configure also takes a theme and the screens’ words:
#RRGGBB or #AARRGGBB (alpha first). logo names an image in your app: an Android drawable and an iOS asset of that name. A field you leave out keeps the SDK’s default. The platform list and the consent screens are in Cr3dentials’ colours, with your logo at the top; your colours apply to the refusal screen.
The string keys are the native SDK’s, the same on both platforms: see the table on the iOS or Android page. Keep the words in braces, which the SDK fills in.
A colour in another form, or a value in strings that isn’t a string, rejects configure with the code InvalidArgument and a message naming it, such as theme.accent must be #RRGGBB or #AARRGGBB. The SDK’s configuration is then left as it was.
Things to know
- The screens. On Android,
verifyshows them over the current activity, which must stay in front until it resolves. On iOS, over the key window’s top-most view controller. - One verification at a time. A
verifycalled while another runs waits for it to finish. - Reloads. When the module goes away, as on a JavaScript reload, a
verifyin flight ends: the SDK takes its screens down and the promise rejects withCancelled. - Errors. A failed call rejects with an
Errorwhosecodeis the SDK’s error name, as listed in Errors. ForRefused,refusalholds the reason, such asdevice_not_verified.InvalidArgumentis the bridge’s own.Internalis a fault inside the SDK: report it to us. - The notification. On Android, the SDK’s foreground service shows a notification reading “Verifying”. To translate or rebrand it, define
zktls_session_notification_title,zktls_session_channel_nameand the drawablezktls_session_notification_iconin 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.
