brettguenther/radar-sdk-js

Radar is the location platform for mobile apps.

Installation

In an HTML page, include the SDK using a <script> tag:

<script src="https://js.radar.io/v3.0.0-beta.4/radar.min.js" integrity="sha384-NLSzGc8WqjQHUlTze1Rp8e+5cjI0KJ8wyU9W+ClJj/ceW8ZFyyX26axTM2pSKyU0" crossorigin="anonymous"></script>

In a web app, install the package from npm, then import the module:

npm install --save radar-sdk-js

import Radar from 'radar-sdk-js';

The SDK is less than 10 KB minified.

Usage

Initialize SDK

To initialize the SDK, call:

Radar.initialize(publishableKey);

where publishableKey is a string containing your Radar publishable API key.

To get a Radar publishable API key, sign up for a Radar account.

Identify user

Until you identify the user, Radar will automatically identify the user by a random UUID "device ID" stored in a cookie.

To identify the user when logged in, call:

Radar.setUserId(userId);

where userId is a stable unique ID string for the user.

To set an optional description for the user, displayed in the dashboard, call:

Radar.setDescription(description);

where description is a string.

You only need to call these functions once, as these settings will be persisted across browser sessions in cookies.

Foreground tracking

Once you have initialized the SDK, you have identified the user, and the user has granted permissions, you can track the user's location.

The SDK uses the HTML5 geolocation API to determine the user's location.

To track the user's location, call:

Radar.trackOnce(function(err, { status, location, user, events }) {
  if (!err) {
    // do something with location, user, events
  }
});

error will be null for a successfull call. Errors thrown by the Radar SDK include:

ERROR_PUBLISHABLE_KEY: the SDK was not initialized
ERROR_PERMISSIONS: the user has not granted location permissions for the website
ERROR_LOCATION: location services were unavailable, or the location request timed out
ERROR_NETWORK: the network was unavailable, or the network connection timed out
ERROR_UNAUTHORIZED: the publishable API key is invalid
ERROR_RATE_LIMIT: exceeded rate limit of 1 request per second per user or 60 requests per hour per user
ERROR_SERVER: an internal server error occurred
ERROR_PARAMETERS: one or more of the parameters are invalid
ERROR_MISSING_CALLBACK: no callback was provided

Support

Have questions? We're here to help! Email us at support@radar.io.

brettguenther / radar-sdk-js