Salta al contenuto principale
@capgo/background-geolocation Posizione Open source

Geolocalizzazione in background Plugin Capacitor

Tracciamento preciso della posizione in background con geofencing nativo iOS e Android e webhook di transizione

Installa

bun add @capgo/background-geolocation bunx cap sync
npm, pnpm o yarn
  • npm install @capgo/background-geolocation
  • pnpm add @capgo/background-geolocation
  • yarn add @capgo/background-geolocation

Guida

Come usare Background Geolocation in Capacitor

Usare @capgo/background-geolocation

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

Installa

bun add @capgo/background-geolocation
bunx cap sync

Cosa espone questo plugin

  • start - Trasmetti aggiornamenti della posizione precisi in foreground o background.
  • stop - Interrompi il tracciamento attivo della posizione.
  • openSettings - Apri le impostazioni native quando gli utenti devono correggere i permessi di posizione.
  • setPlannedRoute - Riproduci un suono nativo quando l'utente esce da un percorso pianificato.
  • setupGeofencing - Configura default dei geofence nativi e invio opzionale dei webhook di transizione.
  • addGeofence - Monitora una regione geofence circolare su iOS o Android.
  • removeGeofence / removeAllGeofences - Interrompi il monitoraggio di una o tutte le regioni registrate.
  • getMonitoredGeofences - Elenca gli identificativi delle regioni monitorate.
  • geofenceTransition listener - Ricevi eventi di ingresso e uscita mentre l'app è attiva.
  • geofenceError listener - Gestisci gli errori di monitoraggio nativi separatamente dagli eventi di transizione.

Esempio d'uso

start

Per iniziare a monitorare le variazioni della posizione del dispositivo, chiama questo metodo. Viene restituita una Promise per indicare che la chiamata è terminata. Il callback verrà invocato ogni volta che è disponibile una nuova posizione o se si verifica un errore durante la chiamata. Non fare affidamento sul rejection della Promise per questo.

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 della posizione del dispositivo. Utile per guidare gli utenti nell'abilitazione dei servizi di localizzazione o nell'aggiustamento 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 per 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 nativi iOS e Android. Aggiungi un HTTP o HTTPS url per consentire a code nativo di inviare payload di transizione tramite POST mentre la WebView è sospesa.

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 di geofencing in background:

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

Riferimento completo

Continua da Using @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.

FAQ

FAQ del plugin Background Geolocation

Come installo il plugin Background Geolocation in un'app Capacitor?

Esegui &quot;bun add @capgo/background-geolocation&quot; (o &quot;npm install @capgo/background-geolocation&quot;), poi esegui &quot;bunx cap sync&quot; affinché i progetti iOS e Android recuperino il codice nativo code. Importalo da &quot;@capgo/background-geolocation&quot; nel tuo code dell'app.

@capgo/background-geolocation funziona con React, Vue e Angular?

Sì. Background Geolocation è un pacchetto Capacitor, quindi funziona con qualsiasi framework web che gira all'interno di Capacitor, incluso Ionic, React, Vue, Angular, Svelte e JavaScript puro.

Quale versione di Capacitor supporta @capgo/background-geolocation?

I plugin Capgo seguono la major version di Capacitor: usa la major version del plugin che corrisponde alla tua major version di Capacitor (ad esempio plugin v8 con Capacitor 8). La tabella di compatibilità nel README di GitHub elenca le versioni mantenute.

@capgo/background-geolocation è gratuito e open source?

Sì. Il code sorgente è pubblico su GitHub all'indirizzo https://github.com/Cap-go/capacitor-background-geolocation/ e il pacchetto è gratuito da installare da npm. Bug report e pull request sono benvenuti.

Posso aggiornare code che usa Background Geolocation senza una revisione dell'App Store?

Installare o aggiornare il plugin modifica il code nativo, quindi serve una nuova build per lo store. Dopo, le modifiche a JavaScript, HTML e CSS che chiamano il plugin possono essere rilasciate subito con le live updates di Capgo.

Rilascia le modifiche a Background Geolocation senza attendere la revisione dell'app

Una volta incluso il plugin nel tuo store build, Capgo invia le modifiche a JavaScript, HTML e CSS tramite live updates in pochi minuti.

Inizia con Capgo