Flutter Guide

Learn about OkHi's integration for verifying addresses.

Installation

Run the command below in your project's root directory

flutter pub add okhi_flutter

Install necessary pods by running the command below in your project's root directory

cd ios/ && pod install --repo-update && cd ../

Configuration

Android

SDK Targets

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.

android {
    namespace = "io.okhi.okhiandroidverificationdemo"
    compileSdk = 34

    defaultConfig {
        applicationId = "io.okhi.okhiandroidverificationdemo"
        minSdk = 21
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }
    buildTypes { ... }
    compileOptions { ... }
}​

Permissions

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

<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" android:foregroundServiceType="location"/>
    ...
    
    <application>
    ...
    </application>
​
</manifest>

iOS

Minimum OS support level

The OkHi Flutter library supports iOS devices running OS 12+. Make sure you are targettingat-least the same by following these steps.

1. In the Xcode project: Update the Deployment Target to iOS 12 or later:

   • Open your Xcode project.

   • Select your project in the Navigator.

   • Under the General tab, locate the Deployment Info section.

   • Set the iOS Deployment Target to 12.0 or higher.

2. In the Podfile: Specify the platform version to ensure CocoaPods aligns with the iOS 12+ requirement:

   • Open your Podfile in a text editor.

   • Add or update the platform line at the top of the file as shown below

   platform :ios, '12.0'

   • Save the file and run pod install to apply the changes.

Background Modes

OkHi iOS library 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

Permissions

Add the following permissions to your Info.plist located under the root directory of your iOS project.

<dict>
    <key>NSLocationAlwaysUsageDescription</key>
    <string>Grant to enable verifying your addresses.</string>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>Grant to enable creating addresses at your current location.</string>
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>Grant to enable creating and verifying your addresses.</string>
</dict>

AppDelegate file setup

Finally set up background location monitoring 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

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

Initialisation

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: "<my_branch_id>", // your branch ID
      clientKey: "<my_client_key>", // 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(),
    );
  }

Create and verify addresses

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)

import 'package:flutter/material.dart';
import 'package:okhi_flutter/okhi_flutter.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  bool _launch = false;

  @override
  void initState() {
    super.initState();
    final config = OkHiAppConfiguration(
      branchId: "<my_branch_id>", // your branch ID
      clientKey: "<my_client_key>", // 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);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('OkHi Flutter Demo'),
        ),
        body: _renderBody(),
      ),
    );
  }

  _renderBody() {
    if (!_launch) {
      return Center(
        child: ElevatedButton(
          onPressed: () {
            setState(() {
              _launch = true;
            });
          },
          child: const Text('Verify an address'),
        ),
      );
    }
    return OkHiLocationManager(
      user: _createOkHiUser(),
      onCloseRequest: _handleOnClose,
      onError: _handleOnError,
      onSucess: _handleOnSuccess,
      configuration: OkHiLocationManagerConfiguration(
        usageTypes: [UsageType.digitalVerification],
      ),
    );
  }

  OkHiUser _createOkHiUser() {
    return OkHiUser(
      phone: "+254...",
      firstName: "John",
      lastName: "Doe",
      appUserId: "abcd1234",
      email: "[e-mail]",
    );
  }

  _handleOnSuccess(OkHiLocationManagerResponse response) async {
    setState(() {
      _launch = false;
    });
    final String locationId = await response.startVerification(null);
    print("started verification for $locationId");
  }

  _handleOnError(OkHiException exception) {
    print(exception.code);
    print(exception.message);
  }

  _handleOnClose() {
    setState(() {
      _launch = false;
    });
  }
}

See full integration example here.

Physical Verification

If you'd like to only have physical verification done you can include the usage type as part of the configuration object that's passed to OkHiLocationManager

OkHiLocationManager(
  //...
  configuration: OkHiLocationManagerConfiguration(
    usageTypes: [UsageType.physicalVerification],
  ),
);

