Geolocalizzazione in background Plugin Capacitor

Usare @capgo/background-geolocation

Geolocalizzazione in background precisa e geofencing nativo per app Capacitor su iOS e Android. Usalo per trasmettere aggiornamenti di posizione precisi, monitorare aree circolari e inviare transizioni di ingresso/uscita dai geofence a JavaScript o al tuo backend.

Installa

bun add @capgo/background-geolocation
bunx cap sync

Cosa espone questo plugin

• start - Stream di aggiornamenti della posizione precisi in foreground o background.
• stop - Interrompere il tracciamento della posizione attivo.
• openSettings - Aprire le impostazioni native quando l'utente deve correggere i permessi della posizione.
• setPlannedRoute - Riprodurre un suono nativo quando l'utente esce dal percorso pianificato.
• setupGeofencing - Configura i default delle geofence native e l'invio opzionale dei webhook di transizione.
• addGeofence - Monitorare una regione geofence circolare su iOS o Android.
• removeGeofence / removeAllGeofences - Smettere di monitorare una o tutte le regioni registrate.
• getMonitoredGeofences - Elenca gli identificativi delle regioni monitorate.
• geofenceTransition listener - Ricevi eventi di enter ed exit mentre l'app è attiva.
• geofenceError listener - Gestisci gli errori di monitoraggio nativi separatamente dagli eventi di transizione.

Esempio d'uso

start

Chiama questo metodo per iniziare a monitorare i cambiamenti di posizione del dispositivo. Restituisce una Promise per indicare il completamento della chiamata. Il callback verrà eseguito ogni volta che una nuova posizione è disponibile o in caso di errore. Non fare affidamento sul rifiuto della promise per gestire questi eventi.

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

Interrompe gli aggiornamenti della posizione.

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

await BackgroundGeolocation.stop();

openSettings

Apre la pagina delle impostazioni sulla posizione del dispositivo. Utile per guidare gli utenti nell'attivazione dei servizi di localizzazione o nella gestione dei permessi.

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

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

setPlannedRoute

Riproduce un file audio quando l'utente devia dal percorso pianificato. Da utilizzare per riprodurre un suono (anche in background, solo su codice nativo).

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

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

Geofencing nativo

Monitora negozi, cantieri, zone di consegna, campus o aree di check-in con geofence native su iOS e Android. Aggiungi un HTTP o HTTPS url per consentire a code di inviare payload POST nativi durante la sospensione della WebView.

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: 'warehouse',
  latitude: 40.7128,
  longitude: -74.006,
  radius: 200,
});

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

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

await BackgroundGeolocation.removeGeofence({ identifier: 'warehouse' });
await listener.remove();
await errorListener.remove();

Su Android, aggiungi ACCESS_BACKGROUND_LOCATION al manifest della tua app solo se hai bisogno del geofencing in background:

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

Riferimento completo

• GitHub: https://github.com/Cap-go/capacitor-background-geolocation/
• Docs: /docs/plugins/background-geolocation/

Continua con l'uso di @capgo/background-geolocation

Se stai usando Usare @capgo/background-geolocation per pianificare il lavoro sui plugin nativi, collegalo a @capgo/background-geolocation per i dettagli di implementazione in @capgo/background-geolocation, Per iniziare per i dettagli di implementazione nella guida introduttiva, Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Plugin Capacitor di Capgo, e Aggiunta o aggiornamento dei plugin per i dettagli di implementazione in Aggiunta o aggiornamento dei plugin.