API Reference

API Reference for the OkHi JavaScript browser library

LocationManager(options)

Enables launching and closing of the OkHi location manager.

Arguments

• options (object) -- A configuration object that the LocationManager class will use to to launch.

Property	Type	Required	Description
user	UserObject	true	An object that contains information about the current user. You will need to provide at least the user's phone number.
onSuccess	function	false	A callback function that will be called with the SuccessObject.
onError	function	false	A callback function that will be called with the ErrorObject.
style	StyleObject	false	A style object that will be used to customise the look of the LocationManager.
copy	CopyObject	false	A configuration object that can be used to change some of the copy displayed on the LocationManager.
config	ConfigurationObject	false	A configuration object that is used to alter some of the behaviours of the Location Manager and Location Card.

Returns

A location manager class instance with the methods below

launch(launchConfiguration)

Arguments

• launchConfiguration (object) -- A configuration object that will enable the location manager to launch in different modes.

Property	Type	Required	Description
mode	string	false	Different modes to launch the Location manager
location	object	false	A LocationObject with a with a location id. If you pass in the location you must only provide the id.

• mode - string values

  • select_location: This launches the location manager prompting the user to select one of their existing locations if available

• location - object

  • id - An OkHi location id.

Launch Possibilities

Mode Value	Location Value	Outcome
null	null	Location Manager launches in its default state, prompting the user to create a location
select_location	null	Location Manager launches prompting the user to select one of their existing locations if available.
null	{ id: "xxx"}	Location Manager launches in edit mode, where the location with the provided id will be updated.
select_location	{ id: "xxx"}	Location Manager launches and preselects the user's location that matches the provided id, prompting them to add any more available information about the location

Usage

var button = document.getElementById('lets-okhi');

var handleOnSuccess = function (data) {
  // handle your success here with the data you get back
};

var handleOnError = function (error) {
  // handle errors here e.g fallback to your own way of collecting a location information 
};

var style = {
  //add your style configuration here
};

var copy = { 
  // add your copy configuration here 
};

var launchConfiguration = {
  mode: // mode you want to launch in
  location: {
    id: 'xxx' // the OkHi location id you want manipulated in the selected mode
  }
};

var handleButtonClick = function () {
  var user = {
    phone: '+254722xxxxxx',
    firstName: 'John',
    lastName: 'Doe',
  };
  var locationManager = new okhi.OkHiLocationManager({
    user: user,
    onSuccess: handleOnSuccess,
    onError: handleOnError,
    style: style,
    copy: copy
  });
  locationManager.launch(launchConfiguration);
};

button.addEventListener('click', handleButtonClick);

LocationCard(options)

Creates and renders an OkHi location card on the DOM. Upon success the onSuccess callback function will be called with a SuccessObject and upon failure the onError will be called with a ErrorObject.

Arguments

• options (object) - A configuration object that the LocationCard class will use to render the card on the DOM.

Key	Type	Required	Description
user	UserObject	true	An object that contains information about the current user. You will need to at least provide the user's phone number
onSuccess	function	false	A function that will be called whenever the card retrieves or displays a user location. The function will receive the SuccessObject.
onError	function	false	A function that will receive an ErrorObject whenever the card or location manager receives an error.
style	StyleObject	false	A style object that will be used to customise the look of both LocationCard and LocationManager.
copy	CopyObject	false	A configuration object that can be used to change some of the copy that both the LocationCard and LocationManager displays.
config	ConfigurationObject	false	A configuration object that is used to alter some of the behaviours of the Location Manager and Location Card.

• Element (DOM element) - A single DOM element where the card will be rendered in.

• Callback (function) - A function that will be called whenever the card retrieves or displays a user location.

  • In the event that the card or location manager encounters an error, the function will receive an ErrorObject as the first argument

  • On a successful operation the function will receive the SuccessObject as the second argument.

Returns

A location card class instance with the properties below.

user

This property allows you to change the user by supplying a new user object to the card. Only phone number is required to change the user. If you provide only a new phone number without changing firstName and lastName properties the previous values will be used.

Usage

var element = document.getElementById('lets-okhi');
var user = new window.okhi.OkHiUser({
    firstName: "John", // optional
    lastName: "Doe", // optional
    phone: "+254722xxxxxx", // required
});
var style = {
    //add your style configuration here
};
var copy = {
    // add your copy configuration here 
};

var handleOnSuccess = function(data) {
    // handle your success here with the data you get back
};

var handleOnError = function (error) {
// handle errors here e.g fallback to your own way of collecting a location information 
};

