Deprecation Notice

This Cordova / Phonegap plugin for the BlueCats Mobile SDK is no longer actively maintained by the BlueCats team. We recommend the use of the following native mobile SDKs:

iOS (Objective-C or Swift): https://github.com/bluecats/bluecats-ios-sdk
Android: https://github.com/bluecats/bluecats-android-sdk

If you have further questions please contact BlueCats Support: [email protected]

com.bluecats.beacons

This plugin provides a Phonegap or Cordova app access to Bluetooth Low Energy iBeacons and Beacons via the BlueCats (www.bluecats.com) BLE SDKs for iOS and Android.

Installation

Cordova

cordova plugin add https://github.com/bluecats/bluecats-phonegap.git

Phonegap

phonegap plugin add https://github.com/bluecats/bluecats-phonegap.git

Supported Platforms

iOS
Android if you have any trouble to get SDK starting purring, please refer to our Wiki or FAQ

Methods

com.bluecats.beacons.startPurringWithAppToken
com.bluecats.beacons.watchMicroLocation
com.bluecats.beacons.watchEnterBeacon
com.bluecats.beacons.watchExitBeacon
com.bluecats.beacons.watchClosestBeaconChange
com.bluecats.beacons.clearWatch
com.bluecats.beacons.localNotificationReceived
com.bluecats.beacons.scheduleLocalNotification
com.bluecats.beacons.cancelAllLocalNotifications

Objects

SDKOptions
BeaconWatchOptions
MicroLocation

Quick Starts

Hello Beacons

Quick Start for com.bluecats.beacons plugin

This plugin provides a Phonegap or Cordova app access to Bluetooth Low Energy iBeacons and Beacons via the BlueCats (www.bluecats.com) BLE SDKs for iOS and Android.

This sample creates the default 'Hello World' Phonegap project and extends with Beacon functionality.

Phonegap

phonegap create MyCordovaProject
cd MyCordovaProject
phonegap plugin add https://github.com/bluecats/bluecats-phonegap.git
cp plugins/com.bluecats.beacons/Samples/HelloBeacons/index.js www/js/index.js

Edit www/js/index.js and update the line:

var blueCatsAppToken = 'BLUECATS-APP-TOKEN';

replacing BLUECATS-APP-TOKEN with your app token generated in the BlueCats console: https://app.bluecats.com/apps

If building for iOS

phonegap platform add ios
phonegap build ios

If building for Android

phonegap platform add android
phonegap build android

PList Entries for iOS 8.0

iOS 8 requires a description for the reason for accessing the user's location information. Currently this needs to be added manually to the iOS project generated by Cordova / PhoneGap see https://github.com/bluecats/bluecats-ios-sdk/wiki/Location-Usage-Description-and-Requesting-Location-Access#location-usage-description

Cordova

If using Cordova replace the phonegap in the above commands with cordova

com.bluecats.beacons.startPurringWithAppToken

Initialises the BlueCats SDK and starts scanning for bluetooth devices. The app token is generated in the BlueCats web console: https://app.bluecats.com

com.bluecats.beacons.startPurringWithAppToken(appToken, success, error, sdkOptions)

Example

function success() {
    alert('BlueCats SDK is purring');
    //Start watching beacons using com.bluecats.beacons.watchEnterBeacon etc.
};

function error() {
    alert('onError!');
};

var sdkOptions = {
    trackBeaconVisits:true, //Log visits to beacons to the BlueCats api
    useLocalStorage:true, //Cache beacons in local db for offline availability
    cacheAllBeaconsForApp:true, //Cache all beacons on startup
    discoverBeaconsNearby:true, //Cache beacons as detected by the device
    cacheRefreshTimeIntervalInSeconds:300 //Period to check for changes in seconds
};

com.bluecats.beacons.startPurringWithAppToken('YOUR-APP-TOKEN', success, error, sdkOptions);

com.bluecats.beacons.watchMicroLocation

Provides beacons and sites in range of the device and their current proximity.

