Saltar al contenido

@capgo/background-geolocation

Seguimiento preciso de la ubicación en segundo plano, eventos nativos de entrada/salida de geofence y webhooks de transición para apps Capacitor.

Entrega en iOS con la app cerrada

Llama a GeofenceRelay.shared.start() desde el app delegate de iOS para que una app terminada pueda enviar un POST al cruzar una región cuando iOS la relanza. Se requiere acceso a la ubicación siempre para ese relanzamiento.

Cola en disco y reintentos

En iOS, las transiciones se encolan en disco y se envían en orden. iOS reintenta ante pérdida de red, 5xx, 408, 429 o 401/403. Esa cola de iOS conserva las 100 transiciones más recientes, ninguna con más de siete días. Android reintenta a través de WorkManager y no usa esta cola ordenada ni esos límites.

clearGeofenceQueue()

Descarta los POST nativos no enviados al cerrar sesión o cambiar de cuenta en el mismo url. La cola también se vacía cuando setupGeofencing se le asigna un urldiferente. En web no hay cola y la llamada se resuelve de inmediato.

Hora del evento

Opcional GeofenceTransitionEvent.time es cuando el teléfono detectó el cruce, en milisegundos desde el epoch. Léelo en tu webhook, no en el reloj del servidor, porque un POST en cola puede llegar más tarde.

Usa @capgo/background-geolocation cuando tu app Capacitor necesita actualizaciones de ubicación precisas en primer plano o en segundo plano, geofences circulares nativos en iOS y Android, y entrega al backend de las transiciones de geofence cuando la WebView está suspendida.

  • start - Recibe actualizaciones de ubicación precisas en primer o segundo plano.
  • stop - Detén limpiamente el seguimiento de ubicación activo.
  • openSettings - Envía a los usuarios a los ajustes de ubicación nativos si faltan permisos.
  • setPlannedRoute - Reproduce un sonido nativo cuando el usuario se desvía de una ruta planificada.
  • setupGeofencing - Configura valores por defecto de geofence nativo y webhooks de transición opcionales.
  • addGeofence - Monitorea una región de geofence circular en iOS o Android por identificador.
  • removeGeofence / removeAllGeofences - Detén el monitoreo de una o todas las geofences registradas.
  • getMonitoredGeofences - Lista los identificadores de región que la capa nativa monitorea actualmente.
  • updateHeaders - Reemplaza las cabeceras HTTP persistidas usadas por la entrega nativa POST.
  • clearGeofenceQueue - Descarta las transiciones de geocerca en cola para un POST nativo que aún no se han enviado.
  • geofenceTransition listener - Recibe eventos de entrada y salida mientras la app está activa, incluyendo opcionalmente time.
  • geofenceError listener - Gestiona errores de monitoreo nativo sin cambiar la estructura del evento de transición.
MétodoDescripción
startEmite actualizaciones precisas de ubicación en foreground o background.
stopDetiene las actualizaciones de ubicación.
openSettingsAbre la configuración de ubicación del dispositivo. Útil para guiar al usuario a activar los servicios de ubicación o ajustar permisos.
setPlannedRouteReproduce un sonido nativo cuando el usuario se desvía de la ruta planificada.
setupGeofencingConfigura los valores predeterminados de geofence y la entrega POST opcional de transiciones nativas.
addGeofenceInicia el monitoreo de un geofence circular en iOS y Android.
removeGeofenceDetiene el monitoreo de un geofence por identificador.
removeAllGeofencesDetiene el monitoreo de todos los geofences registrados por este plugin.
getMonitoredGeofencesDevuelve los identificadores monitoreados actualmente por la capa nativa.
updateHeadersReemplaza las cabeceras HTTP persistidas para la entrega nativa POST. En iOS, esto también vacía la cola de geocercas. En Android, guarda las cabeceras sin iniciar trabajos en cola de WorkManager.
clearGeofenceQueueDescarta las transiciones de geocerca en cola para un POST nativo que aún no se han enviado. Se resuelve de inmediato en web.
addListener('geofenceTransition', ...)Recibe eventos de entrada y salida de geocerca mientras la app está activa. Los eventos pueden incluir time.
addListener('geofenceError', ...)Recibe errores del monitoreo nativo de geofences mientras la app está activa.
getPluginVersionObtén la versión del plugin nativo Capacitor.

Esta referencia se sincroniza desde src/definitions.ts en capacitor-background-geolocation.

Si estás usando @capgo/background-geolocation para planificar el trabajo con plugins nativos, conéctalo con Usando @capgo/background-geolocation para la capacidad nativa en «Usando @capgo/background-geolocation», Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, y Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a plugins de Ionic Enterprise.