diff --git a/src/@ionic-native/plugins/background-geolocation/index.ts b/src/@ionic-native/plugins/background-geolocation/index.ts index 7e9fa5c1e..daab02ebf 100644 --- a/src/@ionic-native/plugins/background-geolocation/index.ts +++ b/src/@ionic-native/plugins/background-geolocation/index.ts @@ -2,253 +2,490 @@ import { Injectable } from '@angular/core'; import { Cordova, IonicNativePlugin, Plugin } from '@ionic-native/core'; import { Observable } from 'rxjs/Observable'; +export enum BackgroundGeolocationLocationCode { + PERMISSION_DENIED = 1, + LOCATION_UNAVAILABLE = 2, + TIMEOUT = 3 +} + +export enum BackgroundGeolocationNativeProvider { + gps = 'gps', + network = 'network', + passive = 'passive', + fused = 'fused' +} + +export enum BackgroundGeolocationLocationProvider { + DISTANCE_FILTER_PROVIDER = 0, + ACTIVITY_PROVIDER = 1, + RAW_PROVIDER = 2 +} + +export enum BackgroundGeolocationEvents { + http_authorization = 'http_authorization', // Triggered when server responded with "401 Unauthorized" to post/sync request. + abort_requested = 'abort_requested', // Triggered when server responded with "285 Updates Not Required" to post/sync request. + background = 'background', // Triggered when app entered background state and (not visible to the user). + foreground = 'foreground', // Triggered when app entered foreground state and (visible to the user). + authorization = 'authorization', // Triggered when user changes authorization/permissions for the app or toggles location services. + error = 'error', // Register error listener. + stop = 'stop', // Triggered when background service has been stopped succesfully. + start = 'start', // Event is triggered when background service has been started succesfully. + activity = 'activity', // Register activity monitoring listener. + stationary = 'stationary', // Register stationary location event listener. + location = 'location' // Register location event listener. +} + +export enum BackgroundGeolocationAuthorizationStatus { + NOT_AUTHORIZED = 0, + AUTHORIZED = 1, + AUTHORIZED_FOREGROUND = 2 +} + +export enum BackgroundGeolocationLogLevel { + TRACE = 'TRACE', + DEBUG = 'DEBUG', + INFO = 'INFO', + WARN = 'WARN', + ERROR = 'ERROR' +} + +export interface BackgroundGeolocationLogEntry { + /** ID of log entry as stored in db. */ + id: number; + + /** Timestamp in milliseconds since beginning of UNIX epoch. */ + timestamp: number; + + /** Log level */ + level: BackgroundGeolocationLogLevel; + + /** Log message */ + message: string; + + /** Recorded stacktrace. (Android only, on iOS part of message) */ + stackTrace: string; +} + +export interface ServiceStatus { + /** TRUE if service is running. */ + isRunning: boolean; + + /** TRUE if location services are enabled */ + locationServicesEnabled: boolean; + + /** + * Authorization status. + * + * Posible values: + * NOT_AUTHORIZED, AUTHORIZED, AUTHORIZED_FOREGROUND + * + * @example + * if (authorization == BackgroundGeolocation.NOT_AUTHORIZED) {...} + */ + authorization: BackgroundGeolocationAuthorizationStatus; +} + +export interface BackgroundGeolocation { + code: BackgroundGeolocationLocationCode; + message: string; +} + +export interface BackgroundGeolocationCurrentPositionConfig { + timeout: number; + maximumAge: number; + enableHighAccuracy: boolean; +} + export interface BackgroundGeolocationResponse { - /** - * ID of location as stored in DB (or null) - */ - locationId: number; + /** ID of location as stored in DB (or null) */ + id: number; /** - * Service provider + * Native provider reponsible for location. + * + * Possible values: + * "gps", "network", "passive" or "fused" */ - serviceProvider: string; + provider: BackgroundGeolocationNativeProvider; - /** - * true if location recorded as part of debug - */ - debug: boolean; + /** Configured location provider. */ + locationProvider: BackgroundGeolocationLocationProvider; - /** - * UTC time of this fix, in milliseconds since January 1, 1970. - */ + /** UTC time of this fix, in milliseconds since January 1, 1970. */ time: number; - /** - * latitude, in degrees. - */ + /** Latitude, in degrees. */ latitude: number; - /** - * longitude, in degrees. - */ + /** Longitude, in degrees. */ longitude: number; - /** - * estimated accuracy of this location, in meters. - */ + /** Estimated accuracy of this location, in meters. */ accuracy: number; /** - * speed if it is available, in meters/second over ground. + * Speed if it is available, in meters/second over ground. + * + * Note: Not all providers are capable of providing speed. + * Typically network providers are not able to do so. */ speed: number; - /** - * altitude if available, in meters above the WGS 84 reference ellipsoid. - */ + /** Altitude if available, in meters above the WGS 84 reference ellipsoid. */ altitude: number; - /** - * accuracy of the altitude if available. - */ - altitudeAccuracy: number; - - /** - * bearing, in degrees. - */ + /** Bearing, in degrees. */ bearing: number; /** - * A Coordinates object defining the current location + * True if location was recorded by mock provider. (ANDROID ONLY) + * + * Note: this property is not enabled by default! + * You can enable it "postTemplate" configure option. */ - coords: Coordinates; + isFromMockProvider?: boolean; /** - * A timestamp representing the time at which the location was retrieved. + * True if device has mock locations enabled. (ANDROID ONLY) + * + * Note: this property is not enabled by default! + * You can enable it "postTemplate" configure option. */ - timestamp: number; + mockLocationsEnabled?: boolean; } export interface BackgroundGeolocationConfig { /** - * Desired accuracy in meters. Possible values [0, 10, 100, 1000]. The lower - * the number, the more power devoted to GeoLocation resulting in higher - * accuracy readings. 1000 results in lowest power drain and least accurate - * readings. @see Apple docs (https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/index.html#//apple_ref/occ/instp/CLLocationManager/desiredAccuracy) - */ - desiredAccuracy: number; - - /** - * Stationary radius in meters. When stopped, the minimum distance the device - * must move beyond the stationary location for aggressive background-tracking - * to engage. - */ - stationaryRadius: number; - - /** - * When enabled, the plugin will emit sounds for life-cycle events of - * background-geolocation! See debugging sounds table. - */ - debug?: boolean; - - /** - * The minimum distance (measured in meters) a device must move horizontally - * before an update event is generated. @see Apple docs. (https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/CLLocationManager/CLLocationManager.html#//apple_ref/occ/instp/CLLocationManager/distanceFilter) - */ - distanceFilter: number; - - /** - * IOS, ANDROID ONLY - * Enable this in order to force a stop() when the application terminated - * (e.g. on iOS, double-tap home button, swipe away the app).o + * Set location provider * - * Defaults to true - */ - stopOnTerminate?: boolean; - - /** - * ANDROID ONLY - * Start background service on device boot. + * Platform: all + * Available providers: + * DISTANCE_FILTER_PROVIDER, + * ACTIVITY_PROVIDER + * RAW_PROVIDER * - * Defaults to false - */ - startOnBoot?: boolean; - - /** - * ANDROID ONLY - * If false location service will not be started in foreground and no notification will be shown. - * - * Defaults to true - */ - startForeground?: boolean; - - /** - * ANDROID ONLY - * When using BackgroundGeolocation.LocationProvider.ANDROID_DISTANCE_FILTER_PROVIDER: - * The minimum time interval between location updates in milliseconds. - * @see Android docs (http://developer.android.com/reference/android/location/LocationManager.html#requestLocationUpdates(long,%20float,%20android.location.Criteria,%20android.app.PendingIntent)) - * and the MS doc (http://msdn.microsoft.com/en-us/library/windows/apps/windows.devices.geolocation.geolocator.reportinterval) - * for more information - * When using BackgroundGeolocation.LocationProvider.ANDROID_ACTIVITY_PROVIDER: - * Rate in milliseconds at which your app prefers to receive location updates. - * @see Android docs (https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest.html#getInterval()) - */ - interval?: number; - - /** - * ANDROID ONLY - * Custom notification title in the drawer. - */ - notificationTitle?: string; - - /** - * ANDROID ONLY - * Custom notification text in the drawer. - */ - notificationText?: string; - - /** - * ANDROID ONLY - * The accent color to use for notification. Eg. #4CAF50. - */ - notificationIconColor?: string; - - /** - * ANDROID ONLY - * The filename of a custom notification icon. See android quirks. - * NOTE: Only available for API Level >=21. - */ - notificationIconLarge?: string; - - /** - * ANDROID ONLY - * The filename of a custom notification icon. See android quirks. - * NOTE: Only available for API Level >=21. - */ - notificationIconSmall?: string; - - /** - * ANDROID ONLY - * Set location service provider @see wiki (https://github.com/mauron85/cordova-plugin-background-geolocation/wiki/Android-providers) + * @default DISTANCE_FILTER_PROVIDER + * @example + * { locationProvider: LocationProvider.RAW_PROVIDER } */ locationProvider?: number; /** - * IOS ONLY - * [AutomotiveNavigation, OtherNavigation, Fitness, Other] Presumably, - * this affects iOS GPS algorithm. @see Apple docs for more information - * (https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLLocationManager_Class/CLLocationManager/CLLocationManager.html#//apple_ref/occ/instp/CLLocationManager/activityType) + * Desired accuracy in meters. + * + * Platform: all + * Provider: all + * Possible values: + * HIGH_ACCURACY, + * MEDIUM_ACCURACY, + * LOW_ACCURACY, + * PASSIVE_ACCURACY + * Note: Accuracy has direct effect on power drain. Lower accuracy = lower power drain. + * + * @default MEDIUM_ACCURACY + * @example + * { desiredAccuracy: BackgroundGeolocationAccuracy.LOW } + */ + desiredAccuracy?: number; + + /** + * Stationary radius in meters. + * + * When stopped, the minimum distance the device must move beyond the stationary location for aggressive background-tracking to engage. + * Platform: all + * Provider: DISTANCE_FILTER + * + * @default 50 + */ + stationaryRadius?: number; + + /** + * When enabled, the plugin will emit sounds for life-cycle events of background-geolocation! See debugging sounds table. + * + * Platform: all + * Provider: all + * + * @default false + */ + debug?: boolean; + + /** + * The minimum distance (measured in meters) a device must move horizontally before an update event is generated. + * + * Platform: all + * Provider: DISTANCE_FILTER, RAW + * + * @default 500 + * @see {@link https://apple.co/2oHo2CV|Apple docs} + */ + distanceFilter?: number; + + /** + * Enable this in order to force a stop() when the application terminated. + * E.g. on iOS, double-tap home button, swipe away the app. + * + * Platform: all + * Provider: all + * + * @default true + */ + stopOnTerminate?: boolean; + + /** + * Start background service on device boot. + * + * Platform: Android + * Provider: all + * + * @default false + */ + startOnBoot?: boolean; + + /** + * The minimum time interval between location updates in milliseconds. + * + * Platform: Android + * Provider: all + * + * @default 60000 + * @see {@link https://bit.ly/1x00RUu|Android docs} + */ + interval?: number; + + /** + * Fastest rate in milliseconds at which your app can handle location updates. + * + * Platform: Android + * Provider: ACTIVITY + * + * @default 120000 + * @see {@link https://bit.ly/1x00RUu|Android docs} + */ + fastestInterval?: number; + + /** + * Rate in milliseconds at which activity recognition occurs. + * Larger values will result in fewer activity detections while improving battery life. + * + * Platform: Android + * Provider: ACTIVITY + * + * @default 10000 + */ + activitiesInterval?: number; + + /** + * @deprecated Stop location updates, when the STILL activity is detected. + */ + stopOnStillActivity?: boolean; + + /** + * Enable/disable local notifications when tracking and syncing locations. + * + * Platform: Android + * Provider: all + * + * @default true + */ + notificationsEnabled?: boolean; + + /** + * Allow location sync service to run in foreground state. + * Foreground state also requires a notification to be presented to the user. + * + * Platform: Android + * Provider: all + * + * @default false + */ + startForeground?: boolean; + + /** + * Custom notification title in the drawer. + * + * Platform: Android + * Provider: all + * @default "Background tracking" + */ + notificationTitle?: string; + + /** + * Custom notification text in the drawer. + * + * Platform: Android + * Provider: all + * + * @default "ENABLED" + */ + notificationText?: string; + + /** + * The accent color (hex triplet) to use for notification. + * Eg. #4CAF50. + * + * Platform: Android + * Provider: all + */ + notificationIconColor?: string; + + /** + * The filename of a custom notification icon. + * + * Platform: Android + * Provider: all + */ + notificationIconLarge?: string; + + /** + * The filename of a custom notification icon. + * + * Platform: Android + * Provider: all + */ + notificationIconSmall?: string; + + /** + * Activity type. + * Presumably, this affects iOS GPS algorithm. + * + * Possible values: + * "AutomotiveNavigation", "OtherNavigation", "Fitness", "Other" + * + * Platform: iOS + * Provider: all + * + * @default "OtherNavigation" + * @see {@link https://apple.co/2oHofpH|Apple docs} */ activityType?: string; /** - * IOS ONLY - * Pauses location updates when app is paused + * Pauses location updates when app is paused. * - * Defaults to true + * Platform: iOS + * Provider: all + * + * @default false + * @see {@link https://apple.co/2CbjEW2|Apple docs} */ pauseLocationUpdates?: boolean; + /** + * Switch to less accurate significant changes and region monitory when in background. + * + * Platform: iOS + * Provider: all + * + * @default false + */ + saveBatteryOnBackground?: boolean; + /** * Server url where to send HTTP POST with recorded locations - * @see https://github.com/mauron85/cordova-plugin-background-geolocation#http-locations-posting + * + * Platform: all + * Provider: all */ url?: string; /** * Server url where to send fail to post locations - * @see https://github.com/mauron85/cordova-plugin-background-geolocation#http-locations-posting + * + * Platform: all + * Provider: all */ syncUrl?: string; /** - * Specifies how many previously failed locations will be sent to server at once + * Specifies how many previously failed locations will be sent to server at once. * - * Defaults to 100 + * Platform: all + * Provider: all + * + * @default 100 */ - syncThreshold?: number; + syncThreshold?: string; /** - * Optional HTTP headers sent along in HTTP request + * Optional HTTP headers sent along in HTTP request. + * + * Platform: all + * Provider: all */ httpHeaders?: any; /** - * IOS ONLY - * Switch to less accurate significant changes and region monitory when in background (default) + * Limit maximum number of locations stored into db. * - * Defaults to 100 - */ - saveBatteryOnBackground?: boolean; - - /** - * Limit maximum number of locations stored into db + * Platform: all + * Provider: all * - * Defaults to 10000 + * @default 10000 */ maxLocations?: number; /** - * ANDROID ONLY with BackgroundGeolocation.LocationProvider.ANDROID_ACTIVITY_PROVIDER + * Customization post template. * - * Fastest rate in milliseconds at which your app can handle location updates. - * @see Android docs (https://developers.google.com/android/reference/com/google/android/gms/location/LocationRequest.html#getFastestInterval()) + * Platform: all + * Provider: all */ - fastestInterval?: number; + postTemplate?: any; +} - /** - * ANDROID ONLY with BackgroundGeolocation.LocationProvider.ANDROID_ACTIVITY_PROVIDER - * - * Rate in milliseconds at which activity recognition occurs. Larger values will result in fewer activity detections while improving battery life. - */ - activitiesInterval?: number; +/** + * Set location service provider @see https://github.com/mauron85/cordova-plugin-background-geolocation/wiki/Android-providers + * + * Possible values: + * ANDROID_DISTANCE_FILTER_PROVIDER: 0, + * ANDROID_ACTIVITY_PROVIDER: 1 + * + * @enum {number} + */ +export declare enum BackgroundGeolocationProvider { + ANDROID_DISTANCE_FILTER_PROVIDER = 0, + ANDROID_ACTIVITY_PROVIDER = 1 +} - /** - * ANDROID ONLY with BackgroundGeolocation.LocationProvider.ANDROID_ACTIVITY_PROVIDER - * - * stop() is forced, when the STILL activity is detected (default is true) - */ - stopOnStillActivity?: boolean; +/** + * Desired accuracy in meters. Possible values [0, 10, 100, 1000]. + * The lower the number, the more power devoted to GeoLocation resulting in higher accuracy readings. + * 1000 results in lowest power drain and least accurate readings. + * + * Possible values: + * HIGH: 0 + * MEDIUM: 10 + * LOW: 100 + * PASSIVE: 1000 + * + * enum {number} + */ +export declare enum BackgroundGeolocationAccuracy { + HIGH = 0, + MEDIUM = 10, + LOW = 100, + PASSIVE = 1000 +} + +/** + * Used in the switchMode function + * + * Possible values: + * BACKGROUND: 0 + * FOREGROUND: 1 + * + * @enum {number} + */ +export declare enum BackgroundGeolocationMode { + BACKGROUND = 0, + FOREGROUND = 1 +} + +export declare enum BackgroundGeolocationIOSActivity { + AutomotiveNavigation = 'AutomotiveNavigation', + OtherNavigation = 'OtherNavigation', + Fitness = 'Fitness', + Other = 'Other' } /** @@ -301,74 +538,21 @@ export interface BackgroundGeolocationConfig { */ @Plugin({ pluginName: 'BackgroundGeolocation', - plugin: 'cordova-plugin-mauron85-background-geolocation', - pluginRef: 'backgroundGeolocation', + plugin: 'cordova-plugin-mauron85-background-geolocation@alpha', + pluginRef: 'BackgroundGeolocation', repo: 'https://github.com/mauron85/cordova-plugin-background-geolocation', platforms: ['Android', 'iOS'] }) @Injectable() export class BackgroundGeolocation extends IonicNativePlugin { - /** - * Set location service provider @see https://github.com/mauron85/cordova-plugin-background-geolocation/wiki/Android-providers - * - * Possible values: - * ANDROID_DISTANCE_FILTER_PROVIDER: 0, - * ANDROID_ACTIVITY_PROVIDER: 1 - * - * @enum {number} - */ - LocationProvider: any = { - ANDROID_DISTANCE_FILTER_PROVIDER: 0, - ANDROID_ACTIVITY_PROVIDER: 1 - }; - - /** - * Desired accuracy in meters. Possible values [0, 10, 100, 1000]. - * The lower the number, the more power devoted to GeoLocation resulting in higher accuracy readings. - * 1000 results in lowest power drain and least accurate readings. - * - * Possible values: - * HIGH: 0 - * MEDIUM: 10 - * LOW: 100 - * PASSIVE: 1000 - * - * enum {number} - */ - Accuracy: any = { - HIGH: 0, - MEDIUM: 10, - LOW: 100, - PASSIVE: 1000 - }; - - /** - * Used in the switchMode function - * - * Possible values: - * BACKGROUND: 0 - * FOREGROUND: 1 - * - * @enum {number} - */ - Mode: any = { - BACKGROUND: 0, - FOREGROUND: 1 - }; - /** * Configure the plugin. * * @param options {BackgroundGeolocationConfig} options An object of type Config * @return {Observable} */ - @Cordova({ - callbackOrder: 'reverse', - observable: true - }) - configure( - options: BackgroundGeolocationConfig - ): Observable { + @Cordova() + configure(options: BackgroundGeolocationConfig): Promise { return; } @@ -475,7 +659,7 @@ export class BackgroundGeolocation extends IonicNativePlugin { /** * Method can be used to detect user changes in location services settings. * If user enable or disable location services then success callback will be executed. - * In case or error (SettingNotFoundException) fail callback will be executed. + * In case or (SettingNotFoundException) fail callback will be executed. * @returns {Observable} */ @Cordova({ @@ -573,7 +757,136 @@ export class BackgroundGeolocation extends IonicNativePlugin { * @returns {Promise} */ @Cordova() - getLogEntries(limit: number): Promise { + getLogEntries( + limit: number, + fromId: number, + minLevel: BackgroundGeolocationLogLevel + ): Promise { + return; + } + + /** + * Return all logged events. Useful for plugin debugging. Parameter limit limits number of returned entries. + * @see https://github.com/mauron85/cordova-plugin-background-geolocation/tree/v2.2.1#debugging for more information. + * + * @returns {Promise} + */ + @Cordova() + getConfig(): Promise { + return; + } + + /** + * One time location check to get current location of the device. + * {timeout: Maximum time in milliseconds device will wait for location, + * maximumAge: Maximum age in milliseconds of a possible cached location that is acceptable to return; + * enableHighAccuracy: if true and if the device is able to provide a more accurate position, it will do so} + * + * @param {BackgroundGeolocationCurrentPositionConfig} options + * @returns {Promise} + */ + @Cordova({ + callbackOrder: 'reverse' + }) + getCurrentLocation( + options?: BackgroundGeolocationCurrentPositionConfig + ): Promise { + return; + } + + /** + * Check status of the service + */ + @Cordova() + checkStatus(): Promise { + return; + } + + /** + * Start background task (iOS only) + * + * To perform any long running operation on iOS + * you need to create background task + * IMPORTANT: task has to be ended by endTask + * + * @returns {Promise} taskKey + */ + @Cordova({ + platforms: ['IOS'] + }) + startTask(): Promise { + return; + } + + /** + * End background task indentified by taskKey (iOS only) + */ + @Cordova({ + platforms: ['IOS'] + }) + endTask(taskKey: number): Promise { + return; + } + + /** + * A special task that gets executed when the app is terminated, but + * the plugin was configured to continue running in the background + * (option stopOnTerminate: false). + * + * In this scenario the Activity was killed by the system and all registered + * event listeners will not be triggered until the app is relaunched. + * + * @example + * BackgroundGeolocation.headlessTask(function(event) { + * + * if (event.name === 'location' || event.name === 'stationary') { + * var xhr = new XMLHttpRequest(); + * xhr.open('POST', 'http://192.168.81.14:3000/headless'); + * xhr.setRequestHeader('Content-Type', 'application/json'); + * xhr.send(JSON.stringify(event.params)); + * } + * + * return 'Processing event: ' + event.name; // will be logged + * }); + * @param func + */ + @Cordova() + headlessTask(func: any): Promise { + return; + } + + /** + * Force sync of pending locations. + * Option syncThreshold will be ignored and all pending locations will be immediately posted to syncUrl in single batch. + * + * Platform: Android, iOS + */ + @Cordova() + forceSync(): Promise { + return; + } + + /** + * Register event listener. + * + * Triggered when server responded with "285 Updates Not Required" to post/sync request. + * @param event + * @param callbackFn + */ + @Cordova({ + observable: true + }) + on(event: BackgroundGeolocationEvents): Observable { + return; + } + + /** + * Unregister all event listeners for given event. + * + * If parameter event is not provided then all event listeners will be removed. + */ + @Cordova() + removeAllListeners(event?: BackgroundGeolocationEvents): Promise { return; } }