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.geofenceTransitionlistener - Ricevi eventi di ingresso e uscita mentre l'app è attiva.geofenceErrorlistener - 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
- GitHub: https://github.com/Cap-go/capacitor-background-geolocation/
- Docs: /docs/plugins/background-geolocation/
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.