Capacitor Device Sensors Guide: Motion, Compass, Steps

Capacitor Gerätesensoren stehen über kleine, fokussierte Plugins zur Verfügung: @capgo/capacitor-accelerometer zur Bewegung, @capgo/capacitor-barometer zur Luftdruckmessung, @capgo/capacitor-compass Für Überschriften @capgo/capacitor-pedometer Für Schritte, plus Licht, Nähe und Schütteln-Plugins. Jeder folgt dem gleichen Muster: Überprüfen Sie die Verfügbarkeit, stellen Sie eine Genehmigung ein, wenn erforderlich, starten Sie Updates, hören Sie zu und stoppen Sie, wenn Sie fertig sind. Diese Anleitung behandelt jeden Sensor mit Capacitor 8 code, die Plattformunterschiede, die zählen, und die Batterierichtlinien, die Apps aus dem Weg räumen.

Übersicht über die Sensoren

Installieren Sie nur, was Sie benötigen. Jeder Plugin ist klein, und weniger Berechtigungssätze bedeuten weniger Fragen im App-Review.

bun add @capgo/capacitor-accelerometer @capgo/capacitor-compass @capgo/capacitor-pedometer
bunx cap sync

iOS-Einrichtung

Fügen Sie die erforderlichen Benutzungsanweisungen hinzu ios/App/App/Info.plist:

<!-- Accelerometer, pedometer, barometer altitude -->
<key>NSMotionUsageDescription</key>
<string>Counts your steps and detects movement during workouts.</string>

<!-- Compass heading -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>Shows which direction you are facing on the map.</string>

Erklären Sie den Nutzen in einfachen Worten. Allgemeine Texte wie „Diese App benötigt Zugriff auf Bewegungen“ sind häufige Gründe für die Ablehnung von App-Bewertungen.

Android-Einrichtung

Die meisten Sensoren benötigen keine Erlaubnis. Der Pedometer-Plugin fügt ACTIVITY_RECOGNITION zum kombinierten Manifest und Sie fordern es zum Laufzeit auf Android 10+ an.

Wenn ein Sensor entscheidend ist, deklarieren Sie die Hardware-Funktion, damit Google Play Ihre App von Geräten ohne sie versteckt. Wenn es optional ist, deklarieren Sie es mit required="false" und überprüfen Sie die Verfügbarkeit zum Laufzeit:

<uses-feature android:name="android.hardware.sensor.barometer" android:required="false" />
<uses-feature android:name="android.hardware.sensor.stepcounter" android:required="false" />
<uses-feature android:name="android.hardware.sensor.compass" android:required="false" />

Accelerometer: Bewegung und Neigung

Der Accelerometer berichtet die Beschleunigung auf den x-, y- und z-Achsen in G. Ein flach liegender Smartphone liest etwa z = -1 oder 1 abhängig von der Plattformkonvention, da die Schwerkraft enthalten ist.

import { CapacitorAccelerometer } from '@capgo/capacitor-accelerometer';

const { isAvailable } = await CapacitorAccelerometer.isAvailable();
if (isAvailable) {
  await CapacitorAccelerometer.requestPermissions();

  const listener = await CapacitorAccelerometer.addListener('measurement', ({ x, y, z }) => {
    const tiltX = Math.atan2(x, Math.sqrt(y * y + z * z)) * (180 / Math.PI);
    ball.style.transform = `translateX(${tiltX * 3}px)`;
  });

  await CapacitorAccelerometer.startMeasurementUpdates();

  // later
  await CapacitorAccelerometer.stopMeasurementUpdates();
  await listener.remove();
}

Use cases: tilt controls in games, “lift to wake” UI, fall or impact detection, activity intensity. Raw data is noisy, so smooth it with a low-pass filter before using it:

const alpha = 0.2;
let smoothed = { x: 0, y: 0, z: 0 };

