Guides

Track Work

How to start tracking work with Orders and other ways to manage tracking intent.

🚧

This guide assumes that you have successfully integrated our HyperTrack SDK with your mobile app and have registered workers in our system. If not then go through the steps in our Install SDK guide first.

To use the HyperTrack API, you will need the {AccountId} and {SecretKey} from the Setup page.

HyperTrack gives you powerful APIs to manage tracking from both your app and backend.

Tracking can be initiated in two ways:

  • Remotely: by creating a server-side tracking intent. (recommended)
  • Locally: by manually calling the SDK methods on device. (advanced; not recommended)

Remote Tracking

Remote tracking can be done in following fashions:

  • Automated: Tracking an Order for a worker. (recommended)
    • Tracking will start with the Order and end once it is completed.
  • Manual: Updating worker's tracking status. (advanced; not recommended)
    • A low level way to manage worker tracking status without Orders.

Automatically track work with Orders

Track work with Orders by calling the POST /orders/track endpoint from your server:

curl --request POST \
     --url https://v3.api.hypertrack.com/orders/track \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "worker_handle": "[email protected]",
  "track_mode": "pre_shift",
  "orders": [
    {
      "order_handle": "order-1",
      "type": "pick",
      "scheduled_at": "2024-11-05T02:00:00Z",
      "destination": {
        "address": "Ferry Building Marketplace, 1 Ferry Building, San Francisco, California 94111, United States",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -122.39340278135214,
            37.795409200306224
          ]
        },
        "radius": 100
      }
    }
  ]
}
'

To get {longitude} and {latitude} of your destination, you can use geojson.io website. HyperTrack uses GeoJSON. Please make sure you follow the correct ordering of longitude and latitude.

This creates the order in the HyperTrack platform and starts tracking the worker's device automatically.

To see the device on the map, open the returned embed_url in your browser (no login required, so you can embed these views directly to your web app). The worker will also show up in the Workers section in the HyperTrack dashboard.

Some highlights of the the HyperTrack Orders API use:

  • set the track_mode to pre-shift to track ETAs
  • set scheduled_at to get notified about any delays via webhooks
  • use share_url to share a live tracking URL of the trip with customers
  • use embed_url to embed live tracking view of an order in your ops dashboard

Manage worker's tracking status

If you don’t use pre_shift or on_shift Order tracking, you can start tracking remotely by setting the worker status. The worker's tracking status can be set by calling the POST workers/{worker_handle}/work_status:

curl --request POST \
     --url https://v3.api.hypertrack.com/workers/james%40ht.com/work_status \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"tracking":true}'

While this is possible we don't recommend customers to do this manually unless explicitly instructed to do so.


Local tracking

Tracking can also be started manually by calling the mobile SDK API methods on worker's device:

  • iOS: set HyperTrack.isTracking to true
  • Android: call setTracking with true

⚠️

The SDK tracking intent is persisted separately from the Order tracking intent. In other words, if tracking is set to true before an Order is tracked, the tracking will continue even after the Order is completed.


Stop tracking locally during an Order

If an Order is tracking and SDK's HyperTrack.isTracking is set to false the remote tracking intent is not cleared.

Locally the SDK will stop tracking, but this will only last up until:

  • The App is restarted and the SDK syncs the remote Order tracking intent, or
  • HyperTrack backend sends an updated tracking intent to the SDK

⚠️

The remote tracking intent has to be managed via the Orders or Workers API.


Example flow of an Order

The following example outlines the complex interplay of various HyperTrack products throughout the lifecycle of an order:

  1. API call to Orders API starts tracking an order
  2. HyperTrack mobile SDK starts tracking on device:
    1. HyperTrack wakes up the device remotely via a push notification (most cases)
    2. Worker opens the mobile app and SDK syncs the remote tracking intent
      1. This mechanism ensures that tracking starts even if the push notification is not able to reach the device (more commonly on iOS)
  3. Worker kills the app, you can see an “app killed” outage in dashboard Order View
  4. Worker re-opens the app, SDK resumes tracking because the Order is still in progress
  5. Worker disables Location Services, the SDK notifies subscribers with “Location Services Disabled” error
    1. There will also be a recorded outage in dashboard view of the order
  6. Worker re-enables Location Services, the SDK resumes tracking
  7. Orders completes, the SDK stops tracking

Updated 3 months ago