var locationCard = new okhi.OkHiLocationCard(
    {
        user: user,
        style: style,
        copy: copy,
    },
    element,
    function(error, data) {
        if (error) {
        // handle errors
            handleOnError()
        } else {
        // handle success data
        handleOnSuccess(data)
        }
    }
);

// changing the user
locationCard.user = new window.okhi.OkHiUser({
  firstName: 'John', // optional
  lastName: 'Doe', // optional
  phone: '+254721xxxxxx', // required
});

UserObject

The UserObject consists of information about a single user.

Property	Type	Description
phone	string	The user's phone number.
firstName	string	The user's first name.
lastName	string	The user's last name.

LocationObject

A LocationObject consists of information about a single OkHi location.

*IMPORTANT* When a user is creating / selecting a location you can always expect to receive a latitude and a longitude all other information listed below are optional.

Property	Type	Description
id	string	The id of the location
placeId	string	The id of the place
propertyName	string	Name of the building
streetName	string	Name of the street
otherInformation	string	Any one-time information about the location. E.g delivery notes
directions	string	Directions to the location
photo	string	The photo of the gate
lat	number	Latitude of the location
lng	number	Longitude of the location
url	string	A public link to view the OkHi location

SuccessObject

The SuccessObject is the UserObject and LocationObject nested into one object.

Example

{
    "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": "+25472XXXXX"
        "firstName": "John",
        "lastName": "Doe"
    }
}

ErrorObject

An ErrorObject contains information of any error that occurred during the launch of the LocationManager.

Property	Type	Description
error_code	string	The code for the error that just occurred
message	string	A message with an exact information of what went wrong

Error Codes

code	Description
fatal_exit	This means the Location Manager was unable to launch due to a fatal error.

StyleObject

The StyleObject provides you with a way to customise both the LocationCard and LocationManager to better match your brand requirements.

Property	Type	Description	Example	Required
color	string	HEX value of your brand color	#009688	true
logo	string	url of your logo	https://cdn.okhi.co/icon.png	true
name	string	name of your company or organisation	OkHi	true
classes	object	Class overrides that will apply specific css properties to the elements in the LocationCard	See details in the StyleClassObject section below	false

StyleClassObject

Property	Type	Description
lc-container	string	This will style the location card parent element.
lc-title	string	This will style the location title text displayed.
lc-button	string	This will style the text buttons.
lc-top	string	This will style the top section of the location card.
lc-bottom	string	This will style the bottom section of the location card.
block-button	string	This will style the block button which prompts the user to create a location.
up-container	string	This styles the up-sell parent element which prompts the user to create a location.
up-message	string	This styles the text that prompts the user to create a location.
lc-information	string	This styles the text that displays the location information.

Example

style: {
  color: '#0277BD',
  logo: 'https://cdn.okhi.co/icon.png',
  name: 'OkHi',
  classes: {
    'lc-container': 'border 1px solid red;',
    'lc-title': 'font-size: 22px;',
    'lc-button': 'border-radius: 0;',
    'lc-top': 'background-color: pink;',
    'lc-bottom': 'background-color: orange;',
    'block-button': 'border-radius: 8px;',
    'up-container': 'background: blue;',
    'up-message': 'color: purple;',
    'lc-information': 'opacity: 0.4;',
  },
},

CopyObject

This object allows you to change different pieces of copy in the LocationCard

Property	Type	Description
createOtherInformation	string	This will change any copy related to prompting users to create other location information.
updateOtherInformation	string	This will change any copy related to prompting users to update other location information.
createLocation	string	This will change any copy related to prompting users to create a location.
selectLocation	string	This will change any copy related to prompting users to select a location.
upsellMessage	string	This will change any copy related to prompting users to create their first OkHi location in the upsell box.

Example

copy: {
  createOtherInformation: 'Create your delivery location',
  updateOtherInformation: 'Change your delivery notes',
  createLocation: 'Create a new delivery location',
  selectLocation: 'Select a delivery location',
  upsellMessage: 'Create your first delivery location with OkHi!',
},

ConfigurationObject

Property	Type	Description
appBar	AppBarConfigurationObject	Configuration object to alter the appearance and behaviour of the app bar.
streetView	bool	Flag to enable OkHi's experimental streetview experience for creating addresses.

AppBarConfigurationObject

Property	Type	Default	Description
visible	bool	true	This will toggle the app bar visibility
color	string	#fff	This will change any copy related to prompting users to update other location information.

Example

config: {
    appBar: {
      color: '#f0f0f0',
      visible: true,
    },
    streetView: true
},