Warum iOS Hintergrund-Ortungsaktualisierungen stoppt

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 behandelt sie.

How iOS treats a backgrounded app

Wenn ein Benutzer das Home-Button drückt oder das Telefon verriegelt, gibt iOS der App einen kurzen Zeitraum, dann suspendiert es sie. Eine gesperrte App erhält keine CPU-Zeit. Für eine Capacitor-App bedeutet dies, dass sowohl die native Seite als auch der WebView stoppen, sodass Ihre JavaScript-Rückruf nicht mehr ausgelöst wird.

Apple macht eine Ausnahme für Apps, die aktiv die Standortverwendung nutzen. Wenn die App für Hintergrundstandort und eine aktive Standortverbindung konfiguriert ist, die im Vordergrund gestartet wurde, hält iOS sie laufend und liefert Updates weiter. Alles, was unten steht, dreht sich um das Einhalten dieses Vertrags und um die Fälle, in denen das System es absichtlich bricht.

Ursache 1: Der Hintergrundmodus für Standortverwendung fehlt

Ohne location in UIBackgroundModesKeine Menge an code wird Updates fließen lassen. Fügen Sie es hinzu ios/App/App/Info.plist:

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

You can also enable it in Xcode under Signing & Capabilities, Background Modes, Location updates. It is a plist key, not an entitlement, so no provisioning profile change is needed.

Die native Eigenschaft dahinter ist allowsBackgroundLocationUpdatesEinstellung auf true ohne den Hintergrundmodus in der plist stürzt die App ab. Der Capgo-Plugin stellt ihn für Sie ein, wenn Sie ihn übergeben backgroundMessage context start()und so muss die plist-Schlüssel vor der Veröffentlichung vorhanden sein.

App-Review-Überprüfungen stellen sicher, dass der Hintergrundmodus gerechtfertigt ist. Erklären Sie in den Überprüfungsnotizen, welche Funktion ihn verwendet, und stellen Sie sicher, dass die Funktion für den Rezensenten sichtbar ist.

Ursache 2: Updates wurden aus dem Hintergrund gestartet.

Apple’s rule: background updates continue if they were started while the app was in the foreground. Trying to start a session from a silent push, a background fetch or a BGTaskScheduler Die Aufgabe funktioniert nicht für Standardortaktualisierungen.

Von einer Benutzeraktion oder bei App-Wiedereinwerfen starten:

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;

Ursache 3: backgroundMessage Kein Wert wurde übergeben.

Dies ist speziell für das Capgo-Plugin und den häufigsten Fehlerbericht. Wenn backgroundMessage wird undefined, konfiguriert der Plugin-Manager den Standortdienst nur für Vordergrund-Verwendung. allowsBackgroundLocationUpdates stays false and updates stop when the app is suspended. Pass a message on both platforms. On Android it also becomes the text of the foreground service notification.

Ursache 4: falsche Autorisierungsstufe oder Zulassen einmal

Viele Entwickler glauben, sie benötigten immer Always zum Hintergrund-Tracking. Sie tun es nicht. Apple dokumentiert, dass eine App mit der Autorisierung When In Use solange im Hintergrund läuft, solange Hintergrund-Updates aktiviert sind.

Always ist wichtig für etwas anderes: Wiederherstellung einer beendeten App. Nur Region-Monitoring, signifikante Änderungen der Standort und Besuche können eine App wiederherstellen, und nur mit Always.

Zwei Benutzeroptionen brechen das Hintergrund-Tracking still und leise:

• Zulassen einmal. Dies ist eine temporäre When In Use-Zustimmung, die abläuft, wenn die App nicht mehr verwendet wird. Die nächste Sitzung beginnt von „nicht bestimmt“ wieder.
• Während des Gebrauchs, dann Always-Anfrage wird nie angezeigt. Wenn Sie ständige Updates anfordern, zeigt iOS das Upgrade-Fenster später an, zu einem Zeitpunkt, den es selbst bestimmt, oft wenn die App nicht auf dem Bildschirm ist.

Check the real state before you start a session:

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.
}

erhält man backgroundLocation oder when_in_use context granted / always, damit Sie die richtige Erklärung anstelle von Vermutungen ansehen können.

Ursache 5: Core Location pausiert Updates automatisch.

CLLocationManager.pausesLocationUpdatesAutomatically standardmäßig. true. Wenn iOS entscheidet, dass der Benutzer nicht bewegt, pausiert es Updates, um die Batterie zu sparen. Für eine App, die nur bei Bedarf Zugriff auf die Standortdaten hat, endet ein Pausieren die Standortzugriff, bis die App erneut gestartet wird, und Core Location setzt sich nicht von selbst fort.

Das Plugin Capgo setzt pausesLocationUpdatesAutomatically = false im eigenen native code, also wird dies behandelt. Wenn Sie ein eigenes native code schreiben oder ein anderes Plugin verwenden, überprüfen Sie diese Eigenschaft zuerst.

Ursache 6: Das Gerät ist stationär und der Filter ist groß.

