Getting Started

@capgo/background-geolocation Combineert präzise Hintergrundortverfolgung mit nativer Geofencing für iOS und Android. Verwenden Sie es für Lieferzonen, Geschäfte, Arbeitsplätze, Campus, Check-ins, Routenwarnungen und jede Workflow, der Eingänge oder Ausgänge benötigt, selbst wenn der WebView nicht läuft.

Installieren

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie die Capgo Fähigkeiten Ihrem KI-Tool hinzu, indem Sie die folgende Anweisung verwenden:

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

Verwenden Sie dann die folgende Anweisung:

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

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und die unten angegebenen Plattform-spezifischen Anweisungen befolgen:

bun add @capgo/background-geolocation
bunx cap sync

Importieren

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

API Übersicht

start

Um auf Änderungen der Geräteposition zu lauschen, rufen Sie diese Methode auf. Ein Versprechen wird zurückgegeben, um anzugeben, dass die Anfrage abgeschlossen ist. Der Callback wird aufgerufen, sobald eine neue Position verfügbar ist, oder wenn bei der Aufrufung dieser Methode ein Fehler aufgetreten ist. Verlassen Sie sich nicht auf die Ablehnung des Versprechens für diese.

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

Stoppert die Standortaktualisierungen.

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

await BackgroundGeolocation.stop();

openSettings

Öffnet die Einstellungen für die Geräteposition. Nützlich für die Anleitung der Benutzer, die Standortdienste zu aktivieren oder die Berechtigungen anzupassen.

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

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

setPlannedRoute

Plays a sound file when the user deviates from the planned route. This should be used to play a sound (in the background too, only for native).

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 im nativen Layer, sodass iOS und Android Eingabe- und Ausgangsereignisse auslösen können, ohne auf das WebView angewiesen zu sein, das wach bleiben muss. Konfigurieren Sie eine HTTP- oder HTTPS-Webhook-URL, wenn Ihr Backend Übergänge auch dann erhalten soll, wenn die App-UI ausgesetzt ist.

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

Bei iOS erfordert Geofencing ständige Standortberechtigung. Bei Android 10 und neuer fügen Sie der App-Manifest die Hintergrund-Ortungs-Erlaubnis hinzu, wenn Sie Hintergrund-Geofencing benötigen:

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

Typenreferenz

StartOptions

Die Optionen für die Konfiguration von Standortaktualisierungen.

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

Ein geografischer Standort mit verschiedenen Attributen. Enthält alle standardmäßigen Standorteigenschaften, die von GPS-/Netzwerk-Anbietern 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

Fehlerobjekt, das an den Standortstartcallback übergeben werden kann. Erweitert den Standardfehler um optionalen 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;
}

Hauptquelle

Diese Seite wurde von dem Plugin generiert. src/definitions.tsRe-run die Synchronisierung, wenn die öffentliche API upstream geändert wird.

Fortsetzen von Getting Started

Wenn Sie das Plugin verwenden Getting Started um native Plugin-Arbeit zu planen, verbinden Sie es mit Mit @capgo/Hintergrund-Geolokalisierung zur Verwendung der native Fähigkeit in Mit @capgo/Hintergrund-Geolokalisierung, Capgo Plugin-Verzeichnis zur Verwendung des Produktflusses in Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo zur Verwendung der Implementierungsdetails in Capacitor Plugins von Capgo, Hinzufügen oder Aktualisieren von Plugins zur Verwendung der Implementierungsdetails in Hinzufügen oder Aktualisieren von Plugins, und Ionische Unternehmens-Plugin-Alternativen zur Verwendung des Produktflusses in Ionische Unternehmens-Plugin-Alternativen.