Android Library

The suite of OkHi android libraries that will enable you to start collecting and verifying your user's addresses.

To start verifying address you need to integrate two libraries. OkCollect & OkVerify.

  • OkCollect - enables you to launch OkHi from your app and collect accurate addresses from your users.

  • OkVerify - enables you to verify the addresses created from OkCollect

Installation

Androidx

Please make sure AndroidX is enabled in your project by modifying android/gradle.properties and adding 2 lines:

android.useAndroidX=true
android.enableJetifier=true

Add the JitPack repository to your build file

allprojects {
    repositories {
        maven { url "https://repo.okhi.io/artifactory/maven" } // <- add this
        //..//
    }
}

Add the OkHi Core library dependencies

dependencies {
    implementation 'io.okhi.android:core:1.7.24'
    implementation 'io.okhi.android:okcollect:3.3.30'
    implementation 'io.okhi.android:okverify:1.9.49'
}

Check for the latest release on GitHub:

android-core

android-okcollect

android-okverify

Configure your app

Open your AndroidManifest.xml located under android/app/src/main/AndroidManifest.xml and add:

  1. your credentials (obtain these by filling out this form) as shown below​.

  2. required permissions: ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION

  3. FOREGROUND_SERVICE is required if your app is targeting Android 14+

<manifest ...>
​
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
    <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_NETWORK_STATE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    ...
    
    <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" />
        <meta-data android:name="io.okhi.core.platform" android:value="android" />
    ...
    </application>
​
</manifest>

If you're targeting Android versions >= 8 you need to make sure your users select on "Allow always" when granting permissions otherwise the verification process won't work. See our best practices section

Usage

Create an instance of the OkVerify class to be used later in your class.

Make sure to invoke the static init method once on app start.

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.

public class Sample extends AppCompatActivity {

    private OkHi okhi;
    private OkCollect okCollect;
    private OkVerify okVerify;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        setUpOkHi();

        Button btn = findViewById(R.id.btnSubmit);
        btn.setOnClickListener(view -> handleButtonClick());
    }

    private void handleButtonClick() {
        OkHiUser user = new OkHiUser.Builder("+234xxxxx") // It is important to provide your actual phone number, as a message will be sent to this number
        .withFirstName("Gift")
        .withLastName("Moore")
        .withEmail("giftmoore@okhi.com") // It is important to use your actual email address, an email may be sent to the provided address
        .build();
        
        requestPermissions(user)
    }
    
    private void requestPermissions(OkHiUser user) {
        okhi.requestEnableVerificationServices(new OkHiRequestHandler<Boolean>() {
            @Override
            public void onResult(result: Boolean) {
                if (result) {
                    startAddressCreation(user);
                }
            }
            
            @Override
            public void onError(e: OkHiException) {
                e.printStackTrace()
            }
        })
    }

    private void startAddressCreation(OkHiUser user) {
         okCollect.launch(user, OkCollectLaunchMode.CREATE, new OkCollectCallback<OkHiUser, OkHiLocation>() {
            @Override
            public void onSuccess(OkHiUser okHiUser, OkHiLocation location) {
                startAddressVerification(okHiUser, location);
            }
            @Override
            public void onClose() {
                Toast.makeText(Sample.this, "User closed", Toast.LENGTH_LONG).show();
            }
            @Override
            public void onError(OkHiException e) {
    
                Toast.makeText(Sample.this, e.getCode() + ":" + e.getMessage(), Toast.LENGTH_LONG).show();
            }
        });
    }

    private void startAddressVerification(OkHiUser user, OkHiLocation location) {
        okVerify.start(user, location, new OkVerifyCallback<String>() {
            @Override
            public void onSuccess(String result) {
                Toast.makeText(Sample.this, "Started verification for: " + result, Toast.LENGTH_LONG).show();
            }

            @Override
            public void onError(OkHiException e) {
                Toast.makeText(Sample.this, e.getCode() + ":" + e.getMessage(), Toast.LENGTH_LONG).show();
            }
        });
    }

    private void setUpOkHi() {

        final OkHiTheme theme = new OkHiTheme.Builder("#333333").setAppBarLogo("https://cdn.okhi.co/icon.png").setAppBarColor("#333333").build();
        final OkHiConfig config = new OkHiConfig.Builder().withStreetView().build();

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

        try {
            okhi = new OkHi(this);
            okCollect = new OkCollect.Builder(this).withTheme(theme).withConfig(config).build();
            okVerify = new OkVerify.Builder(this).build();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        okhi.onActivityResult(requestCode, resultCode, data);
    }

    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults);
        okhi.onRequestPermissionsResult(requestCode, permissions, grantResults)

Next steps

Review the API references

OkHi Core

OkHi OkCollect

OkHi OkVerify

PreviousAndroid GuideNextAndroid Dependencies

Last updated