Why iOS Stops Background Location Updates

iOS stops background location updates because it suspends your app, not because Core Location fails. Unless the app declares the location background mode, enables background updates on its CLLocationManager, and starts them while it is still in the foreground, iOS freezes the process a few seconds after the user leaves and queues or drops the fixes. This guide lists every cause we see in Capacitor apps, with the fix for each, and shows how @capgo/background-geolocation maneja ellos.

¿Cómo iOS trata a una aplicación en segundo plano

When a user swipes home or locks the phone, iOS gives the app a short window, then suspends it. A suspended app gets no CPU time. For a Capacitor app this means both the native side and the WebView stop running, so your JavaScript callback stops firing too.

Apple makes an exception for apps that are actively using location. If the app is configured for background location and has an active location session started in the foreground, iOS keeps it running and keeps delivering updates. Everything below is about meeting that contract, and about the cases where the system breaks it on purpose.

¿Cómo trata iOS una aplicación de fondo?

Sin location en UIBackgroundModes, ninguna cantidad de code mantendrá actualizaciones en flujo. Agregue esto a ios/App/App/Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

Puede habilitarlo también en Xcode en Signing & Capabilidades, Modos de fondo, Actualizaciones de ubicación. Es una clave de plist, no un permiso, por lo que no se necesita cambiar el perfil de provisión.

La propiedad nativa detrás de esto es allowsBackgroundLocationUpdates. Estableciéndolo en true sin el modo de fondo en el plist, el app se cae. El plugin Capgo lo establece por usted cuando pasa backgroundMessage a start(), por lo tanto, el key plist debe estar presente antes de enviar.

La revisión de la App verifica que el modo de fondo esté justificado. Explique en las notas de revisión qué característica lo utiliza, y asegúrese de que la característica esté visible para el revisor.

Causa 2: las actualizaciones se iniciaron desde el fondo

La regla de Apple: las actualizaciones de fondo continúan si se iniciaron mientras la app estaba en el primer plano. Al intentar iniciar una sesión desde un empujón silencioso, un recuento de fondo o un BGTaskScheduler La tarea no funciona para actualizaciones de ubicación estándar.

Inicie la pista desde una acción del usuario o al reanudar la aplicación:

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

let tracking = false;

export async function startTracking() {
  if (tracking) return;
  tracking = true;
  await BackgroundGeolocation.start(
    {
      backgroundMessage: 'Recording your route',
      backgroundTitle: 'Route recording',
      requestPermissions: true,
      distanceFilter: 10,
      url: 'https://api.example.com/v1/points',
    },
    (location, error) => {
      if (error) return console.error(error);
      if (location) console.log(location.latitude, location.longitude);
    },
  );
}

// Re-arm when the user comes back, if the session should be active
App.addListener('appStateChange', ({ isActive }) => {
  if (isActive && shouldBeTracking()) startTracking();
});

declare function shouldBeTracking(): boolean;

Causa 3: backgroundMessage no se pasó

Esto es específico del plugin Capgo y es el informe de bug más común. Si backgroundMessage está indefinido, el plugin configura el administrador de ubicación para el uso de primer plano solo: allowsBackgroundLocationUpdates se queda false y las actualizaciones de ubicación cesan cuando la aplicación se suspende. Pase un mensaje en ambas plataformas. En Android también se convierte en el texto de la notificación del servicio de primer plano.

Causa 4: el nivel de autorización incorrecto, o Autorizar una vez

Muchos desarrolladores creen que necesitan siempre autorizar para seguir la ubicación en segundo plano. No lo necesitan. Apple documenta que una aplicación con autorización de uso cuando se requiere sigue funcionando en segundo plano mientras tiene servicios de ubicación activos, siempre y cuando se habiliten las actualizaciones de segundo plano.

Siempre importa para otra cosa: reiniciar una aplicación terminada. Solo la monitoreo de región, cambios significativos de ubicación y visitas pueden reiniciar una aplicación, y solo con Siempre.

Dos opciones de usuario silenciosamente rompen el seguimiento de fondo:

• Permitir una vez. Esta es una autorización temporal When In Use que expira cuando la aplicación deje de usarse. La próxima sesión comienza desde “no determinado” de nuevo.
• Mientras Usando, luego siempre pregunta nunca mostrada. Cuando solicites siempre, iOS puede mostrar la solicitud de actualización más tarde, en un momento que elija, a menudo cuando la aplicación no esté en pantalla.

Verifica el estado real antes de iniciar una sesión:

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

const status = await BackgroundGeolocation.checkPermissions();

if (status.location !== 'granted') {
  await BackgroundGeolocation.requestPermissions({ permissions: ['location'] });
}

if (status.backgroundLocation === 'when_in_use') {
  // Background tracking still works for standard updates.
  // Explain why Always helps if you also rely on geofences.
}

En iOS, backgroundLocation devuelve when_in_use o granted / alwaysAsí, puedes mostrar la explicación correcta en lugar de adivinar.

, por lo tanto, puedes mostrar la explicación correcta en lugar de adivinar.

CLLocationManager.pausesLocationUpdatesAutomatically defaults to true. When iOS decides the user is not moving, it pauses updates to save battery. For a When In Use app, a pause ends location access until the app is launched again, and Core Location does not resume on its own.