The returned watch ID references the particular watch configuration, and can be used with com.bluecats.beacons.clearWatch to stop watching the beacons.

var watchID = com.bluecats.beacons.watchMicroLocation(success,
                                                       error,
                                                       beaconWatchOptions);

Example

function success(watchData) {
  var beacons = watchData.filteredMicroLocation.beacons;
  var sites = watchData.filteredMicroLocation.sites;
    alert('Beacons: ' + beacons.length + '\n' +
          'Sites: ' + sites.length);
};

function error() {
    alert('error!');
};

var beaconWatchOptions = {
  minimumTriggerIntervalInSeconds:2, //Integer. Minimum seconds between callbacks (default 1)
  repeatCount:3, //Integer. Default repeat infinite
    filter:{
      minimumProximity:'BC_PROXIMITY_IMMEDIATE', //String. Closest proximity to include. Default BC_PROXIMITY_IMMEDIATE
      maximumProximity:'BC_PROXIMITY_NEAR', //String. Furthest proximity to include. Default BC_PROXIMITY_UNKNOWN
      minimumAccuracy:0, //Number. Minimum distance in metres (Default 0)
        maximumAccuracy:0.5 //Number. Maximum distance in metres (Default unrestricted)
        sitesNamed:['Site1','Another Site'],//Array of string. Only include beacons in specified sites
        categoriesNamed:['Entrance','Another Category'],//Array of string. Only include beacons in specified categories

    }
};

var watchID = com.bluecats.beacons.watchMicroLocation(success,
                                                       error,
                                                       beaconWatchOptions);

com.bluecats.beacons.watchEnterBeacon

Provides beacons and sites as they come into range as specified by beaconWatchOptions filters.

The returned watch ID references the particular watch configuration, and can be used with com.bluecats.beacons.clearWatch to stop watching the beacons.

var watchID = com.bluecats.beacons.watchEnterBeacon(success,
                                                       error,
                                                       beaconWatchOptions);

Example

function success(watchData) {
  var beacons = watchData.filteredMicroLocation.beacons;
  var sites = watchData.filteredMicroLocation.sites;
    alert('Entered Beacons: ' + beacons.length + '\n' +
          'Sites: ' + sites.length);
};

function error() {
    alert('error!');
};

var beaconWatchOptions = {
  minimumTriggerIntervalInSeconds:2, //Integer. Minimum seconds between callbacks (default 1)
  repeatCount:3, //Integer. Default repeat infinite
  secondsBeforeExitBeacon:5, //Integer. Seconds after beacon leaves range before it can re-enter (Default 5)
    filter:{
      minimumProximity:'BC_PROXIMITY_IMMEDIATE', //String. Closest proximity to include. Default BC_PROXIMITY_IMMEDIATE
      maximumProximity:'BC_PROXIMITY_NEAR', //String. Furthest proximity to include. Default BC_PROXIMITY_UNKNOWN
      minimumAccuracy:0, //Number. Minimum distance in metres (Default 0)
        maximumAccuracy:0.5 //Number. Maximum distance in metres (Default unrestricted)
        sitesNamed:['Site1','Another Site'],//Array of string. Only include beacons in specified sites
        categoriesNamed:['Entrance','Another Category'],//Array of string. Only include beacons in specified categories
    }
};

var watchID = com.bluecats.beacons.watchEnterBeacon(success,
                                                       error,
                                                       beaconWatchOptions);

com.bluecats.beacons.watchExitBeacon

Provides beacons and sites as they leave range as specified by beaconWatchOptions filters.

The returned watch ID references the particular watch configuration, and can be used with com.bluecats.beacons.clearWatch to stop watching the beacons.

var watchID = com.bluecats.beacons.watchExitBeacon(success,
                                                       error,
                                                       beaconWatchOptions);

Example

function success(watchData) {
  var beacons = watchData.filteredMicroLocation.beacons;
  var sites = watchData.filteredMicroLocation.sites;
    alert('Exited Beacons: ' + beacons.length + '\n' +
          'Sites: ' + sites.length);
};

function error() {
    alert('error!');
};

