@ionic-native/background-geolocation/ngx/index.d.ts

Ionic Native - Native plugins for ionic apps

import { IonicNativePlugin } from '@ionic-native/core';
import { Observable } from 'rxjs';
export declare enum BackgroundGeolocationLocationCode {
    PERMISSION_DENIED = 1,
    LOCATION_UNAVAILABLE = 2,
    TIMEOUT = 3
}
export declare enum BackgroundGeolocationNativeProvider {
    gps = "gps",
    network = "network",
    passive = "passive",
    fused = "fused"
}
export declare enum BackgroundGeolocationLocationProvider {
    DISTANCE_FILTER_PROVIDER = 0,
    ACTIVITY_PROVIDER = 1,
    RAW_PROVIDER = 2
}
export declare enum BackgroundGeolocationEvents {
    http_authorization = "http_authorization",
    abort_requested = "abort_requested",
    background = "background",
    foreground = "foreground",
    authorization = "authorization",
    error = "error",
    stop = "stop",
    start = "start",
    activity = "activity",
    stationary = "stationary",
    location = "location"
}
export declare enum BackgroundGeolocationAuthorizationStatus {
    NOT_AUTHORIZED = 0,
    AUTHORIZED = 1,
    AUTHORIZED_FOREGROUND = 2
}
export declare 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) */
    id: number;
    /**
     * Native provider reponsible for location.
     *
     * Possible values:
     * "gps", "network", "passive" or "fused"
     */
    provider: BackgroundGeolocationNativeProvider;
    /** Configured location provider. */
    locationProvider: BackgroundGeolocationLocationProvider;
    /** UTC time of this fix, in milliseconds since January 1, 1970. */
    time: number;
    /** Latitude, in degrees. */
    latitude: number;
    /** Longitude, in degrees. */
    longitude: number;
    /** Estimated accuracy of this location, in meters. */
    accuracy: number;
    /**
     * 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: number;
    /** Bearing, in degrees. */
    bearing: number;
    /**
     * 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.
     */
    isFromMockProvider?: boolean;
    /**
     * True if device has mock locations enabled. (ANDROID ONLY)
     *
     * Note: this property is not enabled by default!
     * You can enable it "postTemplate" configure option.
     */
    mockLocationsEnabled?: boolean;
}
export interface BackgroundGeolocationConfig {
    /**
     * Set location provider
     *
     * Platform: all
     * Available providers:
     *  DISTANCE_FILTER_PROVIDER,
     *  ACTIVITY_PROVIDER
     *  RAW_PROVIDER
     *
     * @default DISTANCE_FILTER_PROVIDER
     * @example
     * { locationProvider: LocationProvider.RAW_PROVIDER }
     */
    locationProvider?: number;
    /**
     * 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. <code>#4CAF50</code>.
     *
     * 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;
    /**
     * Pauses location updates when app is paused.
     *
     * 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
     *
     * Platform: all
     * Provider: all
     */
    url?: string;
    /**
     * Server url where to send fail to post locations
     *
     * Platform: all
     * Provider: all
     */
    syncUrl?: string;
    /**
     * Specifies how many previously failed locations will be sent to server at once.
     *
     * Platform: all
     * Provider: all
     *
     * @default 100
     */
    syncThreshold?: string;
    /**
     * Optional HTTP headers sent along in HTTP request.
     *
     * Platform: all
     * Provider: all
     */
    httpHeaders?: any;
    /**
     * Limit maximum number of locations stored into db.
     *
     * Platform: all
     * Provider: all
     *
     * @default 10000
     */
    maxLocations?: number;
    /**
     * Customization post template.
     *
     * Platform: all
     * Provider: all
     */
    postTemplate?: any;
}
/**
 * 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
}
/**
 * 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"
}
/**
 * @name Background Geolocation
 * @description
 * This plugin provides foreground and background geolocation with battery-saving "circular region monitoring" and "stop detection". For
 * more detail, please see https://github.com/mauron85/cordova-plugin-background-geolocation
 *
 * @usage
 *
 * BackgroundGeolocation must be called within app.ts and or before Geolocation. Otherwise the platform will not ask you for background tracking permission.
 *
 * ```typescript
 * import { BackgroundGeolocation, BackgroundGeolocationConfig, BackgroundGeolocationResponse } from '@ionic-native/background-geolocation';
 *
 * constructor(private backgroundGeolocation: BackgroundGeolocation) { }
 *
 * ...
 *
 * const config: BackgroundGeolocationConfig = {
 *             desiredAccuracy: 10,
 *             stationaryRadius: 20,
 *             distanceFilter: 30,
 *             debug: true, //  enable this hear sounds for background-geolocation life-cycle.
 *             stopOnTerminate: false, // enable this to clear background location settings when the app terminates
 *     };
 *
 * this.backgroundGeolocation.configure(config)
 *   .then(() => {
 *
 *     this.backgroundGeolocation.on('location').subscribe((location: BackgroundGeolocationResponse) => {
 *       console.log(location);
 *
 *       // IMPORTANT:  You must execute the finish method here to inform the native plugin that you're finished,
 *       // and the background-task may be completed.  You must do this regardless if your operations are successful or not.
 *       // IF YOU DON'T, ios will CRASH YOUR APP for spending too much time in the background.
 *       this.backgroundGeolocation.finish(); // FOR IOS ONLY
 *     });
 *
 *   });
 *
 * // start recording location
 * this.backgroundGeolocation.start();
 *
 * // If you wish to turn OFF background-tracking, call the #stop method.
 * this.backgroundGeolocation.stop();
 *
 * ```
 * @interfaces
 * BackgroundGeolocationResponse
 * BackgroundGeolocationConfig
 */
