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

Prerequisites

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.

Installation

SPM

https://github.com/OkHi/ios-okhi

CocoaPods

platform :ios, '12.0'

target 'MyAwesomeApp' do
  pod 'OkHi', '~> 1.9.9'
end

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.

<key>NSLocationWhenInUseUsageDescription</key>
<string>String that explains why you need this permission</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>String that explains why you need this permission</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<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

Authentication

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
}

Usage

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() {
        super.viewDidLoad()
        // Called in the initial screen
        OkVerify.onStart()
        // 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() {
                startAddressCreation()
            } else {
                okVerify.requestBackgroundLocationPermission()
            }
        }
    }
    
    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: "[e-mail]"), // It is important to use your actual email address, an email may be sent to the provided address
            okHiTheme: okHiTheme,
            okHiConfig: okHiConfig
        ) else {
            return
        }
        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
        debugPrint(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 {
            startAddressCreation()
        }
    }
    
    func verify(_ okverify: OkVerify, didInitialize result: Bool) {
        print("initialized successfully")
    }
    
    func verify(_ okverify: OkVerify, didEncounterError error: OkVerifyError) {
        debugPrint(error)
    }
    
    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.

okVerify.startAddressVerification(
    phoneNumber: "[phone]",
    locationId: "xjaksj8",
    lat: -1.313677,
    lon: 37.292839
)