README

HERE Tracking JS Library

This library simplifies access to HERE Tracking. It can be used to create management consoles, monitoring interfaces and general device interfaces.

It can also be used to act as a virtual device and post telemetry to HERE Tracking.

You can find more information on the tracking platform here: HERE Tracking Developer Guide.

The compiled library is built for the last 2 versions of each major browser and IE 11.

Prerequisites

This is a Node.js and browser module available through the npm registry.

To build and develop this library, download and install Node.js.

Installation is done using the npm install command.

Install

npm install @here/tracking-js

Directory Layout

Here is an overview of the top-level files contained in the repository:

|
+- demo   # Examples of how to use this library to create a management interface or a virtual device
|
+- docs   # (generated using 'npm run docs') Description of each class and method in the library
|
+- lib    # (generated using 'npm run build') Compiled and minified files
|
+- src    # Original source for each module
|   |
|   +- device.js            # Use to create a virtual device
|   |
|   +- devices.js           # Access device management endpoints
|   |
|   +- geofences.js         # Create and manage geofences
|   |
|   +- index.js                 # Main HERETracking class
|   |
|   +- messages.js              # Error messages
|   |
|   +- notifications.js     # Subscribe to/unsubscribe from notification channels
|   |
|   +- shadows.js           # Manage device data
|   |
|   +- traces.js            # Access device trace history
|   |
|   +- transitions.js       # Access device transition history
|   |
|   +- users.js             # Manage user details
|   |
|   +- vendors.js           # Create and manage device licences
|
+- test   # Test cases

Usage

HTML

Include the minified file in your HTML:

<script src="HERETracking.min.js"></script>

Node.JS

const HERETracking = require('here-tracking-js');

HTML and Node.JS

Create a new HERETracking object:

const tracking = new HERETracking();

Then set the environment you want to run against. The options are 'cit' (Customer Integration Testing) or 'production'.

tracking.environment = 'production';

Tests

npm run test

Example Methods

tracking.users.login('email@example.com', 'password123')
    .then(loginData => {
        console.log(loginData);
    });

> {"accessToken": "h1.userTokenHere...", ...}

List a user's registered devices:

tracking.users.listDevices({ token: 'h1.userTokenHere' })
    .then(devices => {
        console.log(devices);
    });

Retrieve a device's shadow (see HERE Tracking Developer Guide - Shadows):

tracking.shadow.get('trackingIdHere', { token: 'h1.userTokenHere' })
    .then(deviceShadow => {
        console.log(deviceShadow);
    })

tracking.device.login('deviceId', 'deviceSecret'})
    .then(deviceLoginData => {
        console.log(deviceLoginData);
    });

HERE Account

A valid HERE Account user accessToken is required to perform any user-related actions. This token is returned following a successful login using a HERE Account email and password. See 'Log in a user' above. Visit account.here.com to register a new user account.

API Reference

Full auto-generated documentation will be available in the docs folder after running

npm run docs

Example Application

There is an example web interface project available in the demo folder.

Note

You will need to register on developer.here.com to get an app_id and app_code in order to be able to see map tiles.

Rename the file credentials.default.js to credentials.js and enter your app_id and app_code.

To start the demo just open demo/index.html in Chrome or Firefox. You'll need to run a local server to use the demo files in other browsers due to local file security restrictions.

demo/index.html

This will ask you to log into your HERE account then list any devices you have claimed to you account. Clicking on a trackingId will show you the last reported location of the device.

demo/embed.html

A single-device view that can be embedded into another page. In addition to the map tile credentials, you must also enter a username, password and trackingId to see the device's position.

demo/device.html

A virtual device that acts as a tracker, using the browser's Geolocation API as the location to send to HERE Tracking. You must enter a device license generated on https://app.tracking.here.com into the form fields.

Generating a Device License

Visit https://app.tracking.here.com
Log in or register a HERE Account via developer.here.com
Select 'Add device'
Select 'Register a new device ID'
Copy the deviceId and deviceSecret into device.html

Building this Library

This is not necessary if you just want to use the SDK. If you want to build from source, though:

npm install
npm run dev
npm run test

Build the final (minified) version using

npm run build

Build the ESDoc docs using:

npm run docs

How can I contribute?

You want to contribute to this library? Welcome! Please read the CONTRIBUTING.md.

License

MIT license, see the LICENSE file in the root of this project for license details.

Usage no npm install needed!