OkHi on your Android app

The OkHi android SDK is a seamless way to collect and use accurate customer location information.

The SDK is a customisable UI within your app that enables users to create or lookup existing OkHi locations.

An OkHi location consists of a high accurate GPS pin, a photo of gate and a weblink that enables either to navigate to the location or to plot your user demographics on the OkHi Insights web-app.

OkHi SDK gives your app the ability to collect an address for a user as well as update the user’s address.

The minimum supported SDK version is 23 (android 6.0)

Steps for integration

Add the maven repository into your project build.gradle

maven { url 'https://jitpack.io' }

See more context below

allprojects {
    repositories {
        google()
        jcenter()
        maven { url "https://jitpack.io" }
        
    }
}

In your app module build.gradle dependencies, add the following dependencies and sync gradle files

implementation 'com.github.OkHi:okhi-android-sdk:1.5.25'

Initialize the OkHi SDK by adding the following line in your application class. Initialize takes two parameters: the API key (a string) to use and verify ( a boolean ) to verify the user's created address.

public class YourCustomApplication extends Application {
    @Override
    Public void onCreate(){
        super.onCreate()
        OkHi.initialize("YOUR_API_KEY", true);
    }
}

You can obtain an api key by signing up here

When you have finished testing and you want to go live, request for a production key here

You can customize the sdk by adding the following line in your application class

OkHi.customize("header background color", "organisation name", "logo url");

• color is in rgb format

• Name of your organization

• Url link of the company logo

Example as below

OkHi.customize("rgb(0, 131, 143)", "okhi", "
https://lh3.ggpht.com/GE2EnJs1M1Al9_Ol2Q1AV0VdSsvjR2dsVWO_2ARuaGVS-CJUhJGbEt_OMHlvR2b8zg=s180
");

Create a callback to receive the responses from the library

OkHiCallback okHiCallback = new OkHiCallback() {
    @Override
    public void querycomplete(JSONObject jsonObject) {
        //The callback will return the jsonobject once its done.
    }
};

Launch the library as follows

JSONObject jsonObject = new JSONObject();
jsonObject.put("firstName", "firstName");
jsonObject.put("lastName", "lastName");
jsonObject.put("phone", "phone");
jsonObject.put("requestSource", "requestSource");
OkHi.displayClient(okHiCallback, jsonObject);

Example as below

JSONObject jsonObject = new JSONObject();
jsonObject.put("firstName", "Ramogi");
jsonObject.put("lastName", "Ochola");
jsonObject.put("phone", "0713567907");
jsonObject.put("requestSource", "loanApplication");
OkHi.displayClient(okHiCallback, jsonObject);

When the user goes through the address creation process successfully, the following json object is returned in the callback.

{
   "location": {
       "streetName": "Yellow brick road",
       "lat": -1.2343261,
       "lng": 36.6642569,
       "placeId": "1A8sxd6V9W",
       "propertyName": "Mitte lane court",
       "directions": "turn is gud",
       "id": "dEwmYjtpqc",
       "url": "https://receive2.okhi.co/dEwmYjtpqc",
       "otherInformation": "Please pet the dog when you arrive"
   },
   "user": {
       "phone": "[phone]",
       "firstName": "Ramogi",
       "lastName": "Ochola"
   }
}

Returned after the user has successfully completed address creation.

{
  "message": "non_fatal_exit",
  "payload": {
    "Response": "Address creation completed successfully"
  }
}

Returned after the user has successfully completed address creation.

When the user does not go through the address creation process successfully, the following json object is returned in the callback.

{
  "message": "fatal_exit",
  "payload": {
    "Error": "Network error"
  }
}

Returned when there is no internet connection.

{
  "message": "fatal_exit",
  "payload": {
    "Error": "Address creation did not complete"
  }
}

Returned if the user did not complete the address creation

{
  "message": "fatal_exit",
  "payload": {
    "Error": "phone is required in user object"
  }
}

Returned if a parameter is missing

{
  "message": "fatal_exit",
  "payload": {
    "errorCode": -1,
    "error": "Location permission not granted",
    "message": "Manifest.permission.ACCESS_BACKGROUND_LOCATION not granted"
  }
}

Returned if address verification is enabled and the app does not have the necessary location permissions allowed.

You can request for the necessary permissions through the SDK as follows

 OkHi.requestPermission(activity, integer);

Example as below

public class MainActivity extends AppCompatActivity {
    private static final int 
    MY_PERMISSIONS_ACCESS_LOCATION = 82;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
     
     //somewhere in your code before calling displayClient
      OkHi.requestPermission(MainActivity.this,
         MY_PERMISSIONS_ACCESS_LOCATION);
   
    }
    
  
             
}        

Also you can implement the code below in the same activity to know if you were successful in obtaining necessary permissions from the user.

    @Override
    public void onRequestPermissionsResult(int requestCode,
                                           String[] permissions, int[] grantResults) {
        switch (requestCode) {
            case MY_PERMISSIONS_ACCESS_LOCATION: {
                // If request is cancelled, the result arrays are empty.
           
                if (grantResults.length > 0
                        && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                    // permission was granted, yay! Do the
                    // You can continue with user flow
                 
                } else {
                    // permission denied, boo! Disable the
                    // verify functionality that depends on this permission.
                
                }
                return;
            }
        }
    }

The SDK has utility method as below to check if its necessary to request for location permission.

Boolean hasPermission = OkHi.checkPermission();