Primeros pasos

@capgo/background-geolocation combina el seguimiento preciso de ubicación en segundo plano con geofencing nativo para iOS y Android. Úsalo para zonas de entrega, tiendas, sitios de trabajo, campus, check-ins, alertas de ruta y cualquier flujo que requiera eventos de entrada o salida incluso si la WebView no se está ejecutando.

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego usa el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/background-geolocation` plugin in my project.

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

bun add @capgo/background-geolocation
bunx cap sync

Importar

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

Inicio rápido

Solicita permisos de ubicación en segundo plano, inicia actualizaciones con una notificación visible en Android y envía correcciones a tu API desde code nativo.

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

await BackgroundGeolocation.requestPermissions({
  permissions: ['location', 'backgroundLocation', 'notification'],
});

await BackgroundGeolocation.start(
  {
    backgroundMessage: 'Tracking delivery route',
    backgroundTitle: 'Location active',
    requestPermissions: true,
    stale: false,
    url: 'https://api.example.com/locations',
    headers: { Authorization: 'Bearer fleet-token' },
    distanceFilter: 25,
  },
  (location, error) => {
    if (error) {
      console.error('Location error', error);
      return;
    }
    if (location) {
      console.log('Fix', location.latitude, location.longitude);
    }
  },
);

Cada corrección se entrega en paralelo a JavaScript (mientras el WebView esté activo) y a url con "source": "native" en el cuerpo JSON.

Ejemplo: webhook de geofence

await BackgroundGeolocation.setupGeofencing({
  url: 'https://api.example.com/geofence-hit',
  backgroundLocation: true,
});

En Android, declara ACCESS_BACKGROUND_LOCATION en tu manifest cuando necesites POSTs de geofencing en segundo plano (consulta la sección de geofencing nativo más abajo).

await BackgroundGeolocation.addGeofence({
  identifier: 'warehouse',
  latitude: 32.7,
  longitude: -117.1,
  radius: 200,
});

Ejemplo: detener el rastreo

await BackgroundGeolocation.stop();

Errores comunes

• Notificación de Android: las actualizaciones en segundo plano requieren backgroundMessage (y título) para que los usuarios vean por qué la ubicación está activa.
• Stale fixes: establecer stale: false cuando solo necesites correcciones de GPS recientes.
• Permisos: solicitud backgroundLocation por separado en las versiones modernas de Android.

Resumen de API

start

Para empezar a escuchar cambios en la ubicación del dispositivo, llama a este método. Se devuelve una Promise para indicar que la llamada finalizó. El callback se ejecutará cada vez que haya una nueva ubicación disponible, o si hubo un error al llamar a este método. No te bases en el rechazo 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 dirigir 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 Native Build).

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

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

Geofencing nativo

El geofencing se ejecuta en la capa nativa, por lo que iOS y Android pueden disparar eventos de entrada y salida sin depender de que la WebView esté activa. Configura una URL de webhook HTTP o HTTPS cuando tu backend deba recibir transiciones incluso si la interfaz de la app 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: 'store-42',
  latitude: 37.33182,
  longitude: -122.03118,
  radius: 150,
  payload: { storeId: '42' },
});

const handle = await BackgroundGeolocation.addListener(
  'geofenceTransition',
  (event) => {
    console.log(event.identifier, event.transition);
  },
);

const errorHandle = await BackgroundGeolocation.addListener(
  'geofenceError',
  (event) => {
    console.error(event.identifier, event.message);
  },
);

const { regions } = await BackgroundGeolocation.getMonitoredGeofences();
console.log(regions);

await BackgroundGeolocation.removeGeofence({ identifier: 'store-42' });
await handle.remove();
await errorHandle.remove();

On iOS, geofencing requires Always location authorization. On Android 10 and newer, add background location permission to your app manifest when you need background geofencing:

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

Referencia de tipos

StartOptions

Opciones para configurar las actualizaciones de ubicación.

export interface StartOptions {
  /**
   * If the "backgroundMessage" option is defined, the plugin will
   * provide location updates whether the app is in the background or the
   * foreground. If it is not defined, location updates are only
   * guaranteed in the foreground. This is true on both platforms.
   *
   * On Android, a notification must be shown to continue receiving
   * location updates in the background. This option specifies the text of
   * that notification.
   *
   * @since 7.0.9
   * @example "Getting your location to provide better service"
   */
  backgroundMessage?: string;
  /**
   * The title of the notification mentioned above.
   *
   * @since 7.0.9
   * @default "Using your location"
   * @example "Location Service"
   */
  backgroundTitle?: string;
  /**
   * Whether permissions should be requested from the user automatically,
   * if they are not already granted.
   *
   * @since 7.0.9
   * @default true
   * @example
   * // Auto-request permissions
   * requestPermissions: true
   *
   * // Don't auto-request, handle manually
   * requestPermissions: false
   */
  requestPermissions?: boolean;
  /**
   * If "true", stale locations may be delivered while the device
   * obtains a GPS fix. You are responsible for checking the "time"
   * property. If "false", locations are guaranteed to be up to date.
   *
   * @since 7.0.9
   * @default false
   * @example
   * // Allow stale locations for faster initial response
   * stale: true
   *
   * // Only fresh locations
   * stale: false
   */
  stale?: boolean;
  /**
   * The distance in meters that the device must move before a new location update is triggered.
   * This is used to filter out small movements and reduce the number of updates.
   *
   * @since 7.0.9
   * @default 0
   * @example
   * // Update every 10 meters
   * distanceFilter: 10
   *
   * // Update on any movement
   * distanceFilter: 0
   */
  distanceFilter?: number;
}

Location

Representa una ubicación geográfica con varios atributos. Contiene todas las propiedades de ubicación estándar devueltas por GPS/red.

export interface Location {
  /**
   * Latitude in degrees.
   * Range: -90.0 to +90.0
   *
   * @since 7.0.0
   * @example 40.7128
   */
  latitude: number;
  /**
   * Longitude in degrees.
   * Range: -180.0 to +180.0
   *
   * @since 7.0.0
   * @example -74.0060
   */
  longitude: number;
  /**
   * Radius of horizontal uncertainty in metres, with 68% confidence.
   * Lower values indicate more accurate location.
   *
   * @since 7.0.0
   * @example 5.0
   */
  accuracy: number;
  /**
   * Metres above sea level (or null if not available).
   *
   * @since 7.0.0
   * @example 10.5
   */
  altitude: number | null;
  /**
   * Vertical uncertainty in metres, with 68% confidence (or null if not available).
   *
   * @since 7.0.0
   * @example 3.0
   */
  altitudeAccuracy: number | null;
  /**
   * `true` if the location was simulated by software, rather than GPS.
   * Useful for detecting mock locations in development or testing.
   *
   * @since 7.0.0
   * @example false
   */
  simulated: boolean;
  /**
   * Deviation from true north in degrees (or null if not available).
   * Range: 0.0 to 360.0
   *
   * @since 7.0.0
   * @example 45.5
   */
  bearing: number | null;
  /**
   * Speed in metres per second (or null if not available).
   *
   * @since 7.0.0
   * @example 2.5
   */
  speed: number | null;
  /**
   * Time the location was produced, in milliseconds since the unix epoch.
   * Use this to check if a location is stale when using stale: true.
   *
   * @since 7.0.0
   * @example 1640995200000
   */
  time: number | null;
}

CallbackError

Objeto de error que puede pasarse al callback de inicio de ubicación. Extiende el Error estándar con códigos de error opcionales.

export interface CallbackError extends Error {
  /**
   * Optional error code for more specific error handling.
   *
   * @since 7.0.0
   * @example "PERMISSION_DENIED"
   */
  code?: string;
}

SetPlannedRouteOptions

export interface SetPlannedRouteOptions {
  /**
   * The name of the sound file to play.
   * Must be a valid sound relative path in the app's public folder to work for both web and native platforms.
   * There's no need to include the public folder in the path.
   * @since 7.0.10
   * @example "notification.mp3"
   * */
  soundFile: string;
  /**
   * The planned route as an array of longitude and latitude pairs.
   * Each pair represents a point on the route.
   * This is used to define a route that the user can follow.
   * The route is used to play a sound when the user deviates from it.
   * @since 7.0.11
   * @example [[-74.0060, 40.7128], [-118.2437, 34.0522]]
   */
  route: [number, number][];

  /**
   * The distance in meters that the user must deviate from the planned route to trigger the sound.
   * This is used to determine how far off the route the user can be before the sound is played.
   * If not specified, a default value of 50 meters is used.
   * @since 7.0.11
   * @default 50
   * @example 50
   */
  distance: number;
}

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos 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.