export declare class BackgroundGeolocation extends IonicNativePlugin {
    /**
     * Configure the plugin.
     *
     * @param options {BackgroundGeolocationConfig} options An object of type Config
     * @return {Promise<any>}
     */
    configure(options: BackgroundGeolocationConfig): Promise<any>;
    /**
     * Turn ON the background-geolocation system.
     * The user will be tracked whenever they suspend the app.
     * @returns {Promise<any>}
     */
    start(): Promise<any>;
    /**
     * Turn OFF background-tracking
     * @returns {Promise<any>}
     */
    stop(): Promise<any>;
    /**
     * Inform the native plugin that you're finished, the background-task may be completed
     * @returns {Promise<any>}
     */
    finish(): Promise<any>;
    /**
     * Force the plugin to enter "moving" or "stationary" state
     * @param isMoving {boolean}
     * @returns {Promise<any>}
     */
    changePace(isMoving: boolean): Promise<any>;
    /**
     * Setup configuration
     * @param options {BackgroundGeolocationConfig}
     * @returns {Promise<any>}
     */
    setConfig(options: BackgroundGeolocationConfig): Promise<any>;
    /**
     * Returns current stationaryLocation if available. null if not
     * @returns {Promise<Location>}
     */
    getStationaryLocation(): Promise<BackgroundGeolocationResponse>;
    /**
     * Add a stationary-region listener. Whenever the devices enters "stationary-mode",
     * your #success callback will be executed with #location param containing #radius of region
     * @returns {Promise<any>}
     */
    onStationary(): Promise<any>;
    /**
     * Check if location is enabled on the device
     * @returns {Promise<number>} Returns a promise with int argument that takes values 0, 1 (true).
     */
    isLocationEnabled(): Promise<number>;
    /**
     * Display app settings to change permissions
     */
    showAppSettings(): void;
    /**
     * Display device location settings
     */
    showLocationSettings(): void;
    /**
     * 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  (SettingNotFoundException) fail callback will be executed.
     * @returns {Observable<number>}
     */
    watchLocationMode(): Observable<number>;
    /**
     * Stop watching for location mode changes.
     * @returns {Promise<any>}
     */
    stopWatchingLocationMode(): Promise<any>;
    /**
     * Method will return all stored locations.
     * Locations are stored when:
     *  - config.stopOnTerminate is false and main activity was killed
     *    by the system
     *  or
     *  - option.debug is true
     * @returns {Promise<any>}
     */
    getLocations(): Promise<any>;
    /**
     * Method will return locations, which has not been yet posted to server. NOTE: Locations does contain locationId.
     * @returns {Promise<any>}
     */
    getValidLocations(): Promise<any>;
    /**
     * Delete stored location by given locationId.
     * @param locationId {number}
     * @returns {Promise<any>}
     */
    deleteLocation(locationId: number): Promise<any>;
    /**
     * Delete all stored locations.
     * @returns {Promise<any>}
     */
    deleteAllLocations(): Promise<any>;
    /**
     * Normally plugin will handle switching between BACKGROUND and FOREGROUND mode itself.
     * Calling switchMode you can override plugin behavior and force plugin to switch into other mode.
     *
     * In FOREGROUND mode plugin uses iOS local manager to receive locations and behavior is affected by option.desiredAccuracy and option.distanceFilter.
     * In BACKGROUND mode plugin uses significant changes and region monitoring to receive locations and uses option.stationaryRadius only.
     *
     * BackgroundGeolocation.Mode.FOREGROUND
     * BackgroundGeolocation.Mode.BACKGROUND
     *
     * @param modeId {number}
     * @returns {Promise<any>}
     */
    switchMode(modeId: number): Promise<any>;
    /**
     * 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.
     *
     * @param limit {number} Limits the number of entries
     * @returns {Promise<any>}
     */
    getLogEntries(limit: number, fromId: number, minLevel: BackgroundGeolocationLogLevel): Promise<BackgroundGeolocationLogEntry[]>;
    /**
     * 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<any>}
     */
    getConfig(): Promise<any>;
    /**
     * 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<any>}
     */
    getCurrentLocation(options?: BackgroundGeolocationCurrentPositionConfig): Promise<BackgroundGeolocationResponse>;
    /**
     * Check status of the service
     */
    checkStatus(): Promise<ServiceStatus>;
    /**
     * 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<number>} taskKey
     */
    startTask(): Promise<number>;
    /**
     *  End background task indentified by taskKey (iOS only)
     */
    endTask(taskKey: number): Promise<any>;
    /**
     * A special task that gets executed when the app is terminated, but
     * the plugin was configured to continue running in the background
     * (option <code>stopOnTerminate: false</code>).
     *
     * 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
     */
    headlessTask(func: any): Promise<any>;
    /**
     * Force sync of pending locations.
     * Option <code>syncThreshold</code> will be ignored and all pending locations will be immediately posted to <code>syncUrl</code> in single batch.
     *
     * Platform: Android, iOS
     */
    forceSync(): Promise<any>;
    /**
     * Register event listener.
     *
     * Triggered when server responded with "<code>285 Updates Not Required</code>" to post/sync request.
     * @param event
     * @param callbackFn
     */
    on(event: BackgroundGeolocationEvents): Observable<BackgroundGeolocationResponse>;
    /**
     * Unregister all event listeners for given event.
     *
     * If parameter <code>event</code> is not provided then all event listeners will be removed.
     */
    removeAllListeners(event?: BackgroundGeolocationEvents): Promise<any>;
}