var beaconWatchOptions = {
  minimumTriggerIntervalInSeconds:2, //Integer. Minimum seconds between callbacks (default 1)
  repeatCount:3, //Integer. Default repeat infinite
  secondsBeforeExitBeacon:5, //Integer. Seconds after beacon leaves range before counts as 'exited' (Default 5)
    filter:{
      minimumProximity:'BC_PROXIMITY_IMMEDIATE', //String. Closest proximity to include. Default BC_PROXIMITY_IMMEDIATE
      maximumProximity:'BC_PROXIMITY_NEAR', //String. Furthest proximity to include. Default BC_PROXIMITY_UNKNOWN
      minimumAccuracy:0, //Number. Minimum distance in metres (Default 0)
        maximumAccuracy:0.5 //Number. Maximum distance in metres (Default unrestricted)
        sitesNamed:['Site1','Another Site'],//Array of string. Only include beacons in specified sites
        categoriesNamed:['Entrance','Another Category'],//Array of string. Only include beacons in specified categories
    }
};

var watchID = com.bluecats.beacons.watchExitBeacon(success,
                                                       error,
                                                       beaconWatchOptions);

com.bluecats.beacons.watchClosestBeaconChange

Provides the closest beacon and its site if the current closest beacon changes as specified by beaconWatchOptions filters.

The returned watch ID references the particular watch configuration, and can be used with com.bluecats.beacons.clearWatch to stop watching the beacons.

var watchID = com.bluecats.beacons.watchClosestBeaconChange(success,
                                                       error,
                                                       beaconWatchOptions);

Example

function success(watchData) {
  var closestBeacon = watchData.filteredMicroLocation.beacons[0];
  var site = watchData.filteredMicroLocation.sites[0];
    alert('Closest Beacon is: ' + closestBeacon.name + '\n' +
          'In Site: ' + site.name);
};

function error() {
    alert('error!');
};

var beaconWatchOptions = {
  minimumTriggerIntervalInSeconds:2, //Integer. Minimum seconds between callbacks (default 1)
  repeatCount:3, //Integer. Default repeat infinite
  secondsBeforeExitBeacon:5, //Integer. Seconds after beacon leaves range before counts as 'exited' (Default 5)
    filter:{
      minimumProximity:'BC_PROXIMITY_IMMEDIATE', //String. Closest proximity to include. Default BC_PROXIMITY_IMMEDIATE
      maximumProximity:'BC_PROXIMITY_NEAR', //String. Furthest proximity to include. Default BC_PROXIMITY_UNKNOWN
      minimumAccuracy:0, //Number. Minimum distance in metres (Default 0)
        maximumAccuracy:0.5 //Number. Maximum distance in metres (Default unrestricted)
        sitesNamed:['Site1','Another Site'],//Array of string. Only include beacons in specified sites
        categoriesNamed:['Entrance','Another Category'],//Array of string. Only include beacons in specified categories
    }
};

var watchID = com.bluecats.beacons.watchClosestBeaconChange(success,
                                                       error,
                                                       beaconWatchOptions);

com.bluecats.beacons.clearWatch

Stop watching beacons referenced by the watchID parameter.

com.bluecats.beacons.clearWatch(watchID);

watchID: The ID returned by com.bluecats.beacons.watchMicroLocation or com.bluecats.beacons.watchEnterBeacon or com.bluecats.beacons.watchExitBeacon or com.bluecats.beacons.watchClosestBeaconChange.

Example

var watchID = com.bluecats.beacons.watchEnterBeacon(onSuccess, onError, options);

// ... later on ...

com.bluecats.beacons.clearWatch(watchID);

com.bluecats.beacons.localNotificationReceived

Notifies when the app is launched by tapping open any local notification (not only notifications triggered by beacons)

The returned watch ID references the particular watch configuration, and can be used with com.bluecats.beacons.clearWatch to stop watching the beacons.

com.bluecats.beacons.localNotificationReceived(success, error);

Example

function success(notificationData) {
    alert('Notification received' + JSON.stringify(notificationData));
};

