Guía
Cómo usar Background Geolocation en 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 precisas, monitorear regiones circulares y enviar transiciones 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 o segundo plano.stop- Detener el seguimiento de ubicación activo.openSettings- Abrir los ajustes nativos cuando los usuarios deban corregir los permisos de ubicación.setPlannedRoute- Reproducir un sonido nativo cuando el usuario se salga de una ruta planificada.setupGeofencing- Configura valores por defecto de geofence nativo y webhooks de transición opcionales.addGeofence- Monitorear una región de geofence circular en iOS o Android.removeGeofence/removeAllGeofences- Detener el monitoreo de una o todas las regiones registradas.getMonitoredGeofences- List monitored region identifiers.geofenceTransitionlistener - Recibe eventos de entrada y salida mientras la app está activa.geofenceErrorlistener - Gestionar los errores de monitoreo nativo por separado de 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 Promise rejection 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. Úsalo para emitir un sonido (también en background, 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 en iOS y Android. Añade un HTTP o HTTPS url para permitir que el code nativo envíe payloads POST de transición 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 background:
<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 Uso de @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 el detalle 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.