Guide
Comment utiliser Background Geolocation dans Capacitor
Utiliser @capgo/background-geolocation
Géolocalisation en arrière-plan précise et geofencing natif pour les apps Capacitor sur iOS et Android. Utilisez-le pour streamer des mises à jour de position précises, surveiller des régions circulaires et transmettre les transitions d'entrée/sortie de geofence à JavaScript ou à votre backend.
Installer
bun add @capgo/background-geolocation
bunx cap sync
Ce que ce plugin expose
startRecevez des mises à jour de localisation précises en foreground/background.stopArrêtez le suivi de localisation en cours.openSettings- Open native settings when users need to fix location permissions.setPlannedRouteJouez un son natif lorsque l'utilisateur quitte l'itinéraire prévu.setupGeofencingConfigurez les geofences natives par défaut et les webhooks de transition optionnels.addGeofenceSurveillez une zone geofence circulaire sur iOS ou Android.removeGeofence/removeAllGeofencesArrêtez la surveillance d'une ou de toutes les zones enregistrées.getMonitoredGeofencesListez les identifiants des zones surveillées.geofenceTransitionlistener - Recevez les événements d'entrée et de sortie lorsque l'app est active.geofenceErrorlistener - Gérez les erreurs de surveillance natives séparément des événements de transition.
Exemple d'utilisation
start
Pour commencer à écouter les changements de localisation de l’appareil, appelez cette méthode. Une Promise est renvoyée pour indiquer que l’appel est terminé. Le callback est appelé chaque fois qu’une nouvelle localisation est disponible, ou en cas d’erreur lors de l’appel de cette méthode. Ne vous fiez pas au rejet de la Promise pour cela.
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
Arrête les mises à jour de localisation.
import { BackgroundGeolocation } from '@capgo/background-geolocation';
await BackgroundGeolocation.stop();
openSettings
Ouvre la page des paramètres de localisation de l’appareil. Pratique pour guider les utilisateurs vers l’activation des services de localisation ou l’ajustement des autorisations.
import { BackgroundGeolocation } from '@capgo/background-geolocation';
// Direct user to location settings
await BackgroundGeolocation.openSettings();
setPlannedRoute
Joue un fichier audio lorsque l’utilisateur s’écarte de l’itinéraire prévu. À utiliser pour jouer un son (y compris en arrière-plan, uniquement sur natif).
import { BackgroundGeolocation } from '@capgo/background-geolocation';
await BackgroundGeolocation.setPlannedRoute({
soundFile: "notification.mp3",
route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]
});
Géofencing natif
Surveillez vos points de vente, chantiers, zones de livraison, campus ou zones de check-in avec des geofences natifs iOS et Android. Ajoutez un HTTP ou HTTPS url pour permettre aux code natifs d’envoyer les payloads de transition pendant que le WebView est suspendu.
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();
Sur Android, ajoutez ACCESS_BACKGROUND_LOCATION au manifeste de votre app uniquement si vous avez besoin de geofencing en arrière-plan :
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
Référence complète
- GitHub : https://github.com/Cap-go/capacitor-background-geolocation/
- Docs : /docs/plugins/background-geolocation/
Continuer à partir de Utiliser @capgo/background-geolocation
Si vous utilisez Utiliser @capgo/background-geolocation pour planifier le travail sur les plugins natifs, connectez-l’à @capgo/background-geolocation pour les détails d'implémentation dans @capgo/background-geolocation, Prise en main pour les détails d'implémentation dans Getting Started Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans les plugins Capacitor par Capgo, et Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Adding or Updating Plugins.