function error() {
    alert('error!');
};

com.bluecats.beacons.localNotificationReceived(success, error);

com.bluecats.beacons.scheduleLocalNotification

Schedules a local notification to be triggered by detecting a beacon matching the specified local notification options

com.bluecats.beacons.scheduleLocalNotification(success, error);

Example

function success() {
    alert('Scheduled notification'));
};

function error() {
    alert('error!');
};

var categoryToTriggerByName = {name:'Entrance'};
var categoryToTriggerById = {id:'BLUECATS-CATEGORY-ID'};
var customNotificationData = {someKey:'key1', anotherKey:'other data'};
var localNotification = {
  fireInCategories:[categoryToTriggerByName,categoryToTriggerById],
  fireAfterDelayInSeconds:60,//Delay the earliest time this notification can trigger. Once the delay has passed, the other criteria will need to be met before triggering.
  alertAction:'View this',
  alertBody:'Welcome back. Here is some great info for you.',
  userInfo:customNotificationData //This object will be provided as notificationData to com.bluecats.beacons.localNotificationReceived callback
};

com.bluecats.beacons.scheduleLocalNotification(localNotification, success, error);

com.bluecats.beacons.cancelAllLocalNotifications

Cancels all local notifications scheduled by com.bluecats.beacons.scheduleLocalNotification that have not yet been triggered/presented.

com.bluecats.beacons.cancelAllLocalNotifications(success, error);

Example

function success() {
    alert('Cancelled all beacon triggered local notifications'));
};

function error() {
    alert('error!');
};

com.bluecats.beacons.cancelAllLocalNotifications(success, error);

BeaconWatchData and MicroLocation

Each of the beacon watch success callbacks com.bluecats.beacons.watchMicroLocation or com.bluecats.beacons.watchEnterBeacon or com.bluecats.beacons.watchExitBeacon or com.bluecats.beacons.watchClosestBeaconChange returns a 'beaconWatchData' object. This contains details of the beacons that met the specified filters and configuration of the watch instance.

Example BeaconWatchData

{
  triggeredCount:3,
  filteredMicroLocation:{}//See 'MicroLocation' below
}

Example MicroLocation

{
  "beacons": [
      {
        "id": "c0563500-dca2-69a2-9541-126eb7d81234",
        "teamID": "7e680e00-7ba2-8ab2-3943-f06fccd91234",
        "proximity": "BC_PROXIMITY_FAR",
        "bluetoothAddress": "000780681234",
        "siteID": "ef615500-7ba2-2e88-1f46-d12e5fb11324",
        "version": 20,
        "proximityUUID": "61687109-905F-4436-91F8-E602F514C96D",
        "siteName": "BlueCats HQ",
        "accuracy": 6.1271604369518,
        "rssi": -96,
        "categories": [
          {
            "id": "cf0c5100-faa2-e1a0-ce4b-a5372eb11234",
            "name": "Soft Drinks"
          },
          {
            "id": "2a096301-81a2-7db7-2847-fd74630f1234",
            "name": "Food"
          }
        ],
        "name": "BlueCats iBeacon",
        "minor": 1010,
        "measuredPowerAt1Meter": -94,
        "major": 3
      },
      {
        "id": "0ef43100-dca2-d0a6-2041-e35e0dee1234",
        "teamID": "7e680e00-7ba2-8ab2-3943-f06fccd91234",
        "proximity": "BC_PROXIMITY_NEAR",
        "bluetoothAddress": "000780681234",
        "siteID": "8e4d1400-9aa2-668b-c44f-d14b1a0f1234",
        "version": 19,
        "proximityUUID": "61687109-905F-4436-91F8-E602F514C96D",
        "siteName": "Another Site",
        "accuracy": 0.37260415444465,
        "rssi": -73,
        "categories": [
          {
            "id": "8db32e00-01a3-f0ac-db4d-dbc9f1271234",
            "name": "Entrance"
          }
        ],
        "name": "BlueCats iBeacon",
        "minor": 1001,
        "measuredPowerAt1Meter": -82,
        "major": 3
      }
    ]
  },
  "sites": [
    {
      "name": "BlueCats HQ",
      "id": "ef615500-7ba2-2e88-1f46-d12e5fb11234",
      "teamID": "7e680e00-7ba2-8ab2-3943-f06fccd91234",
      "beaconCount": 3
    },
    {
      "name": "Another Site",
      "id": "8e4d1400-9aa2-668b-c44f-d14b1a0f1234",
      "teamID": "7e680e00-7ba2-8ab2-3943-f06fccd91234",
      "beaconCount": 2
    }
  ]
}

