Expo React Native Guide

Learn about OkHi's integration for verifying addresses.

1. Set up OkHi (Client-side)

The React Native Library internally uses the native iOS and android libraries. To install the OkHi React Native library, run one of the following commands in your project's directory (depending on which package manager you use):

yarn add react-native-okhi react-native-webview react-native-v8

Next, configure your Android and iOS apps as follows:


You have to start by setting up an expo dev client for you to be able to use the OkHi library. This is needed because the OkHi library uses Native Modules and this is the only way they are supported in Expo. This requires you to login to expo.dev to proceed. Follow this tutorial.

npx expo install expo-dev-client

Add your eas configuration.

  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    "preview": {
      "distribution": "internal"
    "production": {}

Test your build using

eas build --profile development


​Add the following permissions to your android property located under /app.json

"android": {
      "permissions": [

Create a file called injectedAndroidConfig.js at / the root directory and add the following.

const { withProjectBuildGradle } = require("@expo/config-plugins");

module.exports = function withAndroidStrategiesPlugin(config) {
  return withProjectBuildGradle(config, (config) => {
    config.modResults.contents += `
            allprojects {
                repositories {
                    maven { // <--- add this as part of the repos
                        url "https://repo.okhi.io/artifactory/maven" 
    return config;

Also, add the above to your /app.json file.

"plugins": ["./injectedAndroidConfig", "react-native-v8"]


Enable Background modes in your application.

OkHi obtains verification signals in the background, to enable this make sure to add "Location updates" and "Background fetch" to your Background Modes and necessary permissions.

​Add the following permissions to your ios property located under /app.json.

"ios": {
      "infoPlist": {
        "ITSAppUsesNonExemptEncryption": false,
        "UIBackgroundModes": ["location", "fetch"],
        "NSLocationAlwaysAndWhenInUseUsageDescription": "App requires geolocation to improve the quality of the service",
        "NSLocationAlwaysUsageDescription": "App requires geolocation to improve the quality of the service",
        "NSLocationWhenInUseUsageDescription": "App requires geolocation to improve the quality of the service"

Enable "Allow Non-modular includes in Framework modules"

in the Build Settings, filter for "allow non-modular" and Enable "Allow Non-modular includes in Framework modules"

Set up OkVerify in your AppDelegate file

Open your AppDelegate.h file located under ios/MyApp/AppDelegate.h and add the following lines

#import <React/RCTBridgeDelegate.h>
#import <UIKit/UIKit.h>
@import OkHi; // <= add this!

@interface AppDelegate : UIResponder <UIApplicationDelegate, RCTBridgeDelegate>

@property (nonatomic, strong) UIWindow *window;
@property (strong, nonatomic) OkVerify *okverify; // <= and this!

Enable background monitoring

Open your AppDelegate.m file located under ios/MyApp/AppDelegate.m and add the following lines

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  self.okverify = [[OkVerify alloc] init]; // add this!
  if ([launchOptions objectForKey:UIApplicationLaunchOptionsLocationKey]) // add this!
    [self.okverify startMonitoring];
  //.. rest of default react native code
  return YES;

OkHi initialization

Add the following initialisation code to your App.js file in such a way that the code is executed whenever your app is opened.

Replace my_branch_id and my_client_key with the keys provided to you after sign up.

import React, {useEffect} from 'react';
import {View} from 'react-native';
import * as OkHi from 'react-native-okhi';
import AddressScreen from './AddressScreen';

const App = () => {
  useEffect(() => {
      credentials: {
        branchId: '', // your branch ID
        clientKey: '', // your client key
      context: {
        mode: 'prod',
      notification: {
        title: 'Address verification in progress',
        text: 'Tap here to view your verification status.',
        channelId: 'okhi',
        channelName: 'OkHi Channel',
        channelDescription: 'OkHi verification alerts',
      .then(() => console.log('init done'))
  }, [])
  return (
      <AddressScreen />

export default App;

2. Create and verify an address (Client-side)

Add a button to your UI that would enable launching of OkHi address collection tool.

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.

See below an example using AsyncStorage.

import React, {useState} from 'react';
import {Button, View} from 'react-native';
import {
} from 'react-native-okhi';

const AddressScreen = () => {
  const [launch, setLaunch] = useState(false);
  // TODO 1: Change these to your own user details
  const user = {
    phone: '+234xxxxx', // It is important to provide your actual phone number, as a message will be sent to this number
    firstName: 'Gift',
    lastName: 'Moore',
    email: 'giftmoore@okhi.com', // It is important to use your actual email address, an email may be sent to the provided address

  const handleOnPress = () => {
    // TODO 2: Show a location permissions educational primer before requesting for background location permissions.
    request('always', null, async (status, error) => {
      if (status === 'authorizedAlways') {
      /* TODO 3:
          When the user does not grant location permission the first time.
          1. Show a primer to educate them on how to do this in settings
          2. Provide a button to send them to settings. 
            You may use `openAppSettings()`

  const handleOnSuccess = response => {
      .then(async locationId => {
        console.log('started verification for: ' + locationId);
      .catch(error => {
      .finally(() => {

  return (
      <Button title="Create address" onPress={handleOnPress} />
        onCloseRequest={() => setLaunch(false)}
        config={{streetView: true}}

export default AddressScreen;

If you're targeting Android versions >= 8 and you're using the OkVerify library you need to make sure your users select on "Allow always" when granting permissions otherwise the verification process won't work.


If verification has started successfully:


  • a persistent notification should show, indicating that verification is on going


  • when you simulate a change in the location of the device, you should see the GPS icon lighting up at the top of the screen

Common issues:

  • if background location permission is not granted, verification will not start

3. Add address endpoint (Server-side)

Here's a sample address payload that the client would get on successful address collection:

    "user": {
        "id": "B5QgvjE8WC",
        "phone": "+234xxxxx",
        "firstName": "Gift",
        "lastName": "Moore"
    "location": {
        "id": "8F0yPK1Zdj",
        "lat": 6.442849499999999,
        "lon": 3.424421,
        "plusCode": "6FR5CCVF+4Q",
        "propertyName": "10",
        "streetName": "Raymond Njoku Street",
        "title": "Raymond Njoku Street",
        "subtitle": "10",
        "url": "https://okhi.me/8F0yPK1Zdj",
        "streetViewPanoId": "ufxEWf-zpKLcTxIe04o6Bg",
        "streetViewPanoUrl": "https://maps.googleapis.com/maps/api/streetview?size=640x640&fov=45&location=6.44275037195316%2C3.424513218681455&heading=321.4785708568841&pitch=-9.5945875978788",
        "userId": "B5QgvjE8WC",
        "displayTitle": "10, Raymond Njoku Street",
        "country": "Nigeria",
        "state": "Lagos",
        "city": "Eti-Osa",
        "countryCode": "ng"

Create a secure endpoint on your server that your app can use to pass address details to your server. Remember to handle corner cases such as, address updates & multiple addresses if your app supports it.

//Secure new address endpoint
app.post("/users/addresses", async (req) => {
  const { user, location } = req.body;
  const { id, firstName, lastName, phone } = user;
  const {
    id: locationId, displayTitle, title, subtitle, country, state, city, countryCode, lat, lon, plusCode, propertyName, streetName, url, streetViewPanoId, streetViewPanoUrl
  } = location;
  console.log(user, location);
  // Store the location.id. Used to match webhook updates

4. Handle verification events (Server-side)

OkHi sends verification status updates over a few days while verification is on going. Follow the webhook guide to setup a webhook and receive these verification status updates and run actions such as upgrading a user's KYC level.

5. Push Notification (Optional & Client-side)

Available only for Android, OkHi can reduce unknowns by strategically pinging a users device for location updated. See the code below and also click here to learn more about the full implementation and requirements.

const user: OkHiUser = {
  phone: "+234xxxx",
  firstName: "Jane",
  lastName: "Doe",
  fcmPushNotificationToken: "<MY_PUSH_NOTIFICATION_TOKEN>" //Add to your OkHi user object

6. Show verification status in app(Server- & Client-side)

Create a secure endpoint to enable your app to retrieve address details, including the verification status received from the webhook

// Secure address retrieval endpoint
app.get("/users/addresses", (req) => {
  // Get data from db. Example result:
  const dbResult = {
    "id": "8F0yPK1Zdj",
    "status": "verified",
    "displayTitle": "10, Raymond Njoku Street",
    "title": "Raymond Njoku Street",
    "subtitle": "10",
    "country": "Nigeria",
    "state": "Lagos",
    "city": "Eti-Osa",
    "countryCode": "ng",
  return dbResult;

Show the resulting address details and status on the address page in your app.

7. Test the integration

TitleScenarioHow 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.


When verification is initiated, the address shows up on OkDash

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.

8. Customise the integration

Create a location permissions primer (Required)

Create your custom location permissions primer to educate your user on the requirement for location permissions. Make sure to follow our design best practices to ensure you meet the Google Play store and AppStore requirements.

Customise OkCollect (optional)

It is possible to completely transform the default appearance of OkHiLocationManager to better match your brand by providing values to the theme prop

const theme = {
 colors: {primary: '#005D67'},
 appBar: {
   backgroundColor: '#005D67',
   logo: 'https://mydomain.com/logo.png'

 theme={theme} // customizes apperance of buttons and app bar
 style={styles.locationManager} // customizes apperance of the wrapping container

Customising address type

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.

  ...// normal configuration
  config={{ addressTypes: { home: true, work: false } }}

Customise notification icon & color

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 steps

    <!-- 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">
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />

9. Getting ready to go live

Production credentials

Notify us that you'd like to cut a production build so we can supply production credentials.

Prepare for submission to Google Play store and App Store

Submitting an app to Google Play store and App 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:

Publishing to Google Play store

Publishing to App Store


Incase you run into problems while integrating, review common issues here:

React Native troubleshoot guide

Next steps

Review Full integration sample project

Review React Native library documentation

Review OkHi integration best practices

Last updated