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: stringcallback: Function | Registers a callback function to an event. | | removeListener | event: stringcallback: 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: stringcallback: Function | Registers a callback function to an event. | | removeListener | event: stringcallback: 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: BeaconDatamanager: 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. |