OkHi Documentation
Ask or search…
Comment on page

iOS Library

The suite of OkHi iOS framework that will enable you to start collecting and verifying your user's addresses.
OkCollect and OkVerify supports iOS 12 and above


OkHi Client Key and Branch Id

First you need to obtain your OkHi client key and branch ID. You can get these by signing up here.


platform :ios, '12.0'
target 'MyAwesomeApp' do
pod 'OkHi', '~> 1.9.9'

Configure your app

OkCollect requires access WhenInUse location permission to the user's location in order to create an address at their current location. OkVerify requires AlwaysAndWhenInUseUsage location to verify the user's address
To satisfy these requirements add the following to your info.plist file and provide a useful description as to why your application needs access to the user's location.
<string>String that explains why you need this permission</string>
<string>String that explains why you need this permission</string>
<string>String that explains why you need this permission</string>

Background Mode Capabilities

OkVerify obtains and transmits verification signals in the background, to enable this make sure to add "Location updates" and "Background fetch" at Background Modes under Signing & Capabilities of your target


In your AppDelegate.swift file configure the OkHi Auth object with your client key and branch ID. Make sure to also setup your app's context with meta data about your application
import OkHi
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
let okHiAppContext = OkHiAppContext().withAppMeta(name: "My Awesome App", version: "1.0.0", build: "1")
let okHiAuth = OkHiAuth(
branchId: "", // your branch id
clientKey: "", // your client key
environment: OkHi.Environment.prod,
appContext: okHiAppContext
OkCollect.initialize(with: okHiAuth)
OkVerify.initialize(with: okHiAuth, launchOptions: launchOptions)
return true


For OkVerify to work correctly "Always" Location permission needs to be granted by your users. The library provides the requestBackgroundLocationPermission method that enables you to manage these permission requirements as shown below.
import UIKit
import OkHi
import CoreLocation
class ViewController: UIViewController {
private let okCollect = OkCollect()
private let okVerify = OkVerify()
override func viewDidLoad() {
// Do any additional setup after loading the view.
okCollect.delegate = self
okVerify.delegate = self
@IBAction func onButtonPress(_ sender: UIButton) {
if okVerify.isLocationServicesEnabled() {
if okVerify.isBackgroundLocationPermissionGranted() {
} else {
func startAddressCreation() {
let okHiTheme = OkHiTheme().with(logoUrl: "https://cdn.okhi.co/icon.png").with(appBarColor: "#ba0c2f").with(appName: "OkHi")
let okHiConfig = OkHiConfig().enableStreetView().enableAppBar()
guard let vc = okCollect.viewController(
with: OkHiUser(phoneNumber: "+234xxxxx") // It is important to provide your actual phone number, as a message will be sent to this number
.with(firstName: "Gift")
.with(lastName: "Moore")
.with(email: "[email protected]"), // It is important to use your actual email address, an email may be sent to the provided address
okHiTheme: okHiTheme,
okHiConfig: okHiConfig
) else {
self.present(vc, animated: true, completion: nil)
func startAddressVerification(user: OkHiUser, location: OkHiLocation) {
okVerify.startAddressVerification(user: user, location: location)
extension ViewController: OkCollectDelegate {
func collect(didEncounterError error: OkHiError) {
// handle error
func collect(didSelectAddress user: OkHiUser, location: OkHiLocation) {
startAddressVerification(user: user, location: location)
extension ViewController: OkVerifyDelegate {
func verify(_ okverify: OkVerify, didChangeLocationPermissionStatus requestType: OkVerifyLocationPermissionRequestType, status: Bool) {
if requestType == .always && status {
func verify(_ okverify: OkVerify, didInitialize result: Bool) {
print("initialized successfully")
func verify(_ okverify: OkVerify, didEncounterError error: OkVerifyError) {
func verify(_ okverify: OkVerify, didStartAddressVerificationFor locationId: String) {
print("started verification for: \(locationId)")
func verify(_ okverify: OkVerify, didStopVerificationFor locationId: String) {
print("stopped verification for: \(locationId)")
func verify(_ okverify: OkVerify, didUpdateLocationPermissionStatus status: CLAuthorizationStatus) {
// called on each status change
print("location permission status updated")
func verify(_ okverify: OkVerify, didUpdateNotificationPermissionStatus status: Bool) {
print("push notification permission status updated")

Customizing address type parameters

OkCollect V1 introduces the ability to specify out of two types, the location the customer is at.
  • home
  • work
Ideally, you would ask your user to specify this during address creation and it helps our AI more efficiently and quickly verify an address.
let okHiConfig = OkHiConfig().enableStreetView().enableAppBar().withAddressTypes(work: true, home: false)
Check out the full integration sample project
Whenever a user's OkHi address is created or used an SMS is sent to them notifying them of this usage. When testing make sure to use your phone number
Whereas OkCollect does provide ways to customise the look and feel of the address creation process as well as alter some of the in built functionality. Due to accessibility concerns, the product will work with select brand colours that provide enough contrast to the text being rendered.

Start verification without OkCollect

It's possible to construct your own OkHiLocation object using an identifier (provided by us, when a user creates an address using OkCollect) and a pair of coordinates.
phoneNumber: "+254712345678",
locationId: "xjaksj8",
lat: -1.313677,
lon: 37.292839