Démarrage

@capgo/background-geolocation Combinez la traçabilité de localisation de fond précise avec la géofencing native pour iOS et Android. Utilisez-le pour les zones de livraison, les magasins, les sites de travail, les campus, les check-ins, les alertes de trajet et tout workflow qui nécessite des événements d'entrée ou de sortie même lorsque la vue Web n'est pas en cours d'exécution.

Installation

bun add @capgo/background-geolocation
bunx cap sync

Importer

import { BackgroundGeolocation } from '@capgo/background-geolocation';

API Vue d'ensemble

start

Pour commencer à détecter les changements de la position du dispositif, appelez cette méthode. Une promesse est renvoyée pour indiquer que la méthode a terminé. Le callback sera appelé chaque fois qu'une nouvelle position sera disponible, ou si une erreur s'est produite lors de l'appel de cette méthode. N'attendez pas la rejet de la promesse pour cela.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.start(
  {
    backgroundMessage: "App is using your location in the background",
    backgroundTitle: "Location Service",
    requestPermissions: true,
    stale: false,
    distanceFilter: 10
  },
  (location, error) => {
    if (error) {
      console.error('Location error:', error);
      return;
    }
    if (location) {
      console.log('New location:', location.latitude, location.longitude);
    }
  }
);

stop

Arrête les mises à jour de localisation.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.stop();

openSettings

Ouvre la page de paramètres de localisation du dispositif. Utile pour diriger les utilisateurs pour activer les services de localisation ou ajuster les permissions.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

// Direct user to location settings
await BackgroundGeolocation.openSettings();

setPlannedRoute

Joue un fichier audio lorsque l'utilisateur dévie de l'itinéraire planifié. Cela devrait être utilisé pour jouer un son (en arrière-plan également, uniquement pour natif).

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setPlannedRoute({
  soundFile: "notification.mp3",
  route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]
});

Geofencing natif

Le geofencing fonctionne dans la couche native, donc iOS et Android peuvent déclencher les événements d'entrée et de sortie sans se fier à la WebView pour rester éveillé. Configurez une URL de webhook HTTP ou HTTPS lorsque votre backend doit recevoir les transitions même lorsque l'interface utilisateur de l'application est suspendue.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setupGeofencing({
  url: 'https://api.example.com/geofences',
  notifyOnEntry: true,
  notifyOnExit: true,
  payload: { userId: '123' },
});

await BackgroundGeolocation.addGeofence({
  identifier: 'store-42',
  latitude: 37.33182,
  longitude: -122.03118,
  radius: 150,
  payload: { storeId: '42' },
});

const handle = await BackgroundGeolocation.addListener(
  'geofenceTransition',
  (event) => {
    console.log(event.identifier, event.transition);
  },
);

const errorHandle = await BackgroundGeolocation.addListener(
  'geofenceError',
  (event) => {
    console.error(event.identifier, event.message);
  },
);

const { regions } = await BackgroundGeolocation.getMonitoredGeofences();
console.log(regions);

await BackgroundGeolocation.removeGeofence({ identifier: 'store-42' });
await handle.remove();
await errorHandle.remove();

Sur iOS, la géolocalisation nécessite une autorisation de localisation toujours active. Sur Android 10 et versions ultérieures, ajoutez la permission de localisation de fond à votre manifeste d'application lorsque vous avez besoin de la géolocalisation de fond :

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Référence de type

StartOptions

Les options pour la configuration des mises à jour de localisation.

