Aller au contenu principal
@capgo/background-geolocation Localisation Open source

Géolocalisation en arrière-plan Plugin Capacitor

Suivi de localisation précis en arrière-plan avec geofencing natif sur iOS et Android, plus webhooks de transition

Installer

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

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

  • start Recevez des mises à jour de localisation précises en foreground/background.
  • stop Arrêtez le suivi de localisation en cours.
  • openSettings - Open native settings when users need to fix location permissions.
  • setPlannedRoute Jouez un son natif lorsque l'utilisateur quitte l'itinéraire prévu.
  • setupGeofencing Configurez les geofences natives par défaut et les webhooks de transition optionnels.
  • addGeofence Surveillez une zone geofence circulaire sur iOS ou Android.
  • removeGeofence / removeAllGeofences Arrêtez la surveillance d'une ou de toutes les zones enregistrées.
  • getMonitoredGeofences Listez les identifiants des zones surveillées.
  • geofenceTransition listener - Recevez les événements d'entrée et de sortie lorsque l'app est active.
  • geofenceError listener - 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

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.

FAQ

FAQ du plugin Background Geolocation

Comment installer le plugin Background Geolocation dans une application Capacitor ?

Exécutez « bun add @capgo/background-geolocation » (ou « npm install @capgo/background-geolocation »), puis « bunx cap sync » pour que les projets iOS et Android récupèrent le code natif. Importez-le depuis « @capgo/background-geolocation » dans le code de votre application.

@capgo/background-geolocation fonctionne-t-il avec React, Vue et Angular ?

Oui. Background Geolocation est un package Capacitor, il fonctionne donc avec n’importe quel framework web exécuté dans Capacitor, y compris Ionic, React, Vue, Angular, Svelte et le JavaScript pur.

Quelle version de Capacitor @capgo/background-geolocation prend-il en charge ?

Les plugins Capgo suivent la version majeure de Capacitor : utilisez la version majeure du plugin qui correspond à la version majeure de votre Capacitor (par exemple le plugin v8 avec Capacitor 8). Le tableau de compatibilité du README de GitHub recense les versions maintenues.

@capgo/background-geolocation est-il gratuit et open source ?

Oui. Le code source est public sur GitHub à l’adresse https://github.com/Cap-go/capacitor-background-geolocation/ et le package est gratuit à installer depuis npm. Les signalements de bugs et les pull requests sont les bienvenus.

Puis-je mettre à jour code qui utilise Background Geolocation sans passer par une revue de l’App Store ?

L'installation ou la mise à jour du plugin modifie le code natif, ce qui impose un nouveau build pour les stores. Ensuite, les changements JavaScript, HTML et CSS qui appellent le plugin peuvent être livrés instantanément via les live updates de Capgo.

Déployez vos changements de Background Geolocation sans attendre la validation de l'app

Une fois le plugin intégré à votre build de store, Capgo live updates déploie vos changements JavaScript, HTML et CSS aux utilisateurs en quelques minutes.

Commencez avec Capgo