diff --git a/src/index.ts b/src/index.ts index 5872852db..eba48092b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -36,6 +36,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'; @@ -147,6 +148,8 @@ export { Diagnostic, EmailComposer, Facebook, + EstimoteBeacons, + File, Flashlight, Globalization, GooglePlus, @@ -214,6 +217,7 @@ window['IonicNative'] = { Dialogs: Dialogs, Diagnostic: Diagnostic, EmailComposer: EmailComposer, + EstimoteBeacons: EstimoteBeacons, Facebook: Facebook, File: File, Flashlight: Flashlight, diff --git a/src/plugins/estimote-beacons.ts b/src/plugins/estimote-beacons.ts new file mode 100644 index 000000000..2896120c1 --- /dev/null +++ b/src/plugins/estimote-beacons.ts @@ -0,0 +1,482 @@ +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 */ + static ProximityUnknown = 0; + + /** Proximity value */ + static ProximityImmediate = 1; + + /** Proximity value */ + static ProximityNear = 2; + + /** Proximity value */ + static ProximityFar = 3; + + /** Beacon colour */ + static BeaconColorUnknown = 0; + + /** Beacon colour */ + static BeaconColorMintCocktail = 1; + + /** Beacon colour */ + static BeaconColorIcyMarshmallow = 2; + + /** Beacon colour */ + static BeaconColorBlueberryPie = 3; + /** + * Beacon colour. + */ + static BeaconColorSweetBeetroot = 4; + + /** Beacon colour */ + static BeaconColorCandyFloss = 5; + + /** Beacon colour */ + static BeaconColorLemonTart = 6; + + /** Beacon colour */ + static BeaconColorVanillaJello = 7; + + /** Beacon colour */ + static BeaconColorLiquoriceSwirl = 8; + + /** Beacon colour */ + static BeaconColorWhite = 9; + + /** Beacon colour */ + static BeaconColorTransparent = 10; + + /** Region state */ + static RegionStateUnknown = 'unknown'; + + /** Region state */ + static RegionStateOutside = 'outside'; + + /** Region state */ + 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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 { return; } + + /** + * 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 { 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 { 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', + clearWithArgs: true + }) + static startRangingBeaconsInRegion(region: BeaconRegion): Observable { 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 { 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', + clearWithArgs: true + }) + static startRangingSecureBeaconsInRegion(region: BeaconRegion): Observable { 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 { 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', + clearWithArgs: true, + successIndex: 1, + errorIndex: 2 + }) + static startMonitoringForRegion(region: BeaconRegion, notifyEntryStateOnDisplay: boolean): Observable { 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 { 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', + clearWithArgs: true, + successIndex: 1, + errorIndex: 2 + }) + static startSecureMonitoringForRegion(region: BeaconRegion, notifyEntryStateOnDisplay: boolean): Observable { 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 { 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 { return; } + + /** + * Disconnect from connected Estimote Beacon. Available on Android. + * + * @usage + * ``` + * EstimoteBeacons.disconnectConnectedBeacon(); + * ``` + * @return returns a Promise. + */ + @Cordova() + static disconnectConnectedBeacon(): Promise { 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 { 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 { 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 { return; } + +} + +export interface BeaconRegion { + state?: string; + major: number; + minor: number; + identifier?: string; + uuid: string; +}