OkHi on your Java App

This sections describes how you can build your own custom integration to work with the OkHi Location Manager using Java ☕️and JavaFX WebView

Requirements

• An OkHi API Key - You can get one here

• JavaFX WebView set up in your project. Download it here

• JSON in Java [package org.json] set up in your project. Download the jar here

• OkHi Java utility classes. Download it here

Getting Started 🚀

Include JavaFX and org.json jar files in your project.

In your module-info make sure to add the following dependencies.

module my.project {
  requires javafx.fxml;
  requires javafx.controls;
  requires javafx.web;
  requires jdk.jsobject;
  requires org.json;

  opens my.package;
}

Create a package in your src folder called okhi

Copy & Paste all the OkHi utility classes into the newly created okhi package folder.

That's it you now have everything required to run OkHi in your project.

Launching the OkHi Location Manager

You'll first need to create an OkHi Auth object. This step requires the use of your API key.

OkHiAuth auth = new OkHiAuth("r:b59a93ba7d80a95d89dff8e4c52e259a");

Once you have the auth object, you'll then need to create an OkHi user object.

// firstName, lastName, phoneNumber
// only phoneNumber is required
OkHiUser user = new OkHiUser("Bob", "Markson", "0721856492");

To enable the LocationManager to match your company branding, create an OkHi style object.

// hexColor, Company Name, Logo
OkHiStyle style = new OkHiStyle("#ba0c2f", "Jubilee Insurance", "https://jubileeinsurance.com/ke/wp-content/themes/_ji/images/logo.svg");

Once you have all that you can finally create an OkHi object that will enable you to launch the Location Manager

// refer to notes below 

OkHi okhi = new OkHi(auth, user, style, OkHiLaunchMode.SELECT_LOCATION, OkHiDevMode.SANDBOX, new OkHiLocationHandler() {
    @Override
    public void onSuccess(OkHiLocation location, OkHiUser user) {
      // TODO: handle success here
      System.out.println(location.title);
    }

    @Override
    public void onError(OkHiError error) {
      // TODO: handle error here
      System.out.println(error.code);
      System.out.println(error.message);
    }

    @Override
    public void onCloseRequest() {
      // TODO: handle case when user taps the close button
      System.out.println("close me");
    }
}); 

Notes 📝

OkHiLaunchMode.SELECT_LOCATION enables the Location Manager to fetch a list of pre-existing addresses. A different mode available is OkHiLaunchMode.START_APP which defaults the Location Manager to its normal address creation flow.

OkHiDevMode.SANDBOX allows you to work in sandbox mode. Change this to OkHiDevMode.PRODUCTION once you're ready to go live!

The OkHiLocationHandler enables you to listen for success, error and close events Once a location has been created or selected the onSuccess method will be called. If an error does occur e.g no internet connection, the onError method will be called. Be sure to inspect the code and message properties when this happens.

When a user taps the close button in the Location Manager the onCloseRequest method will be called. At this point you can remove the Location Manager from view.

The OkHiLocation object has the following properties:

public String id;
public double lat;
public double lng;
public String placeId;
public String plusCode;
public String propertyName;
public String streetName;
public String title;
public String url;
public String directions;
public String otherInformation;

All together now 🎶

package sample;

import javafx.application.Application;
import javafx.geometry.Insets;
import javafx.scene.Parent;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.layout.HBox;
import javafx.stage.Stage;
import okhi.*;

public class Main extends Application {

  private Stage stage;

  @Override
  public void start(Stage stage) throws Exception{
    this.stage = stage;
    Button button = new Button("Create OkHi Location");
    button.setOnAction(actionEvent ->  {
      this.launchOkHiLocationManager();
    });
    HBox hbox = new HBox(button);
    hbox.setPadding(new Insets(10, 5, 10, 5));
    this.changeScene(hbox);
  }

  public void launchOkHiLocationManager() {
    OkHiAuth auth = new OkHiAuth("r:b59a93ba7d80a95d89dff8e4c52e259a");
    OkHiUser user = new OkHiUser("Bob", "Markson", "0721856492");
    OkHiStyle style = new OkHiStyle("#ba0c2f", "Jubilee Insurance", "https://jubileeinsurance.com/ke/wp-content/themes/_ji/images/logo.svg");
    OkHi okhi = new OkHi(auth, user, style, OkHiLaunchMode.SELECT_LOCATION, OkHiDevMode.SANDBOX, new OkHiLocationHandler() {

      @Override
      public void onSuccess(OkHiLocation location, OkHiUser user) {
        // TODO: handle success here
        System.out.println(location.title);
      }

      @Override
      public void onError(OkHiError error) {
        // TODO: handle error here
        System.out.println(error.code);
      }

      @Override
      public void onCloseRequest() {
        // TODO: handle case when user taps the close button
        System.out.println("close me");
      }
    });

    Parent locationManager = okhi.locationManager();
    changeScene(locationManager);
  }

  public void changeScene(Parent sceneType) {
    Scene scene = new Scene(sceneType, 960, 600);
    stage.setTitle("OkHi LocationManager Demo");
    stage.setScene(scene);
    stage.show();
  }

  public static void main(String[] args) {
    launch(args);
  }
}

Next steps

Backend Integration: Address Interactions

Integrate the Address Interactions API to start collecting your users' interactions with their address to enable you to get rich insights to make more informed business decisions using the insights data.

pageAddress Interactions

We appreciate any feedback you have for us. Let us know if something is not working. If you have a fix for it, great! Here's a link to the GitHub repo, looking forward to your pull requests.