react-native-eddystone

A simple Eddystone™ implementation in React Native for both iOS and Android. The library also include an opinionated beacon manager class that enables simple beacon telemetry linking, caching and expiration.

Installation

$ npm install @lg2/react-native-eddystone --save

If your React Native version is below 0.60

$ react-native link @lg2/react-native-eddystone

Manual installation (React Native < 0.60)

iOS

1. In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]
2. Go to node_modules ➜ @lg2 ➜ react-native-eddystone and add Eddystone.xcodeproj
3. In XCode, in the project navigator, select your project. Add libEddystone.a to your project's Build Phases ➜ Link Binary With Libraries
4. Run your project (Cmd+R)

Alternatively, you can use Cocoapods like so:

pod 'Eddystone', :path => '../node_modules/@lg2/react-native-eddystone/ios'

Android

1. Open up android/app/src/main/java/[...]/MainApplication.java

   • Add import com.lg2.eddystone.EddystonePackage; to the imports at the top of the file
   • Add new EddystonePackage() to the list returned by the getPackages() method

2. Append the following lines to android/settings.gradle:

   include ':@lg2_react-native-eddystone'
   project(':@lg2_react-native-eddystone').projectDir = new File(rootProject.projectDir, '../node_modules/@lg2/react-native-eddystone/android')
   

3. Insert the following lines inside the dependencies block in android/app/build.gradle:

   implementation project(':@lg2_react-native-eddystone')
   

Usage

This is a very simple example of how to listen to UID broadcastz from Eddystone beacons. For more examples, refer to the examples folder.

import Eddystone from "@lg2/react-native-eddystone";

// bind a callback when detecting a uid frame
Eddystone.addListener("onUIDFrame", function(beacon) {
  console.log(beacon);
});

// start listening for beacons
Eddystone.startScanning();

// stop listening for beacons
Eddystone.stopScanning();

API

Method	Arguments	Description
startScanning	none	Starts the device's bluetooth manager and looks for Eddystone beacons.
stopScanning	none	Stop the device's bluetooth manager from listening for Eddystone beacons.
addListener	event: string callback: Function	Registers a callback function to an event.
removeListener	event: string callback: Function	Unregisters a callback function to an event.
Manager	class	A simple beacon telemetry linking, caching and expiration class built on top of the current API. See below.

Events

There are many events that can be subscribed to using the library's addListener method.

Name	Parameters	Description
onUIDFrame	beacon: BeaconData	The device received information from a beacon broadcasting UID data.
onEIDFrame	beacon: BeaconData	The device received information from a beacon broadcasting EID data.
onURLFrame	url: URLData	The device received a Url broadcasted by a beacon.
onTelemetryFrame	telemetry: TelemetryData	The device received telemetry information from a beacon.
onStateChanged	state: string	The device's bluetooth manager state has changed. (iOS only)

Data Structures

BeaconData

{
  id: string,
  uid: string,
  rssi: number,
  txPower: number
}

TelemetryData

{
  uid: string,
  voltage: number,
  temp: number
}

URLData

{
  uid: string,
  url: string
}

Manager

API

Method	Arguments	Description
constructor	expiration: number	Creates a instance of the manager with a specific expiration time for beacons.
start	none	Starts the device's bluetooth manager and looks for Eddystone beacons.
stop	none	Stop the device's bluetooth manager from listening for Eddystone beacons.
has	uid: string	Determines whether or not the beacon exists within the manager or not.
addBeacon	data: BeaconData	Adds a beacon to the manager. This is done automatically when the start method is called but you're allowed to do it manually at any point.
addUrl	beacon: Beacon data: URLData	Updates a beacon to set its URL. This is done automatically when the start method is called but you're allowed to do it manually at any point.
addTelemetry	beacon: Beacon data: TelemetryData	Updates a beacon to set its telemetry data. This is done automatically when the start method is called but you're allowed to do it manually at any point.
addListener	event: string callback: Function	Registers a callback function to an event.
removeListener	event: string callback: Function	Unregisters a callback function to an event.

Events

Events that can be subscribed using the manager's addListener method.

Name	Parameters	Description
onBeaconAdded	beacon: Beacon	The manager received information from a new beacon broadcasting UID or EID data.
onBeaconUpdated	beacon: Beacon	The manager received information from a beacon broadcasting a URL or Telemetry data.
onBeaconExpired	beacon: Beacon	The manager has not received information from a beacon within the ammount of millisecond set by the expiration value.

Beacon

API

Method	Arguments	Description
constructor	data: BeaconData manager: Manager	Creates a instance of a beacon from data and manager
setExpiration	time: number	Sets the beacon expiration. This is done automatically by the manager but you're allowed to do it manually at any point.
getDistance	none	Returns the approximative distance in meters from the device.