OkHi Integration Best Practices
This section is to help guide product managers, designers, and developers through integrating OkHi’s products into their native mobile apps.
Following these best practices will provide the best experience for your users and the best results for your business.
OkHi Integration Best Practices (Google Doc)
Product Overview
OkHi has two product libraries that you can integrate into your product:
OkCollect - collect an accurate address from your customer
OkVerify - verify that your customer lives or works at the collected address
Both product libraries are supported on Android and React Native. iOS is coming soon.
The two product libraries can either be implemented together or separately:
Together - at the point of collecting the address you immediately start verifying the address eg. address verification is required as part of your onboarding flow. (Diagram 1)
Separate - you collect the address first and then start the verification at a later point eg. address verification is only required to unlock certain features or services eg. a larger loan. (Diagram
OkCollect Integration Guide
Launch and Fallback
What is this?
How best to launch OkCollect from your mobile app and manage the fall back if a user exits from the OkCollect experience.
Why is it important?
To minimise users leaving your app when collecting their address it’s important to correctly launch and manage the fallback of OkCollect.
Best Practices
To ensure your users have a seamless experience moving between your app and OkCollect, the library enables you to customise the colour and logo within OkCollect to fit the style of your app. See our developer documentation for more details.
OkCollect requires the name and phone number of the user before launching the modal. To ensure the phone number is in a compliant format as per our developer documentation we recommend asking for the phone in one of two ways:
prefix country code (Diagram 3)
country code selector (Diagram 4)
OkCollect does not handle phone number verification and assumes that the user’s phone number has been verified by your app.
Once the name and phone number are collected your app now needs to launch the OkCollect modal. Please note that to enable the full functionality of OkCollect on Android and React Native, location permissions are required before launching OkCollect. See the Permissions section below.
There are two ways that we recommend that you launch OkCollect with minimal disruption to your user flow:
OkHi Address is Required
Replace your existing address collection flow (usually text address fields) with an “Add Address” button (or similar call to action) that will launch OkCollect. (Diagram 5)
The “Add Address” button behaviour is inactive until the user has entered a valid name and phone number.
Limit the user from progressing to the next step unless the “Add Address” button is tapped and an OkHi address is successfully saved.
Once an address is successfully saved, provide a payoff message that gives feedback to the user that their address was successfully saved.
If the user exits the OkCollect modal, either encourage the user to try again or roll back to your current address collection flow. (Diagram 6)
OkHi Address is Optional
Inline with your existing text address fields add a “Drop pin” button (or similar call to action) that will launch OkCollect. (Diagram 7)
The “Drop pin” button behaviour is inactive until the user has entered a valid name and phone number.
If the user exits the OkCollect modal, either encourage the user to try again or roll back to your current address collection flow.
Save address payoff
On tap of “Save address” the platform toast notification displays to inform the user of the action they have taken: “Address saved”. This notification displays for 2 seconds and then closes the OkCollect view returning the user to your app.
Once a user has successfully saved their address you may want to offer the option for them to edit their address, and therefore relaunch OkCollect. See our developer documentation for more details.
OkVerify Integration Guide
Onboarding
What is this?
How best to educate your user about OkHi’s remote verification technology.
Why is it important?
OkVerify is a new technology that uses geolocation data in the phone to verify addresses. It’s important to proactively communicate how OkVerify works to mitigate privacy concerns and support issues.
Best Practices There are three different levels of education and user opt in that you can build into your user experience. You need to decide what’s right for your users, balancing more education and control with more interruption to your user flow:
education, with opt in: provide full transparency to the user that they could use this remote verification service to verify their address and share how it works. The user can opt in or out to using OkVerify with your product. You will need to provide a fallback address verification solution for the users who opt out of using OkVerify. (Diagram 8)
education, no opt in: provide light transparency to the user that their address will be verified remotely using signals in their phone. Every user has to use this remote verification service. (Diagram 9)
no education, no opt in: technically you could verify the user’s address in the background without their knowledge. We do not recommend this.
Verification status
What is this? It can take multiple days to verify an address so this provides transparency to the user of the status.
Why is it important?
Given the user is likely to be prohibited from the full functionality of your product without their address being verified, it’s important to keep them up to date with the progress.
Best Practices
This best practice assumes that you have provided some education to the user about the remote address verification service.
In your app we recommend always showing the verification status of your user’s address as either:
not started - the address has just been collect but OkVerify has not been initiated yet
in progress - OkVerify has been initiated but the address has not been verified (Diagram 10)
verified - OkVerify has successfully verified the address
To get your user to re-engage with your app and use features that are available after address verification we recommend sending a notification that on tap returns the user to your app and educates them on these features. (Diagram 11)
After an address has been verified, you can decide whether to keep the verification service active in order to ensure the address is always up to date, or to stop the verification service.
Foreground service
What is this?
A notification that remains visible throughout a user's address verification which assists in gathering reliable verification signals.
A foreground service performs operations that are visible to the user by displaying a persistent notification showing your app performing a task in the foreground while using system resources. The notification cannot be dismissed unless the service is stopped or removed from the foreground through the use of methods available in the library outlined in our developer documentation.
Why is it important?
Due to background task restrictions introduced by Google in Android 8 as well as by some device manufacturers, there are limitations in capturing and transmitting reliable verification signals. To mitigate these restrictions we’ve introduced an opt-in foreground service feature that improves the reliability and accelerates verification.
The foreground service also helps with
Data synchronization between OkHi servers and your application
Detecting system level changes such as location services being turned off / on
Maintaining the integrity of running processes by detecting any errors that occur and restarting them if needed
Maintaining verification signals even after device restarts or low power modes
Best Practices
You’ll need to configure a notification as outlined in our developer documentation, and OkVerify will do the rest: creating notification channels, listening for notification request codes, start the foreground service after device restarts or enters low power mode.
It’s important to configure your notification well to ensure reliability of capturing verification signals and to communicate well with your users. We recommend the following:
Notification content: provide an appropriate notification title and text. Example title: “Address verification in progress”. Notification text: “Check the app to review your verification progress”
Notification channel: create a separate channel for OkVerify by providing the appropriate channel identifier, name and description. This will ensure that none of your existing notification channels are affected when a user attempts to change the configuration of a particular channel
Notification identifier: provide an appropriate notification identifier and request code, that don’t conflict with the existing you may have setup. This will enable OkVerify to properly listen for user taps on the relevant notification.
Android location permissions best practices
Miro board
PDF file
iOS location permissions best practices
Miro board
PDF file
Privacy
What is this?
We take the privacy of your users very seriously and have built our products to give your users transparency and control of their data. Read OkHi’s Terms of Service and Privacy Policy.
Why is it important?
If your users do not have the right level of transparency and control of their data they will not sign up to your service.
Best Practices
We ensure that every user agrees to our terms and privacy policy before they save their first address with OkCollect. (Diagram 15)
Last updated
