The OkHi libraries target Android devices >= SDK 21. Make sure you're targeting at least the same and set compileSdkVersion & targetSdkVersion to 34 by modifying your app/build.gradle file.
Alternatively, you can pass the credentials in your AndroidManifest.xml , inside the application tags as shown below.
Passing the API keys to the Manifest file has been deprecated since 29 April 2025, and will be removed. Prioritise passing the API keys in-app for app security.
Always use your phone number or a phone number you own during testing as a message will be sent to this number after an address is created.
We recommend that you persist the verification state of the user in your app local storage. This state can be used to ensure that a user may only verify a predefined number of addresses. Usually one address for most use cases.
Digital Verification (Default)
public class MainActivity extends AppCompatActivity {
private OkCollect okCollect;
private OkVerify okVerify;
private OkHiTheme okHiTheme = new OkHiTheme.Builder("#333").build();
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setUpView();
setUpOkHi();
}
private void setUpView() {
Button btnVerifyAddress = findViewById(R.id.btnVerifyAddress);
btnVerifyAddress.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
onVerifyAddressClick();
}
});
}
private void setUpOkHi() {
int importance = Build.VERSION.SDK_INT >= Build.VERSION_CODES.N ? NotificationManager.IMPORTANCE_DEFAULT : 3;
OkVerify.init(getApplicationContext(), new OkHiNotification(
"Verifying your address",
"We're currently verifying your address. This won't take long",
"OkHi_Test",
"OkHi Address Verification",
"Alerts related to any address verification updates",
importance,
1, // notificationId
2 // notification request code
));
// Initializing with credentials
OkHiAppContext okHiAppContext = new OkHiAppContext(this, "prod", "android", "developer")
OkHiAuth okHiAuth = new OkHiAuth(this, "my_branch_id", "my_client_key", okHiAppContext)
OkHiConfig config = new OkHiConfig.Builder().withUsageTypes(new OkHiUsageType[]{OkHiUsageType.digitalVerification}).build();
okCollect = new OkCollect.Builder(this).withTheme(theme).withConfig(config).withAuth(okHiAuth).build()
okVerify = new OkVerify.Builder(this, okHiAuth).build()
}
private void onVerifyAddressClick() {
okCollect.launch(createOkHiUser(), new OkCollectCallback<OkCollectSuccessResponse>() {
@Override
public void onSuccess(OkCollectSuccessResponse response) {
startAddressVerification(response);
}
@Override
public void onClose() {
showMessage("User closed.");
}
@Override
public void onError(OkHiException e) {
showMessage(e.getCode() + ":" + e.getMessage());
}
});
}
private void startAddressVerification(OkCollectSuccessResponse response) {
okVerify.start(response, new OkVerifyCallback<String>() {
@Override
public void onSuccess(String locationId) {
showMessage("Successfully started verification for: " + locationId);
}
@Override
public void onError(OkHiException e) {
showMessage(e.getCode() + ":" + e.getMessage());
}
});
}
private OkHiUser createOkHiUser() {
return new OkHiUser.Builder("+254...")
.withFirstName("Jane")
.withLastName("Doe")
.withEmail("jane@okhi.co")
.withAppUserId("abcd1234")
.build();
}
private void showMessage(String message) {
runOnUiThread(new Runnable() {
@Override
public void run() {
Toast.makeText(getApplicationContext(), message, Toast.LENGTH_LONG).show();
}
});
}
}
Physical Verification
If you'd like to only have physical verification done you can include the usage type as part of the config object that's passed to OkCollect
OkHiConfig config = new OkHiConfig.Builder()
.withUsageTypes(new OkHiUsageType[]{OkHiUsageType.physicalVerification})
.build()
Address book only
If you'd like to only create the address and still obtain usage data that will help verification later, you can include the usage type as part of the config object that's passed to OkCollect
OkHiConfig config = new OkHiConfig.Builder()
.withUsageTypes(new OkHiUsageType[]{OkHiUsageType.addressBook})
.build()
Physical + Digital Verification
It's possible to have both physical and digital verification to run at the same time for a given address. Include both usage types as part of the array.
OkHiConfig config = new OkHiConfig.Builder()
.withUsageTypes(new OkHiUsageType[]{OkHiUsageType.digitalVerification, OkHiUsageType.physicalVerification})
.build();
Tips & Tricks
Create an address and verify it later
It's possible to create an address, obtain usage data that will help verification and initiate either physical and/or digital at a later time.
The example assumes:
You've securely stored previous address information either on device or server and have access to the locationId obtained in the success response of okcollect.
private void onVerifySavedAddressClick() {
// fetch location ID from your DB source
String locationId = DB.fetchOkHiLocationId();
// construct OkHiLocation object
OkHiLocation location = new OkHiLocation.Builder(locationId).build();
OkHiAppContext okHiAppContext = new OkHiAppContext(this, "prod", "android", "developer")
OkHiAuth okHiAuth = new OkHiAuth(this, "my_branch_id", "my_client_key", okHiAppContext)
// assuming you want to initiate digital verification
OkHiConfig config = new OkHiConfig.Builder()
.withUsageTypes(new OkHiUsageType[]{OkHiUsageType.digitalVerification})
.build();
okCollect = new OkCollect.Builder(this).withTheme(theme)
.withAuth(okHiAuth)
.withConfig(config) // pass new config to okcollect
.build()
okCollect.launch(createOkHiUser(), location , new OkCollectCallback<OkCollectSuccessResponse>() {
@Override
public void onSuccess(OkCollectSuccessResponse response) {
startAddressVerification(response);
}
@Override
public void onClose() {
showMessage("User closed.");
}
@Override
public void onError(OkHiException e) {
showMessage(e.getCode() + ":" + e.getMessage());
}
});
}
Making it yours
Customise the address creation experience
It is possible to completely transform the default appearance of OkCollect to better match your brand by creating a okhiTheme object and passing it to OkCollect as shown below.
OkHiTheme okhiTheme = new OkHiTheme.Builder("#333") // primary color
.setAppBarColor("#333")
.setAppBarLogo("https://mydomain.com/logo.png")
.build();
Customise notification icon & color
<application>
<!-- Set custom default icon for OkVerify's foreground service -->
<meta-data android:name="io.okhi.android_background_geofencing.foreground_notification_icon" android:resource="@drawable/ic_person_pin" />
<!-- Set custom default icon color for OkVerify's foreground service -->
<meta-data android:name="io.okhi.android_background_geofencing.foreground_notification_color" android:resource="@color/colorAccent" />
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
Prepare for submission to the Google Play store
Submitting an app to the Google Play store that has background location permissions has a few extra requirements. Follow these guide to know what to expect and how to handle the extra requirements:
Building with pro-guard
If you have minifyEnabled set to true in your build.gradle file located android/app/build.gradle, you'll need to modify your proguard-rules.pro file, located android/app/proguard-rules.proas shown bellow to include classes required by the library to run.
-dontwarn sun.reflect.**
-dontwarn java.beans.**
-dontwarn sun.nio.ch.**
-dontwarn sun.misc.**
-keep class com.esotericsoftware.** {*;}
-keep class java.beans.** { *; }
-keep class sun.reflect.** { *; }
-keep class sun.nio.ch.** { *; }
-keep class com.snappydb.** { *; }
-dontwarn com.snappydb.**
# If you don't use OkHttp as a dep and the following
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn javax.annotation.**
-keepnames class okhttp3.internal.publicsuffix.PublicSuffixDatabase
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.ConscryptPlatform
-dontwarn org.conscrypt.ConscryptHostnameVerifier
In instances where the web module cannot fire the OS functions i.e. Location permission requests and enabling GPS on QuickStart, after building with Progard enabled, add the following rule to the progard-rules.pro file:
-keepclassmembers class io.okhi.android_okcollect.interfaces.WebAppInterface {
@android.webkit.JavascriptInterface <methods>;
}
Create home or work addresses
You may turn off either of the OkHi address types. This is to allow your users to create either home or work addresses to better suit your use-case. By default both address types are on.
OkHiConfig config = new OkHiConfig.Builder()
.withHomeAddressType(true)
.withWorkAddressType(false)
.build();
Error handling
Both the OkVerifyCallback and OkCollectCallback have an onError method where you can handle errors. The OkHiException object has both getCode and getMessage methods that will help you diagnose what went wrong with the either the address creation process or address verification process.
unsupported_platform error code when launching okcollect on Android OS < 7
Due to known browser limitations on devices running Android OS versions below 7, the android:okcollect library is not supported on these devices. This is because the necessary browser APIs required to accurately create and verify addresses are unavailable. We are aware of this issue and are actively working on an update to address it. In the meantime, please ensure you capture and track errors as demonstrated above to better understand the impact on your users.
Server side integration
Accessing address properties
const handleOnSuccess = async (response: OkCollectSuccessResponse) => {
console.log(response.user.id); // access user properties
console.log(response.location.id); // access location properties
await sendToServer(response.user, response.location) // send address info to your server
await response.startVerification(); // start verification
}
Handling verification events
Testing
Title
Scenario
How to test
Create an address
Address creation succeeds and verification is initiated
Launch OkHi's address manager via the button you created and create an address. A sticky notification appears on android.
Dashboard
When verification is initiated, the address shows up on OkHi Dashboard
Check OkDash, you should see a list of all the addresses created. It takes ~3min for addresses to show up on OkDash
Proof of address
When an address is verified, the webhook receives the status update and the app shows the correct verification status.
A proof of address certificate is made available on OkDash.
Install your app on your personal device that you move around with and create your home address. Check okDash in 3 days for your proof of address certificate once your address has been verified.
Business logic
When an address is verified or not, the correct business logic is applied successfully.
Conduct a comprehensive test with multiple users, wherein they create various addresses to observe diverse outcomes. These outcomes may include successful creation of home addresses, entering incorrect addresses, refusing to grant necessary location permissions, or uninstalling the app immediately after initiating the address verification process, among other scenarios.
Next steps
Review integration examples
Review API ref
You can obtain credentials by filling out this .
You can pass the credentials programmatically during the initialization of the libraries, as shown below:
See full integration example .
See full integration example .
See full integration example .
See full integration example .
You created an address using addressBook usage type. See .
See full integration example .
Once verification starts a persistent notification is visible (Android < 13). You can specify a custom default icon and a custom default color by adding these lines inside the application tag to set the custom default icon and custom color. You'll need to have already created the icon resource in your android application. Icon assets can be created by following these
On the client/app, within your onSucess handler you can access both user and address information which you can use to transit securely to your servers. See the API reference for complete list of properties on and .
Once an address has been created and you've configured a webhook in the OkHi , you'll be able to receive updates regarding address verification in your backend, which you can use to enable certain services in your app. The OkHi Dashboard allows you to do much more; please see the full documentation here.
