Erste Schritte

@capgo/background-geolocation kombiniert präzises Background-Location-Tracking mit nativem Geofencing für iOS und Android. Nutze es für Lieferzonen, Stores, Baustellen, Campus-Bereiche, Check-ins, Routen-Alerts oder jeden Workflow, der Enter- oder Exit-Events benötigt – selbst wenn die WebView nicht aktiv ist.

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/background-geolocation` plugin in my project.

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/background-geolocation
bunx cap sync

Importieren

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

Quickstart

Fordere Hintergrund-Standortberechtigungen an, starte Updates mit einer sichtbaren Android-Benachrichtigung und sende Fixes von nativem code per POST an dein API.

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

await BackgroundGeolocation.requestPermissions({
  permissions: ['location', 'backgroundLocation', 'notification'],
});

await BackgroundGeolocation.start(
  {
    backgroundMessage: 'Tracking delivery route',
    backgroundTitle: 'Location active',
    requestPermissions: true,
    stale: false,
    url: 'https://api.example.com/locations',
    headers: { Authorization: 'Bearer fleet-token' },
    distanceFilter: 25,
  },
  (location, error) => {
    if (error) {
      console.error('Location error', error);
      return;
    }
    if (location) {
      console.log('Fix', location.latitude, location.longitude);
    }
  },
);

Jeder Fix wird parallel an JavaScript (solange die WebView aktiv ist) und an url mit "source": "native" im JSON-Body.

Beispiel: Geofence-Webhook

await BackgroundGeolocation.setupGeofencing({
  url: 'https://api.example.com/geofence-hit',
  backgroundLocation: true,
});

Auf Android deklariere ACCESS_BACKGROUND_LOCATION in deinem Manifest, wenn du Hintergrund-Geofence-POSTs benötigst (siehe den Abschnitt zu nativem Geofencing unten).

await BackgroundGeolocation.addGeofence({
  identifier: 'warehouse',
  latitude: 32.7,
  longitude: -117.1,
  radius: 200,
});

Beispiel: Tracking stoppen

await BackgroundGeolocation.stop();

Häufige Stolperfallen

• Android-Benachrichtigung: Hintergrund-Updates benötigen backgroundMessage (und Titel), damit Nutzer sehen, warum der Standort aktiv ist.
• Veraltete Fixes: setzen stale: false wenn Sie nur frische GPS-Fixes benötigen.
• Berechtigungen: Anfrage backgroundLocation separat auf modernen Android-Versionen.

API Übersicht

start

Rufen Sie diese Methode auf, um auf Änderungen am Gerätestandort zu lauschen. Es wird ein Promise zurückgegeben, das anzeigt, dass der Aufruf abgeschlossen wurde. Der Callback wird jedes Mal aufgerufen, wenn ein neuer Standort verfügbar ist oder wenn beim Aufruf dieser Methode ein Fehler auftrat. Verlassen Sie sich diesbezüglich nicht auf die Promise-Rejection.

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

Stoppt die Standort-Updates.

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

await BackgroundGeolocation.stop();

openSettings

Öffnet die Standorteinstellungen des Geräts. Nützlich, um Nutzer dazu zu bewegen, Ortungsdienste zu aktivieren oder Berechtigungen anzupassen.

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

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

setPlannedRoute

Spielt eine Audiodatei ab, wenn der Nutzer von der geplanten Route abweicht. Dies sollte genutzt werden, um einen Sound abzuspielen (auch im Hintergrund, nur bei Native Build).

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

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

Native Geofencing

Geofencing läuft in der Native Layer, sodass iOS und Android Enter- und Exit-Events triggern können, ohne dass die WebView aktiv bleiben muss. Konfiguriere eine HTTP- oder HTTPS-Webhook-URL, wenn dein Backend Transitions empfangen muss, selbst wenn die App-UI im Hintergrund pausiert.

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();

Unter iOS erfordert Geofencing die „Always“-Standortberechtigung. Unter Android 10 und neuer musst du die Background-Location-Permission in dein App-Manifest aufnehmen, wenn du Background Geofencing benötigst:

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

Typreferenz

StartOptions

Optionen zur Konfiguration von Standort-Updates.

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

Stellt einen geografischen Standort mit verschiedenen Attributen dar. Enthält alle Standard-Standortdaten, die von GPS- oder Netzwerk-Providern zurückgegeben werden.

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

Error-Objekt, das an den Location-Start-Callback übergeben werden kann. Erweitert den Standard-Error um optionale Fehlercodes.

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 of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Verwendung von @capgo/background-geolocation für die native Funktion bei der Nutzung von @capgo/background-geolocation, Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für das Implementierungsdetail beim Hinzufügen oder Aktualisieren von Plugins, und Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow bei den Ionic Enterprise Plugin-Alternativen.