Estimate beacons plugin class

2025-02-21 00:23:00 +08:00 · 2016-07-27 10:07:33 +02:00 · 2016-07-27 10:07:33 +02:00 · 1da35968de
commit 1da35968de
parent 2c01d1998f
2 changed files with 528 additions and 0 deletions
--- a/src/index.ts
+++ b/src/index.ts
@ -35,6 +35,7 @@ import {DeviceOrientation} from './plugins/deviceorientation';
 import {Diagnostic} from './plugins/diagnostic';
 import {Dialogs} from './plugins/dialogs';
 import {EmailComposer} from './plugins/emailcomposer';
+import {EstimoteBeacons} from './plugins/estimote-beacons';
 import {Facebook} from './plugins/facebook';
 import {File} from './plugins/file';
 import {Transfer} from './plugins/filetransfer';
@ -129,6 +130,7 @@ export {
  Dialogs,
  Diagnostic,
  EmailComposer,
+  EstimoteBeacons,
  File,
  Flashlight,
  Geolocation,
@ -190,6 +192,7 @@ window['IonicNative'] = {
  Dialogs: Dialogs,
  Diagnostic: Diagnostic,
  EmailComposer: EmailComposer,
+  EstimoteBeacons: EstimoteBeacons,
  Facebook: Facebook,
  File: File,
  Flashlight: Flashlight,
--- a/src/plugins/estimote-beacons.ts
+++ b/src/plugins/estimote-beacons.ts
@ -0,0 +1,525 @@
+import { Cordova, Plugin } from './plugin';
+import { Observable } from 'rxjs/Observable';
+
+/**
+ * @name EstimoteBeacons
+ *
+ * @description
+ * This plugin enables communication between a phone and Estimote Beacons peripherals.
+ *
+ */
+@Plugin({
+  plugin: 'cordova-plugin-estimote',
+  pluginRef: 'estimote.beacons',
+  repo: 'https://github.com/evothings/phonegap-estimotebeacons',
+  platforms: ['iOS', 'Android']
+})
+export class EstimoteBeacons {
+
+  /** Proximity value */
+  public static ProximityUnknown = 0;
+
+  /** Proximity value */
+  public static ProximityImmediate = 1;
+
+  /** Proximity value */
+  public static ProximityNear = 2;
+
+  /** Proximity value */
+  public static ProximityFar = 3;
+
+  /** Beacon colour */
+  public static BeaconColorUnknown = 0;
+
+  /** Beacon colour */
+  public static BeaconColorMintCocktail = 1;
+
+  /** Beacon colour */
+  public static BeaconColorIcyMarshmallow = 2;
+
+  /** Beacon colour */
+  public static BeaconColorBlueberryPie = 3;
+  /**
+   * Beacon colour.
+   */
+  public static BeaconColorSweetBeetroot = 4;
+
+  /** Beacon colour */
+  public static BeaconColorCandyFloss = 5;
+
+  /** Beacon colour */
+  public static BeaconColorLemonTart = 6;
+
+  /** Beacon colour */
+  public static BeaconColorVanillaJello = 7;
+
+  /** Beacon colour */
+  public static BeaconColorLiquoriceSwirl = 8;
+
+  /** Beacon colour */
+  public static BeaconColorWhite = 9;
+
+  /** Beacon colour */
+  public static BeaconColorTransparent = 10;
+
+  /** Region state */
+  public static RegionStateUnknown = 'unknown';
+
+  /** Region state */
+  public static RegionStateOutside = 'outside';
+
+  /** Region state */
+  public static RegionStateInside = 'inside';
+
+  /**
+   * Ask the user for permission to use location services
+   * while the app is in the foreground.
+   * You need to call this function or requestAlwaysAuthorization
+   * on iOS 8+.
+   * Does nothing on other platforms.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.requestWhenInUseAuthorization().then(
+   *   () => { console.log('on success'); },
+   *   () => { console.log('on error'); }
+   * );
+   * ```
+   *
+   * @see {@link https://community.estimote.com/hc/en-us/articles/203393036-Estimote-SDK-and-iOS-8-Location-Services|Estimote SDK and iOS 8 Location Services}
+   * @return Returns a Promise.
+   */
+  @Cordova()
+  static requestWhenInUseAuthorization(): Promise<any> { return; }
+
+  /**
+   * Ask the user for permission to use location services
+   * whenever the app is running.
+   * You need to call this function or requestWhenInUseAuthorization
+   * on iOS 8+.
+   * Does nothing on other platforms.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.requestAlwaysAuthorization().then(
+   *   () => { console.log('on success'); },
+   *   () => { console.log('on error'); }
+   * );
+   * ```
+   *
+   * @see {@link https://community.estimote.com/hc/en-us/articles/203393036-Estimote-SDK-and-iOS-8-Location-Services|Estimote SDK and iOS 8 Location Services}
+   * @return Returns a Promise.
+   */
+  @Cordova()
+  static requestAlwaysAuthorization(): Promise<any> { return; }
+
+  /**
+   * Get the current location authorization status.
+   * Implemented on iOS 8+.
+   * Does nothing on other platforms.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.authorizationStatus().then(
+   *   (result) => { console.log('Location authorization status: ' + result); },
+   *   (errorMessage) => { console.log('Error: ' + errorMessage); }
+   * );
+   * ```
+   *
+   * @see {@link https://community.estimote.com/hc/en-us/articles/203393036-Estimote-SDK-and-iOS-8-Location-Services|Estimote SDK and iOS 8 Location Services}
+   * @return Returns a Promise.
+   */
+  @Cordova()
+  static authorizationStatus(): Promise<any> { return; }
+
+  /**
+   * Start advertising as a beacon.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.startAdvertisingAsBeacon('B9407F30-F5F8-466E-AFF9-25556B57FE6D', 1, 1, 'MyRegion')
+   *    .then(() => { console.log('Beacon started'); });
+   * setTimeout(() => {
+   *   EstimoteBeacons.stopAdvertisingAsBeacon().then((result) => { console.log('Beacon stopped'); });
+   * }, 5000);
+   * ```
+   * @param uuid {string} UUID string the beacon should advertise (mandatory).
+   * @param major {number} Major value to advertise (mandatory).
+   * @param minor {number} Minor value to advertise (mandatory).
+   * @param regionId {string} Identifier of the region used to advertise (mandatory).
+   * @return Returns a Promise.
+   */
+  @Cordova({
+    clearFunction: 'stopAdvertisingAsBeacon'
+  })
+  static startAdvertisingAsBeacon(uuid: string, major: number, minor: number, regionId: string): Promise<any> { return; }
+
+  /**
+   * Stop advertising as a beacon.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.startAdvertisingAsBeacon('B9407F30-F5F8-466E-AFF9-25556B57FE6D', 1, 1, 'MyRegion')
+   *    .then(() => { console.log('Beacon started'); });
+   * setTimeout(() => {
+   *   EstimoteBeacons.stopAdvertisingAsBeacon().then((result) => { console.log('Beacon stopped'); });
+   * }, 5000);
+   * ```
+   * @return Returns a Promise.
+   */
+  @Cordova()
+  static stopAdvertisingAsBeacon(): Promise<any> { return; }
+
+  /**
+   * Enable analytics.
+   *
+   * @see {@link http://estimote.github.io/iOS-SDK/Classes/ESTConfig.html|Further details}
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.enableAnalytics(true).then(() => { console.log('Analytics enabled'); });
+   * ```
+   * @param enable {number} Boolean value to turn analytics on or off (mandatory).
+   * @return Returns a Promise.
+   */
+  @Cordova()
+  static enableAnalytics(enable: boolean): Promise<any> { return; }
+
+  /**
+  * Test if analytics is enabled.
+  *
+  * @see {@link http://estimote.github.io/iOS-SDK/Classes/ESTConfig.html|Further details}
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.isAnalyticsEnabled().then((enabled) => { console.log('Analytics enabled: ' + enabled); });
+   * ```
+   * @return Returns a Promise.
+   */
+  @Cordova()
+  static isAnalyticsEnabled(): Promise<any> { return; }
+
+  /**
+  * Test if App ID and App Token is set.
+  *
+  * @see {@link http://estimote.github.io/iOS-SDK/Classes/ESTConfig.html|Further details}
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.isAuthorized().then((isAuthorized) => { console.log('App ID and App Token is set: ' + isAuthorized); });
+   * ```
+   * @return Returns a Promise.
+   */
+  @Cordova()
+  static isAuthorized(): Promise<any> { return; }
+
+  /**
+  * Set App ID and App Token.
+  *
+  * @see {@link http://estimote.github.io/iOS-SDK/Classes/ESTConfig.html|Further details}
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.setupAppIDAndAppToken('MyAppID', 'MyAppToken').then(() => { console.log('AppID and AppToken configured!'); });
+   * ```
+   * @param appID {string} The App ID (mandatory).
+   * @param appToken {string} The App Token (mandatory).
+   * @return Returns a Promise.
+   */
+  @Cordova()
+  static setupAppIDAndAppToken(appID: string, appToken: string): Promise<any> { return; }
+
+  /**
+   * Beacon region object.
+   * @typedef {Object} BeaconRegion
+   * @property {string} identifier Region identifier
+   * (id set by the application, not related actual beacons).
+   * @property {string} uuid The UUID of the region.
+   * @property {number} major The UUID major value of the region.
+   * @property {number} major The UUID minor value of the region.
+   */
+
+  /**
+   * Beacon info object. Consists of a region and an array of beacons.
+   * @typedef {Object} BeaconInfo
+   * @property {BeaconRegion} region Beacon region. Not available when scanning on iOS.
+   * @property {Beacon[]} beacons Array of {@link Beacon} objects.
+   */
+
+  /**
+   * Beacon object. Different properties are available depending on
+   * platform (iOS/Android) and whether scanning (iOS) or ranging (iOS/Android).
+   * @typedef {Object} Beacon
+   * @property {number} major Major value of the beacon (ranging/scanning iOS/Android).
+   * @property {number} color One of the estimote.beacons.BeaconColor* values (ranging/scanning iOS/Android).
+   * @property {number} rssi - The Received Signal Strength Indication (ranging/scanning, iOS/Android).
+   * @property {string} proximityUUID - UUID of the beacon (ranging iOS/Android)
+   * @property {number} proximity One of estimote.beacons.Proximity* values (ranging iOS).
+   * @property {string} macAddress (scanning iOS, ranging Android).
+   * @property {number} measuredPower (scanning iOS, ranging Android).
+   * @property {string} name The name advertised by the beacon (ranging Android).
+   * @property {number} distance Estimated distance from the beacon in meters (ranging iOS).
+   */
+
+  /**
+   * Region state object. This object is given as a result when
+   * monitoring for beacons.
+   * @typedef {Object} RegionState
+   * @property {string} identifier Region identifier
+   * (id set by the application, not related actual beacons).
+   * @property {string} uuid The UUID of the region.
+   * @property {number} major The UUID major value of the region.
+   * @property {number} major The UUID minor value of the region.
+   * @property {string} state One of
+   * {@link estimote.beacons.RegionStateInside},
+   * {@link estimote.beacons.RegionStateOutside},
+   * {@link estimote.beacons.RegionStateUnknown}.
+   */
+
+  /**
+   * Start scanning for all nearby beacons using CoreBluetooth (no region object is used).
+   * Available on iOS.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.startEstimoteBeaconDiscovery().subscribe(beacons => {
+   *   console.log(JSON.stringify(beacons));
+   * });
+   * setTimeout(() => {
+   *   EstimoteBeacons.stopEstimoteBeaconDiscovery().then(() => { console.log('scan stopped'); });
+   * }, 5000);
+   * ```
+   * @return Returns an Observable that notifies of each beacon discovered.
+   */
+  @Cordova({
+    observable: true,
+    clearFunction: 'stopEstimoteBeaconDiscovery'
+  })
+  static startEstimoteBeaconDiscovery(): Observable<any> { return; }
+
+  /**
+   * Stop CoreBluetooth scan. Available on iOS.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.startEstimoteBeaconDiscovery().subscribe(beacons => {
+   *   console.log(JSON.stringify(beacons));
+   * });
+   * setTimeout(() => {
+   *   EstimoteBeacons.stopEstimoteBeaconDiscovery().then(() => { console.log('scan stopped'); });
+   * }, 5000);
+   * ```
+   * @return returns a Promise.
+   */
+  @Cordova()
+  static stopEstimoteBeaconDiscovery(): Promise<any> { return; }
+
+  /**
+   * Start ranging beacons. Available on iOS and Android.
+   *
+   * @usage
+   * ```
+   * let region: BeaconRegion = {} // Empty region matches all beacons.
+   * EstimoteBeacons.startRangingBeaconsInRegion(region).subscribe(info => {
+   *   console.log(JSON.stringify(info));
+   * });
+   * setTimeout(() => {
+   *   EstimoteBeacons.stopRangingBeaconsInRegion(region).then(() => { console.log('scan stopped'); });
+   * }, 5000);
+   * ```
+   * @param region {BeaconRegion} Dictionary with region properties (mandatory).
+   * @return Returns an Observable that notifies of each beacon discovered.
+   */
+  @Cordova({
+    observable: true,
+    clearFunction: 'stopRangingBeaconsInRegion'
+  })
+  static startRangingBeaconsInRegion(region: BeaconRegion): Observable<any> { return; }
+
+  /**
+   * Stop ranging beacons. Available on iOS and Android.
+   *
+   * @usage
+   * ```
+   * let region: BeaconRegion = {} // Empty region matches all beacons.
+   * EstimoteBeacons.startRangingBeaconsInRegion(region).subscribe(info => {
+   *   console.log(JSON.stringify(info));
+   * });
+   * setTimeout(() => {
+   *   EstimoteBeacons.stopRangingBeaconsInRegion(region).then(() => { console.log('scan stopped'); });
+   * }, 5000);
+   * ```
+   * @param region {BeaconRegion} Dictionary with region properties (mandatory).
+   * @return returns a Promise.
+   */
+  @Cordova()
+  static stopRangingBeaconsInRegion(region: BeaconRegion): Promise<any> { return; }
+
+  /**
+   * Start ranging secure beacons. Available on iOS.
+   * This function has the same parameters/behaviour as
+   * {@link EstimoteBeacons.startRangingBeaconsInRegion}.
+   * To use secure beacons set the App ID and App Token using
+   * {@link EstimoteBeacons.setupAppIDAndAppToken}.
+   */
+  @Cordova({
+    observable: true,
+    clearFunction: 'stopRangingSecureBeaconsInRegion'
+  })
+  static startRangingSecureBeaconsInRegion(region: BeaconRegion): Observable<any> { return; }
+
+  /**
+   * Stop ranging secure beacons. Available on iOS.
+   * This function has the same parameters/behaviour as
+   * {@link EstimoteBeacons.stopRangingBeaconsInRegion}.
+   */
+  @Cordova()
+  static stopRangingSecureBeaconsInRegion(region: BeaconRegion): Promise<any> { return; }
+
+  /**
+   * Start monitoring beacons. Available on iOS and Android.
+   *
+   * @usage
+   * ```
+   * let region: BeaconRegion = {} // Empty region matches all beacons.
+   * EstimoteBeacons.startMonitoringForRegion(region).subscribe(state => {
+   *   console.log('Region state: ' + JSON.stringify(state));
+   * });
+   * ```
+   * @param region {BeaconRegion} Dictionary with region properties (mandatory).
+   * @param [notifyEntryStateOnDisplay=false] {boolean} Set to true to detect if you
+   * are inside a region when the user turns display on, see
+   * {@link https://developer.apple.com/library/prerelease/ios/documentation/CoreLocation/Reference/CLBeaconRegion_class/index.html#//apple_ref/occ/instp/CLBeaconRegion/notifyEntryStateOnDisplay|iOS documentation}
+   * for further details (optional, defaults to false, iOS only).
+   * @return Returns an Observable that notifies of each region state discovered.
+   */
+  @Cordova({
+    observable: true,
+    clearFunction: 'stopMonitoringForRegion',
+    successIndex: 1,
+    errorIndex: 2
+  })
+  static startMonitoringForRegion(region: BeaconRegion, notifyEntryStateOnDisplay: boolean): Observable<any> { return; }
+
+  /**
+   * Stop monitoring beacons. Available on iOS and Android.
+   *
+   * @usage
+   * ```
+   * let region: BeaconRegion = {} // Empty region matches all beacons.
+   * EstimoteBeacons.stopMonitoringForRegion(region).then(() => { console.log('monitoring is stopped'); });
+   * ```
+   * @param region {BeaconRegion} Dictionary with region properties (mandatory).
+   * @return returns a Promise.
+   */
+  @Cordova()
+  static stopMonitoringForRegion(region: BeaconRegion): Promise<any> { return; }
+
+  /**
+   * Start monitoring secure beacons. Available on iOS.
+   * This function has the same parameters/behaviour as
+   * EstimoteBeacons.startMonitoringForRegion.
+   * To use secure beacons set the App ID and App Token using
+   * {@link EstimoteBeacons.setupAppIDAndAppToken}.
+   * @see {@link EstimoteBeacons.startMonitoringForRegion}
+   */
+  @Cordova({
+    observable: true,
+    clearFunction: 'stopSecureMonitoringForRegion',
+    successIndex: 1,
+    errorIndex: 2
+  })
+  static startSecureMonitoringForRegion(region: BeaconRegion, notifyEntryStateOnDisplay: boolean): Observable<any> { return; }
+
+
+  /**
+  * Stop monitoring secure beacons. Available on iOS.
+  * This function has the same parameters/behaviour as
+  * {@link EstimoteBeacons.stopMonitoringForRegion}.
+  */
+  @Cordova()
+  static stopSecureMonitoringForRegion(region: BeaconRegion): Promise<any> { return; }
+
+  /**
+   * Connect to Estimote Beacon. Available on Android.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.connectToBeacon(FF:0F:F0:00:F0:00);
+   * ```
+   * ```
+   * EstimoteBeacons.connectToBeacon({
+   *     proximityUUID: '000000FF-F00F-0FF0-F000-000FF0F00000',
+   *     major: 1,
+   *     minor: 1
+   *   });
+   * ```
+   * @param beacon {Beacon} Beacon to connect to.
+   * @return returns a Promise.
+   */
+  @Cordova()
+  static connectToBeacon(beacon: any): Promise<any> { return; }
+
+  /**
+   * Disconnect from connected Estimote Beacon. Available on Android.
+   *
+   * @usage
+   * ```
+   * EstimoteBeacons.disconnectConnectedBeacon();
+   * ```
+   * @return returns a Promise.
+   */
+  @Cordova()
+  static disconnectConnectedBeacon(): Promise<any> { return; }
+
+  /**
+   * Write proximity UUID to connected Estimote Beacon. Available on Android.
+   *
+   * @usage
+   * ```
+   * // Example that writes constant ESTIMOTE_PROXIMITY_UUID
+   * EstimoteBeacons.writeConnectedProximityUUID(ESTIMOTE_PROXIMITY_UUID);
+   *
+   * @param uuid {string} String to write as new UUID
+   * @return returns a Promise.
+   */
+  @Cordova()
+  static writeConnectedProximityUUID(uuid: any): Promise<any> { return; }
+
+  /**
+   * Write major to connected Estimote Beacon. Available on Android.
+   *
+   * @usage
+   * ```
+   * // Example that writes 1
+   * EstimoteBeacons.writeConnectedMajor(1);
+   *
+   * @param major {number} number to write as new major
+   * @return returns a Promise.
+   */
+  @Cordova()
+  static writeConnectedMajor(major: number): Promise<any> { return; }
+
+  /**
+   * Write minor to connected Estimote Beacon. Available on Android.
+   *
+   * @usage
+   * ```
+   * // Example that writes 1
+   * EstimoteBeacons.writeConnectedMinor(1);
+   *
+   * @param minor {number} number to write as new minor
+   * @return returns a Promise.
+   */
+  @Cordova()
+  static writeConnectedMinor(minor: number): Promise<any> { return; }
+
+}
+
+export interface BeaconRegion {
+  state?: string;
+  major: number;
+  minor: number;
+  identifier?: string;
+  uuid: string;
+}