El plugin Capgo establece pausesLocationUpdatesAutomatically = false en su nativo code, por lo que se maneja este caso. Si escribe su propio nativo code, o utiliza otro plugin, compruebe esta propiedad primero.

Causa 6: el dispositivo está inmóvil y el filtro es grande

Con un distanceFilter de 50 metros, un teléfono sentado en una mesa no produce actualizaciones. Eso parece “se ha detenido la seguimiento” en tus registros, pero está funcionando como diseñado.

• Si necesita latidos del corazón mientras está inmóvil, utilice un pequeño o cero distanceFilter.
• Use minIntervalMs para limitar cuántas veces se envían POST nativos, en lugar de un gran filtro de distancia.

await BackgroundGeolocation.start(
  {
    backgroundMessage: 'Vehicle tracking active',
    distanceFilter: 0,
    minIntervalMs: 120_000, // at most one native POST every 2 minutes
    url: 'https://api.example.com/v1/vehicle-points',
  },
  () => {},
);

Causa 7: Precise Location está desactivado

Since iOS 14 users can turn off Precise Location for your app. You still get updates, but they are approximate (several kilometers) and arrive much less often. Detect this in your data (large accuracy values) and explain to the user why precise location matters for your feature. If you ship a delivery or fitness app, show this in onboarding, not after a bad trip.

Causa 9: el dispositivo está apagado

If el usuario desplaza la aplicación hacia la bandeja de aplicaciones, iOS detiene las actualizaciones de ubicación estándar. No hay plugin que pueda mantenerlas funcionando. Esto es una sorpresa común para los equipos que provienen de Android, donde un servicio de primer plano puede seguir funcionando después de que se elimina la tarea.

Opciones:

• No fuerce cierre durante una sesión. La mayoría de las aplicaciones de flota lo hacen en la configuración inicial.
• Agregue geofencos con autorización de 'Siempre' alrededor de lugares importantes para que iOS pueda relanzar la aplicación en segundo plano al entrar o salir.
• Envía una notificación para recordar al usuario que reabra la aplicación cuando su servidor deja de recibir puntos para una sesión.

Causa 9: El JavaScript no está funcionando aunque el nativo sí

Uno muy sutil. El nativo code puede recibir una ubicación mientras el WebView está suspendido, o mientras sigue vivo pero no está procesando temporizadores o llamadas de red rápidamente. Si envías puntos con fetch pueden llegar tarde o no llegar en absoluto.

Utilice el plugin url opción. Cada punto se envía desde nativo code con el mismo JSON que el Location tipo más "source": "native", independent of the WebView. Keep the callback for UI updates only. Delivery is best effort with no on-disk queue, so if you cannot lose a point, also store it locally when the callback fires and reconcile later.

For trabajo de fondo más allá de la ubicación, lee cómo funcionan las tareas de fondo en Capacitor y ve @capgo/capacitor-background-task.

La causa 10: Modo de bajo consumo y estado térmico

El Modo de bajo consumo reduce la actividad de fondo en todo el sistema. La ubicación sigue funcionando, pero otras cosas en las que tu sesión depende (reintentos de red, actualizaciones de fondo) se ralentizan. Prueba con el Modo de bajo consumo activado antes de firmar un lanzamiento.

El indicador azul

Cuando una aplicación con autorización de uso en uso utiliza la ubicación en segundo plano, iOS muestra una píldora azul en la barra de estado. El plugin Capgo establece showsBackgroundLocationIndicator to true para sesiones de fondo, lo que los usuarios esperan y lo que los revisores buscan. No traten de ocultarlo, los usuarios confían en ello.

Un plan de pruebas que detecta estos errores

Pruebas de simulador no son suficientes para ubicación de fondo. Utilice un iPhone real y:

1. Crea una configuración de lanzamiento, no solo de depuración. Los builds de depuración asociados a Xcode reciben un tratamiento de ciclo de vida diferente.
2. Comience una sesión en primer plano, bloquee el teléfono, camine o conduzca durante 20 minutos.
3. Repite con “Permitir una vez”, con ubicación precisa desactivada, con modo de ahorro de energía activado.
4. Verifique los registros de su servidor para source: "native" puntos, no solo sus registros en la aplicación.
5. Forcee la salida durante una sesión y confirme que su aplicación explica qué sucedió en la próxima lanzamiento.

Si necesita un ID de dispositivo para compilaciones ad hoc, el encuentrador de ID de dispositivo iOS lo obtiene de Safari. Si no tiene un Mac con Xcode 26 para compilaciones, Capgo Compilación puede producir compilaciones de iOS firmadas en la nube.

Lista de verificación de depuración

Correcciones de envío

La mayoría de estas correcciones afectan Info.plist o la configuración nativa, por lo que necesitan una nueva versión del App Store. Las partes de JavaScript, como las explicaciones de permisos, el contenido de inicio de sesión y la lógica de reintento, se pueden enviar a los usuarios existentes con Capgo actualizaciones en vivo una vez que la versión nativa esté disponible.

Si está decidiendo entre plugins, nuestra comparación de Transistorsoft y el plugin gratuito Capgo aborda los pros y los contras.