v5.1.1

OkHi on your website

Display and access user's OkHi locations on your website.

The OkHi JavaScript library provides you with a quick and secure way to collect high accuracy location information from your users.

Prerequisites

  • API Keys: You can obtain your API keys by signing up here

Quickstart 🚀

Enabling your users to create a new address or select an existing one is as simple as: 

new okcollect({
  target: document.querySelector('#address'),
  props: {
    API_KEY: "<CLIENT-KEY>",
    userFirstName: "<firstname>",
    userLastName: "<lastname>",
    userPhoneNumber: "<phonenumber>",
    onAddressSelected: (userAddress) => {
      console.log(userAddress)
    },
    onError: (error) => {
      console.log(error)
    },
    appSettings: {
      name: "<app-name>",
      version: "<app-version>"
    },
    ...
  }
});

Whenever a user's OkHi address is created or used an SMS is sent to them notifying them of this usage

OkCollect supports two modes of integration. Single-step and Multi-step integration. Which mode of integration suits your app depends on the time user profile data is available to your app. Follow the Single-step integration guide if you’re collecting the user’s address as part of your user signup flow or as part of a checkout form where you’re prompting user profile data

On the other hand if user profile data is available to your app before the point of address collection (for example in a multi-step registration form or a user profile update screen), follow the Multi-step integration guide.

Single-step Integration

OkCollect requires a few data items on the user creating an address like the user's name and phone number. But oftentimes such user data is not available ahead of time since we commonly capture a user's address as part of our user input form.

To integrate OkCollect on the same form where we're prompting the rest of the user data requires reactively forwarding user input to OkCollect. Here's a full example:

<!DOCTYPE html>
<html lang="en">
 <head>
   <meta charset="UTF-8" />
   <meta http-equiv="X-UA-Compatible" content="IE=edge" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>OkCollect Demo</title>
   <script src="https://sandbox-api.okhi.io/v5/okweb/v2?clientKey=<CLIENT-KEY>&branchId=<BRANCH-ID>"></script>
 </head>
 <body>
   <div style="margin: 0 auto; max-width: 500px; display: flex; flex-direction: column; gap: 8px">
     <input id="firstName" name="firstName" placeholder="First Name" />
     <input id="lastName" name="lastName" placeholder="Last Name" />
     <input id="phoneNumber" name="phoneNumber" placeholder="Phone Number" />
     <div id="address"></div>
   </div>
   <script>
     const c = new okcollect({
       target: document.querySelector('#address'),
       props: {
         API_KEY: "<CLIENT-KEY>",
         userFirstName: "",
         userLastName: "",
         userPhoneNumber: "",
         onAddressSelected: (userAddress) => {
            console.log(userAddress)
          },
          onError: (error) => {
            console.log(error)
          },
         streetviewEnabled: true,
         toTheDoorEnabled: true,
         styleSettings: {
           primaryColor: "#005D67",
           highlightColor: "#85FFC7"
         },
         appSettings: {
           name: "Example App",
           version: "1.0.0"
         },
       }
     });
     document.querySelector('#firstName').addEventListener('input', (ev) => {
       c.$set({ userFirstName: ev.target.value });
     });
     document.querySelector('#lastName').addEventListener('input', (ev) => {
       c.$set({ userLastName: ev.target.value });
     });
     document.querySelector('#phoneNumber').addEventListener('input', (ev) => {
       c.$set({ userPhoneNumber: ev.target.value });
     });
   </script>
 </body>
</html>

Whenever a user's OkHi address is created or used an SMS is sent to them notifying them of this usage

*IMPORTANT* The onAddressSelected callback may be called multiple times as the user changes or manages their address.

Multi-step Integration

But there are cases where we have the user's data available ahead of time. For instance in a multi-step user creation flow or in case we want to collect a user's address only as part of an update profile feature. In such cases we don't have to sync user form inputs to OkCollect properties as we did above. Here's a full example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>OkCollect Demo</title>
    <script src="https://sandbox-api.okhi.io/v5/okweb/v2?clientKey=<CLIENT-KEY>&branchId=<BRANCH-ID>"></script>
  </head>
  <body>
    <div style="margin: 0 auto; max-width: 500px">
      <p>First Name: John</p>
      <p>Last Name: Doe</p>
      <p>Phone Number: +12025550153</p>
      <div id="address"></div>
    </div>
    <script>
      new okcollect({
        target: document.querySelector('#address'),
        props: {
          API_KEY: "<CLIENT-KEY>",
          userFirstName: "John",
          userLastName: "Doe",
          userPhoneNumber: "+12025550153",
          onAddressSelected: (userAddress) => {
            console.log(userAddress)
          },
          onError: (error) => {
            console.log(error)
          },
          styleSettings: {
            primaryColor: "#005D67",
            highlightColor: "#85FFC7"
          },
          appSettings: {
            name: "Example App",
            version: "1.0.0"
          },
        }
      });
    </script>
  </body>