function lowPass(m: { x: number; y: number; z: number }) {
  smoothed = {
    x: smoothed.x + alpha * (m.x - smoothed.x),
    y: smoothed.y + alpha * (m.y - smoothed.y),
    z: smoothed.z + alpha * (m.z - smoothed.z),
  };
  return smoothed;
}

Aktualisieren Sie den DOM nicht bei jedem Sample. Speichern Sie den neuesten Wert und rendern Sie ihn in einem requestAnimationFrame loop.

Schüttelgesten

Erstellen Sie nicht auf jeden Sample die DOM. Speichern Sie den neuesten Wert und rendern Sie ihn in einem

import { CapacitorShake } from '@capgo/capacitor-shake';

const handle = await CapacitorShake.addListener('shake', () => openFeedbackForm());

Gyroskop und Geräteorientierung

Für Rotation ist kein separates Plugin erforderlich. Die WebView zeigt es bereits an:

async function enableMotion() {
  // iOS 13+ requires a user gesture and explicit permission
  const DME = DeviceMotionEvent as unknown as { requestPermission?: () => Promise<'granted' | 'denied'> };
  if (typeof DME.requestPermission === 'function') {
    const result = await DME.requestPermission();
    if (result !== 'granted') return;
  }

  window.addEventListener('devicemotion', (e) => {
    const r = e.rotationRate; // alpha, beta, gamma in degrees per second
    if (r) updateRotation(r.alpha ?? 0, r.beta ?? 0, r.gamma ?? 0);
  });

  window.addEventListener('deviceorientation', (e) => {
    // alpha: 0-360 around z, beta: -180..180 front/back, gamma: -90..90 left/right
    updateOrientation(e.alpha, e.beta, e.gamma);
  });
}

document.querySelector('#enable-motion')!.addEventListener('click', enableMotion);

Aufrufen requestPermission nur nach einem Buttonklick, nie beim Seitenaufruf, sonst lehnt iOS den Antrag ab.

Kompass: Richtung

import { CapgoCompass, CompassAccuracy } from '@capgo/capacitor-compass';

const status = await CapgoCompass.requestPermissions(); // iOS: location permission
if (status.compass === 'granted') {
  await CapgoCompass.addListener('headingChange', ({ value }) => {
    needle.style.transform = `rotate(${-value}deg)`;
  });

  await CapgoCompass.startListening({
    minInterval: 100,      // ms between events
    minHeadingChange: 2,   // degrees
  });

  // Android only: ask the user to calibrate when accuracy drops
  await CapgoCompass.addListener('accuracyChange', ({ accuracy }) => {
    calibrationHint.hidden = accuracy >= CompassAccuracy.MEDIUM;
  });
  await CapgoCompass.watchAccuracy();
}

// One-off reading
const { value } = await CapgoCompass.getCurrentHeading();

value Werte zwischen 0 und 360 Grad vom magnetischen Nordpol. Dinge zu beachten:

• The magnetometer is disturbed by magnets in phone cases, laptops and car mounts. Show a calibration hint (move the phone in a figure eight) when Android reports low accuracy.
• Drosselung mit minInterval Bremsen mit minHeadingChange anstatt in JavaScript. Es spart Brückenverkehr.
• For a map that rotates with the user, combine heading with geolocation. If you need location while the app is in the background, see the Hintergrund-Geolokalisierungs-Plugin.

Schrittzähler: Schritte, Distanz und Stockwerke

Der Schrittzähler ist ein leistungssparender Chip, der kontinuierlich zählt, selbst wenn Ihre App nicht läuft.

import { CapacitorPedometer } from '@capgo/capacitor-pedometer';

const features = await CapacitorPedometer.isAvailable();
// { stepCounting, distance, pace, cadence, floorCounting }

const perm = await CapacitorPedometer.requestPermissions();
if (perm.activityRecognition !== 'granted') {
  // explain why and link to settings
}