See full integration example here.

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 configuration object that's passed to OkHiLocationManager

OkHiLocationManager(
  //...
  configuration: OkHiLocationManagerConfiguration(
    usageTypes: [UsageType.addressBook],
  ),
);

See full integration example here.

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.

OkHiLocationManager(
  //...
  configuration: OkHiLocationManagerConfiguration(
    usageTypes: [UsageType.digitalVerification, UsageType.physicalVerification],
  ),
);

See full integration example here.

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:

1. You created an address using addressBook usage type. See here.
2. 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.

import 'package:flutter/material.dart';
import 'package:okhi_flutter/models/okhi_usage_type.dart';
import 'package:okhi_flutter/okhi_flutter.dart';
import './db.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  bool _launch = false;
  List<UsageType> _usageTypes = [UsageType.addressBook];
  String? _locationId;

  @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);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('OkHi Flutter Demo'),
        ),
        body: _renderBody(),
      ),
    );
  }

  _renderBody() {
    if (_launch) {
      return OkHiLocationManager(
        user: _createOkHiUser(),
        onCloseRequest: _handleOnClose,
        onError: _handleOnError,
        onSucess: _handleOnSuccess,
        configuration: OkHiLocationManagerConfiguration(
          locationId: _locationId,
          usageTypes: _usageTypes,
        ),
      );
    }
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          ElevatedButton(
            onPressed: _handleCreateAnAddressPress,
            child: const Text('Create an address'),
          ),
          ElevatedButton(
            onPressed: _handleVerifySavedAddressPress,
            child: const Text('Verify saved address'),
          ),
        ],
      ),
    );
  }

  _handleVerifySavedAddressPress() {
    final response = DB.fetchAddress();
    if (response != null) {
      _locationId = response.location.id;
      _usageTypes = [UsageType.digitalVerification];
      setState(() {
        _launch = true;
      });
    }
  }

  _handleCreateAnAddressPress() {
    setState(() {
      _launch = true;
    });
  }

  OkHiUser _createOkHiUser() {
    return OkHiUser(
      phone: "+2547..",
      firstName: "John",
      lastName: "Doe",
      appUserId: "abcd1234",
      email: "[e-mail]",
    );
  }

  _handleOnSuccess(OkHiLocationManagerResponse response) async {
    setState(() {
      _launch = false;
    });
    final String locationId = await response.startVerification(null);
    print("started verification for: $locationId");
    DB.saveAddress(response);
  }

  _handleOnError(OkHiException exception) {
    print(exception.code);
    print(exception.message);
  }

  _handleOnClose() {
    setState(() {
      _launch = false;
    });
  }
}

See full integration example here.

Making it yours

Customise address creation experience

It is possible to completely transform the default appearance of OkHiLocationManager to better match your brand by creating a okhiTheme object and passing it to OkCollect as shown below.

return OkHiLocationManager(
  //...
  configuration: OkHiLocationManagerConfiguration(
    usageTypes: [UsageType.digitalVerification],
    color: "#333", // primary
    logoUrl: "https://cdn.okhi.co/icon.png",
  ),
);

Customise notification icon & color

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

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:

Publishing to Google Play store

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.

return OkHiLocationManager(
  configuration: OkHiLocationManagerConfiguration(
    withHomeAddressType: true,
    withWorkAddressType: false,
  ),
);

Error handling

The OkHiLocationManager has 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.

return OkHiLocationManager(
  onError: (error) {
    // handle errors
    print(error.code)
    print(error.message)
  },
);

Known issues

unsupported_platform error code when launching the OkHiLocationManager on Android OS < 7

Due to known browser limitations on devices running Android OS versions below 7, the OkHiLocationManager 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

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 user and location.

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

Once an address has been created and you've configured a webhook in the OkHi Customer Dashboard, 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 webhook documentation here.

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

• Digital Verification Example
• Physical Verification Example
• Digital and Physical Verification Example
• Create and verify an address later Example

Review OkHi integration best practices