Eddystone Advertising Library

The Eddystone Advertising Library abstracts low level concepts of the Eddystone protocol and wraps existing Advertising APIs so that developers don't have to worry about these low level details. The library exposes simple functions that developers can use to advertise a Valid Eddystone packet from their device.

NOTE Currently only ChromeOS is supported.

Usage

The Eddystone Advertising Library creates window.eddystone of type Eddystone

To advertise a url: Example

let registered_adv;
eddystone.registerAdvertisement({
  type: 'url',
  url: 'https://example.com',
  advertisedTxPower: -20
}).then(advertisement => {
  registered_adv = advertisement;
  console.log('Advertising: ' + advertisement.url)
}).catch(error => console.log(error.message));

To stop advertising: Example

registered_adv.unregisterAdvertisement().then(() => {
  console.log('Advertisement unregistered successfully.');
}).catch(error => console.log(error.message));

Or if you have multiple advertisements:

eddystone.advertisements.forEach(advertisement => {
  advertisement.unregisterAdvertisement()
    .then(() => console.log('Unregistered successfully'))
    .catch(error => console.log('Couldn\'t unregister the advertisement: ' + error.message));
});

API

Modules

eddystone-advertisement

eddystone-advertising

eddystone-chrome-os

eddystone-uid

eddystone-url

platform

Members

eddystone : Eddystone

The global eddystone instance.

eddystone-advertisement

Example

const advertisement = require('eddystone-advertisement')

• eddystone-advertisement
  • .EddystoneAdvertisement
    • new EddystoneAdvertisement(id, options, platform)
    • .id : number
    • .type : string
    • .advertisedTxPower : number | undefined
    • .url : string | undefined
    • .namespace : string | undefined
    • .instance : string | undefined
    • .unregisterAdvertisement() ⇒ Promise.<void>
  • .EddystoneFrameType : enum

advertisement.EddystoneAdvertisement

Represents the Advertisement being broadcasted.

Kind: static class of eddystone-advertisement

• .EddystoneAdvertisement
  • new EddystoneAdvertisement(id, options, platform)
  • .id : number
  • .type : string
  • .advertisedTxPower : number | undefined
  • .url : string | undefined
  • .namespace : string | undefined
  • .instance : string | undefined
  • .unregisterAdvertisement() ⇒ Promise.<void>

new EddystoneAdvertisement(id, options, platform)

Throws:

• TypeError If no platform was passed.
• Error If type is an unsupported Frame Type.

Param	Type	Description
id	number	Unique between browser restarts meaning the id will no longer be valid upon browser restart.
options	EddystoneAdvertisementOptions	The options used when creating the advertisement.
platform	Object	The underlying platform; used to unregister the advertisement.

eddystoneAdvertisement.id : number

The ID of this advertisment.

Kind: instance property of EddystoneAdvertisement

eddystoneAdvertisement.type : string

The Eddystone Type

Kind: instance property of EddystoneAdvertisement

eddystoneAdvertisement.advertisedTxPower : number | undefined

Tx Power included in the advertisement. Only present if type === 'url' or type === 'uid'.

Kind: instance property of EddystoneAdvertisement

eddystoneAdvertisement.url : string | undefined

URL being advertised. Only present if type === 'url'.

Kind: instance property of EddystoneAdvertisement

eddystoneAdvertisement.namespace : string | undefined

Hex string of the namespace being advertised. Only present if type === 'uid'.

Kind: instance property of EddystoneAdvertisement

eddystoneAdvertisement.instance : string | undefined

Hex string of the instance being advertised. Only present if type === 'uid'.

Kind: instance property of EddystoneAdvertisement

eddystoneAdvertisement.unregisterAdvertisement() ⇒ Promise.<void>

Unregisters the current advertisement.

Kind: instance method of EddystoneAdvertisement
Fulfill: void - If the advertisement was unregistered successfully.
Reject: Error - If the advertisement failed to be registered. If the promise rejects the advertisment may still be broadcasting. The only way to recover may be to reboot your machine.

advertisement.EddystoneFrameType : enum

Possible Eddystone frame types.

Kind: static constant of eddystone-advertisement
Read only: true
See

• Protocol Specification
• Eddystone-URL
• Eddystone-UID
• Eddystone-TLM

Properties

Name	Type	Default
URL	string	"url"
UID	string	"uid"
TLM	string	"tlm"

eddystone-advertising

• eddystone-advertising
  • Eddystone ⏏
    • instance
      • .advertisements : Array.<EddystoneAdvertisement>
      • .registerAdvertisement() ⇒ Promise.<EddystoneAdvertisement>
    • inner
      • ~EddystoneAdvertisementOptions : Object

Eddystone ⏏

Exposes platform independent functions to register/unregister Eddystone Advertisements.

Kind: Exported class

eddystone.advertisements : Array.<EddystoneAdvertisement>

Contains all previously registered advertisements. Note: In a Chrome App, if the event page gets killed users won't be able to unregister the advertisement.

Kind: instance property of Eddystone

eddystone.registerAdvertisement() ⇒ Promise.<EddystoneAdvertisement>

Function to register an Eddystone BLE advertisement.

Kind: instance method of Eddystone
Params: EddystoneAdvertisementOptions options The characteristics of the advertised Eddystone.
Fulfill: EddystoneAdvertisement - If the advertisement was registered successfully.
Reject: Error - If the advertisement failed to be registered.

Eddystone~EddystoneAdvertisementOptions : Object

