Flutter Guide

Learn about OkHi's integration for verifying addresses.

1. Set up OkHi (Client-side)

The Flutter Library internally uses the native iOS and android libraries. To install the OkHi Flutter library, run the following command in your project's directory:

flutter pub add okhi_flutter

Next, configure your android and iOS apps as follows:

Android

​Add the following permissions to your AndroidManifest.xml located under android/app/src/main/AndroidManifest.xml

• FOREGROUND_SERVICE is required if your app is targeting Android 14+

<manifest ...>
​    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <uses-permission android:name="android.permission.INTERNET" />
    ...
    
    <application>
    ...
    </application>
​
</manifest>

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.

The OkHi flutter library targets android devices >= SDK 21. Make sure you're targeting at-least the same and set compileSdkVersion & targetSdkVersion to 33 by modifying your android/build.gradle file

ext {
  minSdkVersion = 21
  compileSdkVersion = 33
  targetSdkVersion = 33
  ..//
}

iOS

You would require the latest versions of Xcode & Swift

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 under Signing & Capabilities of your target.

Enable location updates, background fetch background modes

All OkHi react-native libraries target ios devices >= 12. Make sure you're targeting at-least the same by modifying your both your Podfile and deployment target.

Podfile located under: ios/Podfile

platform :ios, '12.0'

Add necessary permissions to your info.plist file located under /ios/MyApp

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

Finally install all required pods by running the following command in the ios directory

pod install

Set up OkHi in your AppDelegate file

Open your AppDelegate file located under ios/Runner/AppDelegate.swift and add in the following

import UIKit
import Flutter
import OkHi // <- import OkHi

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
    private let okverify = OkVerify() // <- initialize okverify
    
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        if launchOptions?[UIApplication.LaunchOptionsKey.location] != nil { // <- enable monitoring
            okverify.startMonitoring()
        }
        GeneratedPluginRegistrant.register(with: self)
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

OkHi initialization

Add the following initialization code to your main.dart file. Replace my_branch_id and my_client_key with the keys provided to you after sign up.

import 'package:okhi_flutter/okhi_flutter.dart';

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    final config = OkHiAppConfiguration(
      branchId: "", // your branch ID
      clientKey: "", // your client key
      env: OkHiEnv.prod,
      notification: OkHiAndroidNotification(
        title: "Verification in progress",
        text: "Verifying your address",
        channelId: "okhi",
        channelName: "OkHi",
        channelDescription: "Verification alerts",
      ),
    );
    OkHi.initialize(config).then((result) {
      print("init done: $result"); // returns true if initialization is successfull
    });
  }

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Home(),
    );
  }

Test

To confirm that initialisation is working as expected, the `init done true` log should be printed out in your console every time your app is opened.

Proguard

Flutter by default has proguard enabled on release builds (see here). Before creating a release build add the following proguard rules:

1. Create a file called proguard-rules.pro under android/app

2. Paste the following content into the file

#Flutter Wrapper
-keep class io.flutter.app.** { *; }
-keep class io.flutter.plugin.**  { *; }
-keep class io.flutter.util.**  { *; }
-keep class io.flutter.view.**  { *; }
-keep class io.flutter.**  { *; }
-keep class io.flutter.plugins.**  { *; }
-keep class io.flutter.plugin.editing.** { *; }
-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

3. Open your android/app/build.gradle and edit it as shown below

 android {
  buildTypes {
    release {
      minifyEnabled true
      shrinkResources true
      proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
    }
  }
}

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

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

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's local storage. This state can be used to ensure that a user may only verify a predefined number of addresses. Usually, one address is used for most cases.

import 'package:flutter/material.dart';

class CreateAddress extends StatefulWidget {
  const CreateAddress({Key? key}) : super(key: key);

  @override
  _CreateAddressState createState() => _CreateAddressState();
}

class _CreateAddressState extends State<CreateAddress> {
  String? _successMessage;

  void _handleSuccess(response) async {
    print(response.user); // user information
    print(response.location); // address information
    setState(() {
      _successMessage = "Address successfully created: ${response.location.id}";
    });
    response.startVerification(null).then((value) async {
      // Send data to your API only when it starts
      print("verification started for ${response.location.id}")
    }).catchError((e) => print("error"));
  }

  void _handleError(error) {
    print(error.code);
    print(error.message);
  }

  Widget _buildBody() {
    if (_successMessage != null) {
      return Center(
        child: Text(_successMessage!)
      );
    } else {
      return OkHiLocationManager(
        user: OkHiUser(phone: "+234xxxxx", email: "[e-mail]", firstName: "Gift", lastName: "Moore"),
        onSuccess: _handleSuccess,
        onError: _handleError,
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Create an address"),
      ),
      body: _buildBody(),
  }
}

Test

If verification has started successfully:

Android:

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

iOS

• 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": "Moore",
        "lastName": "Gift"
    },
    "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.

Node

//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
  return;
});

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

Node

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

6. Test the integration

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

7. 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's possible to completely transform the default appearance of OkHiLocationManager to better match your brand by providing values to the theme prop

It's possible to completely transform the default apperance of OkHiLocationManager to better match your brand by providing values to the theme prop

class Home extends StatelessWidget {
  const Home({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Create an address"),
      ),
      body: OkHiLocationManager(
        user: OkHiUser(phone: "+234xxxxx"),
        configuration: OkHiLocationManagerConfiguration(
          color: "#333",
          logoUrl: "https://mydomain.com/logo.png",
        ),
      ),
    );
  }
}

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.

OkHiLocationManager(
  user: OkHiUser(phone: "+234xxxxx"),
  onSucess: (response) { // handle success },
  onError: (error) { // handle error },
  configuration: OkHiLocationManagerConfiguration(withHomeAddressType: true, withWorkAddressType: 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

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

8. Getting ready to go live

Production credentials

Notify us that you'd like to create 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 guides to know what to expect and how to handle the extra requirements:

Publishing to Google Play store

Publishing to App Store

Next steps

Review Full integration sample project

Review Flutter library documentation

Review OkHi integration best practices