// Steps today (start and end are required on iOS)
const startOfDay = new Date();
startOfDay.setHours(0, 0, 0, 0);
const today = await CapacitorPedometer.getMeasurement({
  start: startOfDay.getTime(),
  end: Date.now(),
});
console.log(today.numberOfSteps, today.distance, today.floorsAscended);

// Live updates during a walk
await CapacitorPedometer.addListener('measurement', (m) => {
  stepsEl.textContent = String(m.numberOfSteps ?? 0);
});
await CapacitorPedometer.startMeasurementUpdates();

Plattformunterschiede:

• iOS (Core Motion) beantwortet historische Abfragen für etwa die letzten sieben Tage und liefert außerdem Distanz, Stockwerke, Tempo und Schrittfrequenz auf unterstützten Geräten.
• Android berichtet nur Schritte. Der Hardwarezähler wird bei einem Neustart zurückgesetzt, also behandeln Sie ihn nicht als Lebenszeitgesamtsumme. Speichern Sie Ihre eigene Basiswert.

Für eine lange Zeitreihe, tägliche Gesamtsummen auf verschiedenen Geräten oder Daten von einem Fitnessarmband, lesen Sie stattdessen aus dem Health-Store mit @capgo/capacitor-health anstatt. Es aggregiert Schritte aus allen Quellen in Apple Health und Health Connect. Unsere Health Connect-Migration-Anleitung erklärt die Einrichtung.

Barometer: Druck und Höhe

import { CapacitorBarometer } from '@capgo/capacitor-barometer';

const { isAvailable } = await CapacitorBarometer.isAvailable();
if (isAvailable) {
  await CapacitorBarometer.requestPermissions();
  await CapacitorBarometer.addListener('measurement', ({ pressure, relativeAltitude }) => {
    pressureEl.textContent = `${pressure.toFixed(1)} hPa`;
    altitudeEl.textContent = `${relativeAltitude.toFixed(1)} m`;
  });
  await CapacitorBarometer.startMeasurementUpdates();
}

pressure ist in Hektopascalen auf beiden Plattformen. relativeAltitude ist der seit Updates startend gemessene Meterwechsel, der nur von iOS bereitgestellt wird. Auf Android ist es immer 0, also berechne es selbst mit der barometrischen Formel:

const P0 = 1013.25; // standard sea-level pressure in hPa
const altitudeMeters = (p: number) => 44330 * (1 - Math.pow(p / P0, 1 / 5.255));

let baseline: number | null = null;
function relativeAltitude(pressure: number) {
  baseline ??= altitudeMeters(pressure);
  return altitudeMeters(pressure) - baseline;
}

Die absolute Höhe aus der Druckmessung ist um Zehnermeter von der tatsächlichen abweichend, weil sich das Wetter auf die Meereshöhe auswirkt. Die relativen Änderungen über Minuten sind genau bis auf einen Meter, was ausreichend ist, um Stockwerke oder Anstiege zu zählen. Viele Budget-Android-Smartphones haben keinen Barometer, also prüfe immer isAvailable.

Beleuchtungslichtsensor (Android)

import { LightSensor } from '@capgo/capacitor-light-sensor';

const { available } = await LightSensor.isAvailable(); // always false on iOS
if (available) {
  await LightSensor.addListener('lightSensorChange', ({ illuminance }) => {
    document.body.classList.toggle('high-contrast', illuminance > 10_000); // bright sunlight
  });
  await LightSensor.start({ updateInterval: 500 });
}

Typische Werte: unter 10 Lux ist ein dunkles Zimmer, einige hundert Lux ein Büro, Zehntausende Lux direkte Sonneneinstrahlung. Verwende es für eine Lesemodusanpassung, die sich an den Raum anpasst, oder um den Contrast bei Außen zu erhöhen. Um die Bildschirmhelligkeit selbst zu ändern, paare es mit @capgo/capacitor-brightness.

