Web

Contents

Introduction

This is the documentation for the web JavaScript SDK. Before integrating, read the native SDK documentation to familiarize yourself with the platform.

See the source on GitHub here. Or, see the radar-sdk-js package on npm here.

Install

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 library:

npm install --save radar-sdk-js
import Radar from 'radar-sdk-js';

The SDK is less than 20 KB minified.

Integrate

Initialize

To initialize the library, call:

Radar.initialize(publishableKey);

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

Identify user

To identify the user when logged in, call:

Radar.setUserId(userId);

where userId is a stable unique ID for the user.

To set an optional dictionary of custom metadata for the user, call:

Radar.setMetadata(metadata);

where metadata is a JSON object with up to 16 keys and values of type string, boolean, or number.

Finally, 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 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, result) {
  if (!err) {
    // do something with result.location, result.events, result.user
  }
});

If the request is unsuccessful, err will be a string, one of:

  • ERROR_PUBLISHABLE_KEY: SDK not initialized
  • ERROR_PERMISSIONS: location permissions not granted
  • ERROR_LOCATION: location services error or timeout (10 seconds)
  • ERROR_NETWORK: network error or timeout (10 seconds)
  • ERROR_BAD_REQUEST: bad request (missing or invalid params)
  • ERROR_UNAUTHORIZED: unauthorized (invalid API key)
  • ERROR_PAYMENT_REQUIRED: payment required (organization disabled or usage exceeded)
  • ERROR_FORBIDDEN: forbidden (insufficient permissions or no beta access)
  • ERROR_NOT_FOUND: not found
  • ERROR_RATE_LIMIT: too many requests (rate limit exceeded)
  • ERROR_SERVER: internal server error
  • ERROR_UNKNOWN: unknown error

Manual tracking

You can manually update the user's location by calling:

Radar.trackOnce({
  latitude: 39.2904,
  longitude: -76.6122,
  accuracy: 65
}, function(err, result) {
  if (!err) {
    // do something with result.events, result.user
  }
});

Other APIs

The web SDK also exposes APIs for anonymous context, geocoding, search, and distance.

Get location

Get a single location update without sending it to the server:

Radar.getLocation(function(err, result) {
  if (!err) {
    // do something with result.location
  }
});

Context

With the context API, get context for a location, depending on context types configured, without sending device or user identifiers to the server:

Radar.getContext({
  latitude: 40.783826,
  longitude: -73.975363,
  accuracy: 65
}, function(err, result) {
  if (!err) {
    // do something with result.context
  }
});

Geocoding

With the forward geocoding API, geocode an address, converting address to coordinates:

Radar.geocode('20 jay st brooklyn ny', function(err, result) {
  if (!err) {
    // do something with result.addresses
  }
});

With the reverse geocoding API, reverse geocode a location, converting coordinates to address:

Radar.reverseGeocode({
  latitude: 40.783826,
  longitude: -73.975363
}, function(err, result) {
  if (!err) {
    // do something with result.addresses
  }
});

With the IP geocoding API, geocode the device's current IP address, converting IP address to city, state, and country:

Radar.ipGeocode(function(err, result) {
  if (!err) {
    // do something with result.address
  }
});

Search

With the autocomplete API, autocomplete partial addresses and place names, sorted by relevance:

Radar.autocomplete({
  query: 'brooklyn roasting',
  near: {
    latitude: 40.783826,
    longitude: -73.975363
  },
  limit: 10
}, function(err, result) {
  if (!err) {
    // do something with result.addresses
  }
});

With the geofence search API, search for geofences near a location, sorted by distance:

Radar.searchGeofences({
  radius: 1000,
  tags: ['venue'],
  limit: 10
}, function(err, result) {
  if (!err) {
    // do something with result.geofences
  }
});

With the places search API, search for places near a location, sorted by distance:

Radar.searchPlaces({
  near: {
    latitude: 40.783826,
    longitude: -73.975363
  },
  radius: 1000,
  chains: ['starbucks'],
  limit: 10
}, function(err, result) {
  if (!err) {
    // do something with result.places
  }
});

Distance

With the distance API, calculate the travel distance and duration between two locations:

Radar.getDistance({
  origin: {
    latitude: 40.78382,
    longitude: -73.97536
  },
  destination: {
    latitude: 40.70390,
    longitude: -73.98670
  },
  modes: [
    'foot',
    'car'
  ],
  units: 'imperial'
}, function(err, result) {
  if (!err) {
    // do something with result.routes
  }
});

Support

Have questions? We're here to help! Email us at [email protected].