</html>

Non-blocking integration guide

You may have noticed that in the previous examples OkCollect’s javascript library was imported at the top of the page’s html. Doing so blocks rendering of the rest of the page and increases the page’s load time.

We can get around this problem by using the library’s callback api and loading it asynchronously.

<script src="https://sandbox-api.okhi.io/v5/okweb/v2?clientKey=<CLIENT-KEY>&branchId=<BRANCH-ID>&callback=initOkCollect" async defer></script>

Here’s a full example

<!DOCTYPE html>
<html lang="en">
 <head>
   <meta charset="UTF-8" />
   <meta http-equiv="X-UA-Compatible" content="IE=edge" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>OkCollect Demo</title>
 </head>
 <body>
   <div style="margin: 0 auto; max-width: 500px; display: flex; flex-direction: column; gap: 8px">
     <input id="firstName" name="firstName" placeholder="First Name" />
     <input id="lastName" name="lastName" placeholder="Last Name" />
     <input id="phoneNumber" name="phoneNumber" placeholder="Phone Number" />
     <div id="address"></div>
   </div>
   <script>
     function initOkCollect() {
       const c = new okcollect({
         target: document.querySelector('#address'),
         props: {
           API_KEY: "<CLIENT-KEY>",
           userFirstName: "",
           userLastName: "",
           userPhoneNumber: "",
           onAddressSelected: (userAddress) => {
              console.log(userAddress)
            },
            onError: (error) => {
              console.log(error)
            },
           streetviewEnabled: true,
           toTheDoorEnabled: true,
           styleSettings: {
             primaryColor: "#005D67",
             highlightColor: "#85FFC7"
           },
           appSettings: {
             name: "Example App",
             version: "1.0.0"
           },
         }
       });
       document.querySelector('#firstName').addEventListener('input', (ev) => {
         c.$set({ userFirstName: ev.target.value });
       });
       document.querySelector('#lastName').addEventListener('input', (ev) => {
         c.$set({ userLastName: ev.target.value });
       });
       document.querySelector('#phoneNumber').addEventListener('input', (ev) => {
         c.$set({ userPhoneNumber: ev.target.value });
       });
     }
   </script>
   <script async defer src="https://sandbox-api.okhi.io/v5/okweb/v2?clientKey=<CLIENT-KEY>&branchId=<BRANCH-ID>&callback=initOkCollect"></script>
 </body>
</html>

*IMPORTANT* To switch to production remember to change your client & server keys and branch ID to production ones and change the JS library to: https://api.okhi.io/v5/okweb?clientKey=YOUR_CLIENT_API_KEY&branchId=YOUR_BRANCH_ID&callback=initOkHi

Address Specificity

OkCollect defaults to a high-conversion rate user experience where an address is captured with minimal user interaction in the least amount of time. This however comes at the expense of exhaustiveness. The default flow doesn't capture the user's gate photo on streetview, nor is the user prompted to fill out a form with more granular address details like apartment number, building name etc. OkCollect has two configuration options to capture these details.

To enable gate image capture enable the streetview property as follows:

new okcollect({
  target: document.querySelector('#address'),
  props: {
    ...
    streetviewEnabled: true,
    ...
  }
});

To enable a form prompt where the user can supply to-the-door details, make sure to enable the toTheDoor property as follows:

new okcollect({
  target: document.querySelector('#address'),
  props: {
    ...
    toTheDoorEnabled: true,
    ...
  }
});

Dark Mode

Dark mode can be enabled in OkCollect by setting isDarkMode property to true

new okcollect({
  target: document.querySelector('#address'),
  props: {
    ...
    isDarkMode: true,
    ...
  }
});

Next steps

PreviousOkVerify iOSNextAPI Reference

Last updated