Mit einem distanceFilter von 50 Metern erzeugt ein auf einem Schreibtisch sitzender Telefon keine Updates. Das sieht in Ihren Protokollen wie „Tracking gestoppt“ aus, aber es funktioniert wie vorgesehen.

• If you need heartbeats while stationary, use a small or zero distanceFilter.
• Use minIntervalMs um die Häufigkeit der native POSTs zu begrenzen, anstatt einen großen Entfernungsfilter.

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',
  },
  () => {},
);

Ursache 7: Genauigkeit der Standortbestimmung ist ausgeschaltet

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.

Ursache 8: Der Benutzer beendete die App

If the user swipes the app away in the app switcher, iOS stops standard location updates. No plugin can keep them running. This is a common surprise for teams coming from Android, where a foreground service can keep running after the task is removed.

Options:

• Tell users not to force quit during a session. Most fleet apps do this in onboarding.
• Senden Sie eine Benachrichtigung, um den Nutzer zu erinnern, die App wieder zu öffnen, wenn Ihr Server keine Punkte mehr für eine Sitzung erhält.
• Senden Sie eine Benachrichtigung, um dem Benutzer zu erinnern, die App wieder zu öffnen, wenn Ihr Server keine Daten mehr für eine Sitzung empfängt.

Kausal 9: JavaScript läuft nicht, trotzdem läuft native

A subtle one. Native code can receive a location while the WebView is suspended, or while it is still alive but not processing timers or network calls quickly. If you send points with fetch Ursache 8: Der Nutzer hat die App beendet

Verwenden Sie die Plugin-Einstellung. url Jeder Punkt wird POSTed von native code mit dem gleichen JSON wie der Location Typ plus "source": "native", unabhängig vom WebView. Halten Sie den Callback nur für UI-Updates. Die Lieferung ist bester Versuch mit keiner auf-Disk-Queue, also wenn Sie einen Punkt nicht verlieren können, speichern Sie ihn auch lokal, wenn der Callback ausgelöst wird und rechnen Sie später nach.

Für Hintergrund-Arbeit außerhalb der Standort, lesen Sie wie Hintergrund-Aufgaben in Capacitor funktionieren und sehen Sie @capgo/capacitor-background-task.

Ursache 10: Low Power Mode und thermische Zustand

Low Power Mode reduziert die Hintergrund-Aktivität über das System. Der Standort funktioniert noch, aber andere Dinge, auf die Ihre Sitzung angewiesen ist (Netzwerk-Wiederholungen, Hintergrund-Aktualisierungen), werden langsamer. Testen Sie mit Low Power Mode aktiviert, bevor Sie eine Veröffentlichung freigeben.

Der blaue Indikator

Wenn eine App mit When In Use-Berechtigung Standort in Hintergrund verwendet, zeigt iOS einen blauen Pill in der Statusleiste. Das Capgo-Plugin setzt showsBackgroundLocationIndicator zurück true für Hintergrundssitzungen, was Benutzer erwarten und was Rezensenten suchen. Versuchen Sie es nicht zu verbergen, Benutzer vertrauen ihm.

Eine Testplanung, die diese Fehler einfängt

Simulator-Tests sind für Hintergrund-Ortung nicht ausreichend. Verwenden Sie ein echtes iPhone und:

1. Erstellen Sie eine Release-Konfiguration, nicht nur Debug. Debug-Builds, die an Xcode angehängt sind, erhalten eine andere Lebenszyklusbehandlung.
2. Starten Sie eine Sitzung im Vordergrund, sperren Sie das Telefon, gehen Sie oder fahren Sie 20 Minuten.
3. Wiederholen mit „Erlauben einmal“, mit Präziser Standort ausgeschaltet, mit Energieeinsparmodus eingeschaltet.
4. Überprüfen Sie Ihre Server-Protokolle für source: "native" Punkte, nicht nur Ihre in-app-Protokolle.
5. Forzutötung während einer Sitzung und Bestätigung, dass Ihre App auf der nächsten Startanmeldung darüber informiert.

Wenn Sie ein Geräte-UDID für ad-hoc-Builds benötigen, findet der iOS-UDID-Finder es in Safari. Wenn Sie kein Mac mit Xcode 26 für Builds haben, Capgo Build Kann in der Cloud signierte iOS-Builds erstellen.

Troubleshooting-Checkliste

Versand von Reparaturen

Die meisten dieser Reparaturen berühren Info.plist oder native Konfiguration, sodass sie eine neue App-Store-Veröffentlichung benötigen. Die JavaScript-Teile, wie z.B. Erläuterungen zu den Berechtigungen, Einweisungstext und Wiederholungslogik, können an bestehende Benutzer mit Capgo Live-Updates versendet werden, sobald die native Veröffentlichung raus ist.

Wenn Sie zwischen Plugins entscheiden, vergleichen Sie unsere Transistorsoft und die kostenlose Capgo-Erweiterung bedeutet die Kompromisse.