Object that contains the characteristics of the package to advertise.

Kind: inner typedef of Eddystone
Properties

Name	Type	Description
type	EddystoneFrameType	Type of Eddystone. For now only 'url' is supported.
url	string | undefined	The URL to advertise
advertisedTxPower	number | undefined	The Tx Power to advertise

eddystone-chrome-os

• eddystone-chrome-os
  • EddystoneChromeOS ⏏
    • .registerAdvertisement(options) ⇒ Promise.<EddystoneAdvertisement>
    • .unregisterAdvertisement(advertisement) ⇒ Promise.<void>
    • ._constructAdvertisement() ⇒ ChromeOSAdvertisement

EddystoneChromeOS ⏏

This class wraps the underlying ChromeOS BLE Advertising API.

Kind: Exported class
Todo

• Add link to API.

EddystoneChromeOS.registerAdvertisement(options) ⇒ Promise.<EddystoneAdvertisement>

Function that registers an Eddystone BLE advertisement.

Kind: static method of EddystoneChromeOS
Fulfill: EddystoneAdvertisement - If the advertisement was registered successfully.
Reject: Error - If the advertisement failed to be regsitered.

Param	Type	Description
options	EddystoneAdvertisementOptions	The characteristics of the advertisement.

EddystoneChromeOS.unregisterAdvertisement(advertisement) ⇒ Promise.<void>

Function to unregister an advertisement.

Kind: static method of EddystoneChromeOS
Fulfill: void - If the advertisment was unregistered successfully.
Reject: Error - If the advertisment failed to be unregistered.

Param	Type	Description
advertisement	EddystoneAdvertisement	The advertisement to unregister.

EddystoneChromeOS._constructAdvertisement() ⇒ ChromeOSAdvertisement

Construct the ChromeOS specific advertisement to register.

Kind: static method of EddystoneChromeOS
Returns: ChromeOSAdvertisement - advertisement
Throws:

• Error If the frame type is not supported
• Error If the Tx Power value is not in the allowed range. See: https://github.com/google/eddystone/tree/master/eddystone-url#tx-power-level
• Error If the URL Scheme prefix is unsupported. For a list of supported Scheme prefixes see: https://github.com/google/eddystone/tree/master/eddystone-url#url-scheme-prefix
• Error If the URL contains an invalid character. For a list of invalid characters see the Note in: https://github.com/google/eddystone/tree/master/eddystone-url#eddystone-url-http-url-encoding

Params: EddystoneAdvertisementOptions options The characteristics of the advertisement.

eddystone-uid

• eddystone-uid
  • EddystoneUID ⏏
    • .constructServiceData(advertisedTxPower, namespace, instance) ⇒ Array.<number>
    • .getByteArray(value) ⇒ Array.<number>

EddystoneUID ⏏

This class provides helper functions that relate to Eddystone-UID.

Kind: Exported class
See: Eddystone-UID

EddystoneUID.constructServiceData(advertisedTxPower, namespace, instance) ⇒ Array.<number>

Constructs a valid Eddystone-UID service data from a Tx Power value, namespace and instance.

Kind: static method of EddystoneUID
Returns: Array.<number> - The service data.
See: UID Frame Specification

Param	Type	Description
advertisedTxPower	number	The Tx Power included in the service data.
namespace	Array.<number> | string	The namespace to advertise.
instance	Array.<number> | string	The instance to advertise.

EddystoneUID.getByteArray(value) ⇒ Array.<number>

Validates the give array of bytes or converts the hex string into an array of bytes.

Kind: static method of EddystoneUID
Returns: Array.<number> - Array of bytes.
Throws:

• TypeError If |value| is not an array or a string.
• Error If |value| contains out-of-range numbers or characters.

Param	Type	Description
value	Array.<number> | string	The value to encode.

eddystone-url

• eddystone-url
  • EddystoneURL ⏏
    • .constructServiceData(url, advertisedTxPower) ⇒ Array.<number>
    • .encodeURL(url) ⇒ Array.<number>

EddystoneURL ⏏

This class provides helper functions that relate to Eddystone-URL.

Kind: Exported class
See: Eddystone-URL

EddystoneURL.constructServiceData(url, advertisedTxPower) ⇒ Array.<number>

Constructs a valid Eddystone-URL service data from a URL and a Tx Power value.

Kind: static method of EddystoneURL
Returns: Array.<number> - The service data.
See: URL Frame Specification

Param	Type	Description
url	string	The URL to use in the service data.
advertisedTxPower	number	The Tx Power to use in the service data.

EddystoneURL.encodeURL(url) ⇒ Array.<number>

Encodes the given string using the encoding defined in the Eddystone-URL Spec.

Kind: static method of EddystoneURL
Returns: Array.<number> - The encoded url.
Throws:

• Error If the URL Scheme prefix is unsupported. For a list of supported Scheme prefixes see: https://github.com/google/eddystone/tree/master/eddystone-url#url-scheme-prefix
• Error If the URL contains an invalid character. For a list of invalid characters see the Note in: https://github.com/google/eddystone/tree/master/eddystone-url#eddystone-url-http-url-encoding

See: Eddystone-URL

Param	Type	Description
url	string	The url to encode.

platform

platform() ⇒ Object ⏏

Detects what API is available in the platform.

Kind: Exported function
Returns: Object - An object that wraps the underlying BLE Advertising API
Throws:

• Error If the platform is unsupported

eddystone : Eddystone

The global eddystone instance.

Kind: global variable