Nahesensorkennung

Der Nahsensore meldet dir, wenn etwas die Oberseite des Bildschirms bedeckt, normalerweise das Ohr des Benutzers während eines Anrufs.

import { CapacitorProximity } from '@capgo/capacitor-proximity';

const status = await CapacitorProximity.getStatus();
if (status.available) {
  await CapacitorProximity.enable();  // screen turns off when covered
}

// when the call or voice message ends
await CapacitorProximity.disable();

Bei iOS schaltet dies UIDevice.isProximityMonitoringEnabled, was den Bildschirm aus schaltet, wenn er bedeckt ist. Bei Android hört der Plugin auf den Nahsensore und dimmt das App-Fenster. Aktiviere es nur während eines Sprachanrufs, einer Sprachnachricht oder eines Walkie-Talkie-Modus, damit das Ohr des Benutzers keine Tasten drückt.

Praktische Regeln für Sensore-Anwendungen

1. Prüfe die Verfügbarkeit zuerst. Tablets fehlen oft ein Schrittzähler oder ein Barometer, und Emulatoren faken die meisten Sensoren. Verberge Funktionen, die du nicht unterstützen kannst.
2. Stoppe Updates, wenn sie nicht sichtbar sind. Verwende @capacitor/app's appStateChange um Hörer zu stoppen, wenn das App in den Hintergrund geht und sie bei der Wiederanmeldung neu zu starten. Sensoren, die im Hintergrund laufen, verbrauchen die Batterie und führen zu einer Bewertung von 1 Stern.
3. Beschränke in native code , wenn der Plugin es erlaubt (Kompass minInterval, Lichtsensor updateInterval), nicht in JavaScript.
4. Stelle in diesem Kontext eine Erlaubnis an. Request motion access when the user starts a workout, not on first launch.
5. Testen Sie auf echtem Hardware. Simulatoren liefern konstante oder synthetische Werte. Testen Sie zumindest ein Budget-Android-Smartphone, bei dem Sensoren fehlen oder störend sind.
6. Respektieren Sie die Datenschutzregeln. Die Bewegungs- und Standortdaten gelten als sensibel in den Datenschutzlabels des App Stores und der Play-Datensicherheitsform. Erklären Sie, was Sie sammeln.

Troubleshooting

: Die Verwendungsoption ist fehlend inDie Verwendungsoption fehlt. Info.plist, oder die Berechtigung wurde abgelehnt. Überprüfe Einstellungen, Datenschutz und Sicherheit, Bewegung und Fitness.

Schrittzähler gibt auf Android 0 zurück: ACTIVITY_RECOGNITION was verwehrt wurde oder das Gerät keinen Schrittzähler hat. Überprüfen Sie isAvailable().stepCounting.

Magnetkompass springt herumMagnetische Störungen oder keine Kalibrierung. Überprüfen Sie die Genauigkeit auf Android und zeigen Sie eine Kalibrierungshinweis an.

relativeAltitude ist immer 0: erwartet auf Android. Berechnen Sie es aus dem Druck wie oben gezeigt.

DeviceMotionEvent.requestPermission werfen: es wurde nicht von einem Benutzereingriff aufgerufen.

Batterieentladungsberichte: Hörer bleiben im Hintergrund laufen. Stoppen Sie sie auf appStateChange.

Sensorfunktionen schnell verschicken

Schwellenwerte, Glättungsfaktoren und UI für Sensorfunktionen benötigen in der Regel mehrere Runden der Anpassung mit echten Benutzern. Diese Logik lebt in JavaScript, sodass Sie sie mit Capgo Live-Updates ohne eine App-Store-Bewertung, während neue Plugins und Berechtigungszeichen durch eine reguläre Build gehen. Wenn Sie externe Sensoren wie Brustgurten anschließen, fahren Sie mit unserer Anleitung zum Erstellen eines Herzfrequenzmonitors mit Capacitor.