Beacon

A beacon represents a single Bluetooth beacon device. It contains both static information about the beacon as well as the current state of the range beacon such as proximity and accuracy.

id: string Bluecats unique identifier for this beacon
teamID: string BlueCats unique identifier for the team this beacon belongs to
proximity: string Simplified classification of the distance to the beacon. Available values are: BC_PROXIMITY_IMMEDIATE (~~< 0.5m) BC_PROXIMITY_NEAR (~~< 3m) BC_PROXIMITY_FAR (~>3m) BC_PROXIMITY_UNKNOWN (unable to determine distance). These distances are approximations only and will vary by device and beacon configuration.
bluetoothAddress: string Unique identifier for the bluetooth device
siteID: string BlueCats unique identifier for the site this beacon belongs to
version: integer Updates made to a beacon that need to be flashed to the physical beacon increments the version number
siteName: string The name of the site the beacon belongs to
accuracy: double Approximate distance from the beacon in metres.
rssi: integer Strength of the signal from the beacon. Can be in the range 0 to -100. The closer to zero the strong the signal
categories: array see 'Category' Categories 'tag' beacons with extra information. For example a beacon can be tagged with the category 'Entrance' to signify it is the entrance to a building or 'Refreshments' to signify it is a refreshment area etc.
name: string A friendly name for the beacon
proximityUUID: string The first component of the iBeacon identity
major: integer The second component of an iBeacon identity
minor: integer The third component of an iBeacon identity
measuredPowerAt1Meter: integer This is the expected rssi to be measured when a device is 1 meter from the beacon. This could be used for custom distance calculations.

Site

A site is used by the BlueCats platform to group beacons into a physical location such as a single building or address.

name: string Friendly name for the site
id:id string Bluecats unique identifier for the site
teamID: string BlueCats unique identifier for the team this site belongs to
beaconCount: integer Total number of beacons in this site (whether or not they are in range)

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
Samples/HelloBeacons		Samples/HelloBeacons
src		src
README.md		README.md
SampleMicroLocation.json		SampleMicroLocation.json
blueCatsSDKCDVPlugin.js		blueCatsSDKCDVPlugin.js
conf.json		conf.json
gitignore		gitignore
package.json		package.json
plugin.xml		plugin.xml
push.gradle		push.gradle

bluecats/bluecats-phonegap

Folders and files

Latest commit

History

Repository files navigation

Deprecation Notice

com.bluecats.beacons

Installation

Supported Platforms

Methods

Objects

Quick Starts

Hello Beacons

Quick Start for com.bluecats.beacons plugin

Phonegap

PList Entries for iOS 8.0

Cordova

com.bluecats.beacons.startPurringWithAppToken

Example

com.bluecats.beacons.watchMicroLocation

Example

com.bluecats.beacons.watchEnterBeacon

Example

com.bluecats.beacons.watchExitBeacon

Example

com.bluecats.beacons.watchClosestBeaconChange

Example

com.bluecats.beacons.clearWatch

Example

com.bluecats.beacons.localNotificationReceived

Example

com.bluecats.beacons.scheduleLocalNotification

Example

com.bluecats.beacons.cancelAllLocalNotifications

Example

BeaconWatchData and MicroLocation

Example BeaconWatchData

Example MicroLocation

Beacon

Site

Category

About

Resources

Stars

Watchers

Forks

Releases 6

Packages 0

Contributors 4

Languages

Packages