Android Guide

Learn about OkHi's integration for verifying addresses.

Installation

Add the OkHi Maven repository to your settings.gradle file located at the root of your project

settings.gradle

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url "https://repo.okhi.io/artifactory/maven" } // <- add this
    }
}
rootProject.name = "OkHiAndroidVerificationDemo"
include ':app'

settings.gradle.kts

pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://repo.okhi.io/artifactory/maven") // <- add this
        }
    }
}

rootProject.name = "OkHiAndroidVerificationDemo"
include(":app")

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

Include the OkHi Android libraries as part of your app's dependencies by modifying your app/build.gradle file.

dependencies {
    implementation 'io.okhi.android:core:1.7.31'
    implementation 'io.okhi.android:okverify:1.9.66'
    implementation 'io.okhi.android:okcollect:3.3.45'
}

Configuration

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>

Credentials

Within your AndroidManifest.xml , inside application tags add your credentials as shown bellow. You can obtain credentials by filling out this form.

<application>
  <meta-data android:name="io.okhi.core.branch_id" android:value="<my_branch_id>" />
  <meta-data android:name="io.okhi.core.client_key" android:value="<my_client_key>" />
  <meta-data android:name="io.okhi.core.environment" android:value="prod" />
</application>

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)

public class MainActivity extends AppCompatActivity {

  private OkCollect okCollect;
  private OkVerify okVerify;
  private OkHiTheme okHiTheme = new OkHiTheme.Builder("#333").build();

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setUpView();
    setUpOkHi();
  }
  
  private void setUpView() {
    Button btnVerifyAddress = findViewById(R.id.btnVerifyAddress);
    btnVerifyAddress.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        onVerifyAddressClick();
      }
    });
  }

  private void setUpOkHi() {
    int importance = Build.VERSION.SDK_INT >= Build.VERSION_CODES.N ? NotificationManager.IMPORTANCE_DEFAULT : 3;
    OkVerify.init(getApplicationContext(), new OkHiNotification(
      "Verifying your address",
      "We're currently verifying your address. This won't take long",
      "OkHi_Test",
      "OkHi Address Verification",
      "Alerts related to any address verification updates",
      importance,
      1, // notificationId
      2 // notification request code
    ));
    OkHiConfig config = new OkHiConfig.Builder().withUsageTypes(new OkHiUsageType[]{OkHiUsageType.digitalVerification}).build();
    okVerify = new OkVerify.Builder(this).build();
    okCollect = new OkCollect.Builder(this).withConfig(config).withTheme(okHiTheme).build();
  }

  private void onVerifyAddressClick() {
    okCollect.launch(createOkHiUser(), new OkCollectCallback<OkCollectSuccessResponse>() {
      @Override
      public void onSuccess(OkCollectSuccessResponse response) {
        startAddressVerification(response);
      }

      @Override
      public void onClose() {
        showMessage("User closed.");
      }

      @Override
      public void onError(OkHiException e) {
        showMessage(e.getCode() + ":" + e.getMessage());
      }
    });
  }

  private void startAddressVerification(OkCollectSuccessResponse response) {
    okVerify.start(response, new OkVerifyCallback<String>() {
      @Override
      public void onSuccess(String locationId) {
        showMessage("Successfully started verification for: " + locationId);
      }

      @Override
      public void onError(OkHiException e) {
        showMessage(e.getCode() + ":" + e.getMessage());
      }
    });
  }
  
  private OkHiUser createOkHiUser() {
    return new OkHiUser.Builder("+254...")
      .withFirstName("Jane")
      .withLastName("Doe")
      .withEmail("[e-mail]")
      .withAppUserId("abcd1234")
      .build();
  }

  private void showMessage(String message) {
    runOnUiThread(new Runnable() {
      @Override
      public void run() {
        Toast.makeText(getApplicationContext(), message, Toast.LENGTH_LONG).show();
      }
    });
  }
}

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 config object that's passed to OkCollect

OkHiConfig config = new OkHiConfig.Builder()
  .withUsageTypes(new OkHiUsageType[]{OkHiUsageType.physicalVerification})
  .build()

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 config object that's passed to OkCollect

OkHiConfig config = new OkHiConfig.Builder()
  .withUsageTypes(new OkHiUsageType[]{OkHiUsageType.addressBook})
  .build()

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.

OkHiConfig config = new OkHiConfig.Builder()
  .withUsageTypes(new OkHiUsageType[]{OkHiUsageType.digitalVerification, OkHiUsageType.physicalVerification})
  .build();

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.

private void onVerifySavedAddressClick() {

  // fetch location info from your db source
  String locationId = DB.fetchOkHiLocationId();
  double lat = DB.fetchLat();
  double lon = DB.fetchLng();
  
  // construct OkHiLocation object
  OkHiLocation location = new OkHiLocation.Builder(locationId, lat, lon).build();
  
  // assuming you want to initate digital verification
  OkHiConfig config = new OkHiConfig.Builder()
  .withUsageTypes(new OkHiUsageType[]{OkHiUsageType.digitalVerification})
  .build();
  
  // pass new config to okcollect
  okCollect = new OkCollect.Builder(this)
  .withConfig(config)
  .withTheme(okHiTheme)
  .build();
  
  okCollect.launch(createOkHiUser(), location , new OkCollectCallback<OkCollectSuccessResponse>() {
    @Override
    public void onSuccess(OkCollectSuccessResponse response) {
      startAddressVerification(response);
    }

    @Override
    public void onClose() {
      showMessage("User closed.");
    }

    @Override
    public void onError(OkHiException e) {
      showMessage(e.getCode() + ":" + e.getMessage());
    }
  });
}

See full integration example here.

Making it yours

Customise address creation experience

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

OkHiTheme okhiTheme = new OkHiTheme.Builder("#333") // primary color
              .setAppBarColor("#333")
              .setAppBarLogo("https://mydomain.com/logo.png")
              .build();

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.

OkHiConfig config = new OkHiConfig.Builder()
              .withHomeAddressType(true)
              .withWorkAddressType(false)
              .build();

Error handling

Both the OkVerifyCallback and OkCollectCallback have 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.

@Override
public void onError(OkHiException e) {
  showMessage(e.getCode() + ":" + e.getMessage());
}

Known issues

unsupported_platform error code when launching okcollect on Android OS < 7

Due to known browser limitations on devices running Android OS versions below 7, the android:okcollect library 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 API ref

• android-core

• android-okcollect

• android-okverify

Review OkHi integration best practices