Geolocalización en segundo plano plugin Capacitor

Usando @capgo/background-geolocation

Geolocalización en segundo plano precisa y geofencing nativo para apps de Capacitor en iOS y Android. Úsalo para transmitir actualizaciones de ubicación exactas, monitorear regiones circulares y enviar eventos de entrada/salida de geofence a JavaScript o a tu backend.

Instalar

bun add @capgo/background-geolocation
bunx cap sync

Lo que expone este plugin

• start - Recibe actualizaciones de ubicación precisas en primer plano o en segundo plano.
• stop - Detén el seguimiento de ubicación activo.
• openSettings - Abre los ajustes nativos cuando el usuario deba corregir los permisos de ubicación.
• setPlannedRoute - Reproduce un sonido nativo si el usuario se sale de la ruta planificada.
• setupGeofencing - Configura los valores predeterminados de geofencing nativo y el envío opcional de webhooks de transición.
• addGeofence - Monitoriza una región de geofence circular en iOS o Android.
• removeGeofence / removeAllGeofences - Deja de monitorizar una o todas las regiones registradas.
• getMonitoredGeofences - List monitored region identifiers.
• geofenceTransition listener - Recibe eventos de entrada y salida mientras la app está activa.
• geofenceError listener - Gestiona los errores de monitoreo nativo de forma independiente a los eventos de transición.

Ejemplo de uso

start

Llama a este método para empezar a escuchar cambios en la ubicación del dispositivo. Devuelve una Promise para indicar que la llamada finalizó. El callback se ejecutará cada vez que haya una nueva ubicación disponible o si ocurre un error al llamar al método. No dependas de la rejección de la promise para esto.

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

Detiene las actualizaciones de ubicación.

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

await BackgroundGeolocation.stop();

openSettings

Abre la página de ajustes de ubicación del dispositivo. Útil para guiar a los usuarios a activar los servicios de ubicación o ajustar permisos.

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

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

setPlannedRoute

Reproduce un archivo de sonido cuando el usuario se desvía de la ruta planificada. Debe usarse para emitir un sonido (también en segundo plano, solo en nativo).

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

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

Geofencing nativo

Monitorea tiendas, obras, zonas de entrega, campus o áreas de check-in con geofences nativas para iOS y Android. Añade un HTTP o HTTPS url para permitir que el code nativo envíe payloads de transición POST mientras la WebView está suspendida.

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();

En Android, añade ACCESS_BACKGROUND_LOCATION a tu app manifest solo cuando necesites geofencing en segundo plano:

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

Referencia completa

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

Continuar desde Usar @capgo/background-geolocation

Si estás usando Usando @capgo/background-geolocation para planificar el trabajo con plugins nativos, conéctalo con @capgo/background-geolocation para los detalles de implementación en @capgo/background-geolocation, Primeros pasos para los detalles de implementación en Primeros pasos, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para los detalles de implementación en Capacitor Plugins de Capgo, y Añadir o actualizar plugins para los detalles de implementación al añadir o actualizar plugins.