Migrating from Devices to Drivers

Who is a Driver? And how does it relate to a Device?

🚧

This section is for existing customers that already use Devices API and want to move to new Drivers API

Introduction

Driver in HyperTrack is the Worker/Pro/Courier. Every driver has a driver_handle which you use internally to identify your mobile app users. For example, this could be the user_id, email, phone number etc. The driver_handle stays the same while the devices (device_ids) used by the driver might change over time. It is used in the Ops Views to display information about the work done by the driver.

So what's the big deal you ask? What can the Drivers API do for me? Great question, let's answer that!

Drivers are a high level construct you can use to interact with our APIs: where previously you would rely on device_id you now can use driver_handle. Previously you would have to keep track of your mobile app user’s device_id (subject to change) to know which one to start tracking for, but now you can simply start tracking for the driver_handle (remains the same).

For example, let’s say John has a device A. Tomorrow he switches his device to one that has B. Earlier, you would have to update the John’s linked device_id at your end from A to B to ensure that you start tracking the right device. With Drivers you can forget about juggling the device_ids and instead use the driver_handle for all of your location tracking workflows.

Highlights of what this means in different contexts:

  • Your driver work timeline can be seamlessly retrieved even when the driver switches between devices.
  • You can now manage the driver availability and schedule to enable automatic start/stop tracking and order planning.
  • You don’t need to manage device_ids on your backend. Use your own identifiers for drivers as the driver_handle for tracking, availability, planning and searches.
  • Nearby search can be used to find available drivers for work.

So how do you start using drivers?

Currently you probably manage device_ids in your own backend, correlating them with your mobile app user’s unique id (referred to as user_id onwards).

From the SDK, set metadata with driver_handle to your user_id and we’ll automagically create a driver with such handle for you. You can also pre-create drivers via POST https://v3.api.hypertrack.com/drivers, and the matching driver_handle will be updated with the new device_id (if the driver already exists).

Once this is done any future devices your user will have are going to be linked with that drive_handle. As long as your device metadata sets a driver_handle we will make sure the two linked.

Alternatively, you can create a driver POST https://v3.api.hypertrack.com/drivers with a device_id in the body or patch existing drivers with PATCH https://v3.api.hypertrack.com/drivers/{driver_handle} with a device_id to link to the driver. But we recommend using the SDK approach, because you typically have the user_id readily available in your the app.

Updated 22 days ago

What’s Next