Radius Networks Developer Portal

Latest Post 03 May 2016

Announcing the JavaScript Beacon Library

James Nebeker

At Radius Networks we’re proud of our extensive collection of software and development tools geared towards location services and Bluetooth beacons. Today we’re excited to announce the latest addition to this family of tools and products, the JavaScript Beacon Library.

What is the JavaScript Beacon Library?

The JavaScript Beacon Library is (surprise) a JavaScript library for broadcasting BLE beacon advertisements. It harnesses the internal Bluetooth capabilities of the host OS to send out beacon transmissions that nearby phones/tablets can discover, turning your device into the ultimate software beacon. It’s simple to use and integrate, letting developers concentrate on building cool apps that use beacon technology instead of worrying about the nuts and bolts behind the beacon advertising.

What platforms are supported?

Currently the only platform supported is Chrome OS, the JavaScript Beacon Library can be used inside Chrome apps to transmit beacon advertisements on any Chromebook, Chromebox, Chromebit, etc. It leverages the Bluetooth APIs internal to Chrome OS in order to do the beacon broadcasting, which are limited in use to Chrome apps only.

Getting started with the JavaScript Beacon Library

First you’ll need a Chrome app to start integrating the library, I recommend starting with this guide from the Chrome developer site for a quick introduction to Chrome apps and how to start developing one of your own. There you’ll find a sample app you can download to start developing with if you want a quick start. Once you have a Chrome app set up, head to the JBL Github repo where you can download a copy of the library, the file is called beacon.js. Drop this into your project directory and add it to the header of the app’s index.html file:

<!DOCTYPE html>
<html>
<head>
  <script src="beacon.js"></script>
</head>
</html>

Now the library will be available in your app’s JavaScript source.

Registering a beacon advertisement

To begin broadcasting as a beacon in your Chrome app, you need to register a beacon advertisement with the JBL. This is done with the registerAdvertisement() method, which takes in an hash of options that dictate the beacon type, identifiers, and advertised transmit power.

This method is asynchronous; it returns a promise, for which you can specify the appropriate callback functions for success and failure of the advertisement registration.

Below is an example of registering a beacon advertisement of type AltBeacon:

beacon.registerAdvertisement({
  type: 'altbeacon',
  ids: ['2F234454CF6D4A0FADF2F4911BA9FFA6', 1, 1],
  advertisedTxPower: -59
}).then(advertisement => {
  console.log('Advertising: ' + advertisement)
}).catch(error => console.log(error.message));

If an advertisement is successfully registered, it will be transmitted by the OS until it is unregistered. The registered advertisement is stored in an array, accessible at beacon.advertisements, where it can be unregistered later on when you no longer want to transmit this beacon. This is done the unregisterAdvertisement() method:

let registered_adv = beacon.advertisements[0];
registered_adv.unregisterAdvertisement().then(() => {
  console.log('Advertisement unregistered successfully.');
}).catch(error => console.log(error.message));

Only one advertisement can be registered at a time, so if you want to register a new beacon advertisement you first need to unregister any existing ones.

Registering custom beacon types

By default, the JavaScript Beacon Library supports three beacon types:

Additionally, the JBL supports any custom beacon type, so you can register any other beacon standards and broadcast with them just the same.

To register a custom beacon type you only need to specify a name, beacon layout string, and either a manufacturer ID or a service UUID depending on the type of Bluetooth advertisement the beacon standard utilizes. This is done with the registerBeaconType() method, for example:

beacon.registerBeaconType({
  type: 'cool_beacon',
  beaconLayout: 'm:2-3=0000,i:4-19,i:20-21,i:22-23,p:24-24',
  manufacturerId: 0x1234
})

After registering a new beacon type, you can then register a beacon advertisement of that type using the name you specified.
For more information on the beaconLayout string used to classify custom beacon types check out this page from the Android Beacon Library docs.

Physical Web Display

With the release of the JavaScript Beacon Library, we’ve released an update to the Physical Web Display Chrome app in the Chrome Web Store. This new version incorporates the JBL, now enabling all major beacon types, not just Eddystone URL. This opens up the app to many other exciting use cases and extends the number of users you can reach drastically. To grab a copy of the newest version check out Physical Web Display in the Chrome Web Store, or check out this blog post for more info.

A note about Chrome OS BLE Advertising

One important limitation of BLE advertising on Chrome OS is that it is limited to Chrome apps running in “auto-launched kiosk mode” by default. This is a security decision made by the Chrome team, and can only be circumvented by enabling the “BLE Advertising in Chrome Apps” flag in chrome://flags. Without this flag enabled, only a Chrome app running in kiosk mode that is launched automatically at startup will be able to advertise BLE. For information on developing kiosk apps and putting your Chrome OS device into “kiosk mode” check out these links:

Continue Reading...