export interface StartOptions {
  /**
   * If the "backgroundMessage" option is defined, the plugin will
   * provide location updates whether the app is in the background or the
   * foreground. If it is not defined, location updates are only
   * guaranteed in the foreground. This is true on both platforms.
   *
   * On Android, a notification must be shown to continue receiving
   * location updates in the background. This option specifies the text of
   * that notification.
   *
   * @since 7.0.9
   * @example "Getting your location to provide better service"
   */
  backgroundMessage?: string;
  /**
   * The title of the notification mentioned above.
   *
   * @since 7.0.9
   * @default "Using your location"
   * @example "Location Service"
   */
  backgroundTitle?: string;
  /**
   * Whether permissions should be requested from the user automatically,
   * if they are not already granted.
   *
   * @since 7.0.9
   * @default true
   * @example
   * // Auto-request permissions
   * requestPermissions: true
   *
   * // Don't auto-request, handle manually
   * requestPermissions: false
   */
  requestPermissions?: boolean;
  /**
   * If "true", stale locations may be delivered while the device
   * obtains a GPS fix. You are responsible for checking the "time"
   * property. If "false", locations are guaranteed to be up to date.
   *
   * @since 7.0.9
   * @default false
   * @example
   * // Allow stale locations for faster initial response
   * stale: true
   *
   * // Only fresh locations
   * stale: false
   */
  stale?: boolean;
  /**
   * The distance in meters that the device must move before a new location update is triggered.
   * This is used to filter out small movements and reduce the number of updates.
   *
   * @since 7.0.9
   * @default 0
   * @example
   * // Update every 10 meters
   * distanceFilter: 10
   *
   * // Update on any movement
   * distanceFilter: 0
   */
  distanceFilter?: number;
}

Location

Représente une localisation géographique avec diverses attributs. Contient toutes les propriétés de localisation standard retournées par les fournisseurs GPS/réseau.

export interface Location {
  /**
   * Latitude in degrees.
   * Range: -90.0 to +90.0
   *
   * @since 7.0.0
   * @example 40.7128
   */
  latitude: number;
  /**
   * Longitude in degrees.
   * Range: -180.0 to +180.0
   *
   * @since 7.0.0
   * @example -74.0060
   */
  longitude: number;
  /**
   * Radius of horizontal uncertainty in metres, with 68% confidence.
   * Lower values indicate more accurate location.
   *
   * @since 7.0.0
   * @example 5.0
   */
  accuracy: number;
  /**
   * Metres above sea level (or null if not available).
   *
   * @since 7.0.0
   * @example 10.5
   */
  altitude: number | null;
  /**
   * Vertical uncertainty in metres, with 68% confidence (or null if not available).
   *
   * @since 7.0.0
   * @example 3.0
   */
  altitudeAccuracy: number | null;
  /**
   * `true` if the location was simulated by software, rather than GPS.
   * Useful for detecting mock locations in development or testing.
   *
   * @since 7.0.0
   * @example false
   */
  simulated: boolean;
  /**
   * Deviation from true north in degrees (or null if not available).
   * Range: 0.0 to 360.0
   *
   * @since 7.0.0
   * @example 45.5
   */
  bearing: number | null;
  /**
   * Speed in metres per second (or null if not available).
   *
   * @since 7.0.0
   * @example 2.5
   */
  speed: number | null;
  /**
   * Time the location was produced, in milliseconds since the unix epoch.
   * Use this to check if a location is stale when using stale: true.
   *
   * @since 7.0.0
   * @example 1640995200000
   */
  time: number | null;
}

CallbackError

Objet d'erreur pouvant être passé au callback de démarrage de la localisation. Étend l'erreur standard avec des codes d'erreur optionnels.

export interface CallbackError extends Error {
  /**
   * Optional error code for more specific error handling.
   *
   * @since 7.0.0
   * @example "PERMISSION_DENIED"
   */
  code?: string;
}

SetPlannedRouteOptions

export interface SetPlannedRouteOptions {
  /**
   * The name of the sound file to play.
   * Must be a valid sound relative path in the app's public folder to work for both web and native platforms.
   * There's no need to include the public folder in the path.
   * @since 7.0.10
   * @example "notification.mp3"
   * */
  soundFile: string;
  /**
   * The planned route as an array of longitude and latitude pairs.
   * Each pair represents a point on the route.
   * This is used to define a route that the user can follow.
   * The route is used to play a sound when the user deviates from it.
   * @since 7.0.11
   * @example [[-74.0060, 40.7128], [-118.2437, 34.0522]]
   */
  route: [number, number][];

  /**
   * The distance in meters that the user must deviate from the planned route to trigger the sound.
   * This is used to determine how far off the route the user can be before the sound is played.
   * If not specified, a default value of 50 meters is used.
   * @since 7.0.11
   * @default 50
   * @example 50
   */
  distance: number;
}

Source de Vérité

Cette page est générée à partir du plugin’s src/definitions.tsRe-run la synchronisation lorsque les public API changent en amont.