/ open source

Open sourcing live location tracking experience for web

Billions of trips happen on the planet every day, leading to people meeting each other at home, work or some place else. Whether you are tracking users of apps for work or consumers, a ubiquitous way to share their live location is through a web URL in a text message. These URLs power a great tracking experience on a map with smooth animations, accurate ETAs and up-to-date trip status. It is non-trivial to create a beautiful tracking experience in a web browser. It involves getting and visualizing real-time data updates on the map with moving markers, polylines, smooth animations and automatic zoom levels.

Hot on the heels of open sourcing our location and activity tracking app, we are excited to announce our open-source SDK for our live location tracking experience for web. You will find this post relevant if you are building a custom tracking experience with your own data or building a tracking experience using HyperTrack actions.

Tracking experience SDK for web

The SDK takes location data as input and renders it on a Google Maps view. Furthermore, it continuously takes new data as input and animates them on the map.The core features of this library are:

  • Initialize and render map in your DOM container
  • Initialize and render markers for start location, current location, end location, destination and trailing polyline
  • Handle multiple simultaneous trips on the map maintaining separate markers and polylines
  • Smooth animation for user marker on data update
  • Customizations with full access and control over map object

Installation

Using NodeJS:

npm install --save ht-webtracking-sdk

Or Script tag:

Add dist/track.js as a script tag between <head> and </head> of your html. It exposes global ht object on window.

Prerequisites

  1. Load the Google Maps JavaScript API with API key by adding a script tag like the one in the following example in the of your html:
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  1. Create Map DOM container: In the html file, create a DOM which would contain the map. Give it a unique id. Example:
<div id="map" style="height: 300px; width: 500px"></div>

Usage

The Typescript library ships with typing information. The SDK exposes a global variable ht with the trackByData method. Call this method with the TrackingData object(s) to instantiate the class and render location data on the map. Furthermore, pass the TrackingOptions object to specify the map container, callbacks and customizations. New location data for the trip(s) is passed on to the track() method in a similar format. Pass the data to the instantiated class with the id for which you wish to update the tracking experience and animate the marker to its new location.

Each TrackingData object uses the following values to render icons and animate them on the map:

  • id: Unique identifier for the trip. The SDK uses this id in subsequent updates.
  • encodedTimeAwarePolyline: The time aware polyline is an open source format which captures the locations and timestamps as a compressed string. It is an extension to Google's encoded polyline format, which stores static locations (without timestamps) in a string. The SDK uses this format to animate the marker smoothly current data as well as updates.
  • destination: Expected place of completion for the trip. The SDK uses this to display the destination.
  • isLive: A boolean for whether tracking is live. The SDK uses this field to determine whether to show or hide the user and destination markers.
var ht = require('ht-webtracking-sdk');
var trackedData = ht.trackByData([{
  "id": "",
  "encodedTimeAwarePolyline": "spxsBsdb|Lymo`qvAx@TKvAr@K",
  "destination": {}
  }],
  {
    "mapId": "map",
    "mapOptions": {},
    "onReady": handleOnReady,
    "onError": handleOnError
  }
);

Customization

The SDK follows a default color scheme with its own custom icons and map polyline color. You may pass custom base64 images and polyline options through MapOptions within TrackingOptions to override these defaults. The SDK also exposes the map object via callbacks for full control and access of the tracking experience to the developer. For example, use this to customize the user marker:

var trackingOptions = {
  "mapId": "map",
  "mapOptions": {
    "vehicleIcon": {
        "src": "data:image/png;base64,iVBORw0KGgoAAA....",
        "height": "60px"
    }
  },
  ...
}

Why open source?

The trips that users are expected to perform are assigned as actions to these users in the HyperTrack API. Each assigned action returns a unique trck.at tracking URL. Developers may share this URL with their customers in a lightweight manner through their favorite messaging channel. We built a beautiful tracking experience on these URLs. When developers requested customizations to integrate the tracking experience with their product and brand experience, we packaged it as an SDK. Developer who wanted more access and control over the SDK requested the source code and we provided it to them.

Today, we are opening up this SDK to the developer community at large. We would love to see how the community uses it and would love to see those pull requests, so please send them in. :)

Do check out our open source code here, we would love to hear your feedback. Please create a GitHub issue if you face any trouble with the code and we will be sure to resolve it quickly.