Capacitor Gerätesensoren-Leitfaden: Bewegung, Kompass, Schritte

Capacitor Gerätesensoren stehen über kleine, fokussierte Plugins zur Verfügung: @capgo/capacitor-accelerometer zur Bewegung, @capgo/capacitor-barometer zur Luftdruckmessung, @capgo/capacitor-compass zur Orientierung, @capgo/capacitor-pedometer zur Schrittzählung, plus Licht, Nähe und Schüttelpack-Plugins. Jedes 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. Dieser Leitfaden behandelt jeden Sensor mit Capacitor 8 code, den Plattformunterschiede, die zählen, und die Akkubestimmungen, die Apps vor Schwierigkeiten bewahren.

Sensorenübersicht

Install nur das, was du verwendest. 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 Verwendungszuordnungen für Ihre Sensoren 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>

Beschreiben Sie den Nutzen für den Benutzer in einfachen Worten. Allgemeine Texte wie „Diese App benötigt Zugriff auf Bewegungen“ sind häufige Gründe für einen App-Review-Widerspruch.

Android-Einrichtung

Die meisten Sensoren benötigen keine Berechtigung. Der Pedometer-Plugin fügt ACTIVITY_RECOGNITION zur Merged-Manifest hinzu, und Sie fordern ihn bei 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 fernhält. Wenn er optional ist, deklarieren Sie ihn mit required="false" und überprüfen Sie die Verfügbarkeit bei 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 Je nach 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();
}

Verwendungsfälle: Tiltsteuerungen in Spielen, "Lift-to-Wake"-Benutzeroberfläche, Sturz- oder Aufprallerkennung, Aktivitätsintensität. Die Rohdaten sind rauschig, also glätten Sie sie mit einem Tiefpassfilter, bevor Sie sie verwenden:

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

Ändern Sie nicht den DOM auf jedem Sample. Speichern Sie den neuesten Wert und rendern Sie ihn in einem requestAnimationFrame loop.

Schüttelgesten

Für "Bugs melden, indem man den Gerät schüttelt" oder "Durch Schütteln rückgängig machen", müssen Sie keine Schwellenwerte anpassen.

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

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

Gyroskop und Geräteorientierung

Es gibt kein separates Plugin für die Rotation. 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);

Call requestPermission nicht ausgelöst durch eine Seite, nie bei der Seitenladung, 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 ist Grad von dem magnetischen Norden, 0 bis 360. Dinge zu beachten:

• Der Magnetometer wird durch Magnete in Telefonhüllen, Laptops und Autoladungen gestört. Zeige eine Kalibrierungshinweis (bewege das Telefon in einem acht geschlossenen Kreis) an, wenn Android eine niedrige Genauigkeit meldet.
• Verzögern Sie mit minInterval und minHeadingChange anstatt in JavaScript. Es spart Brückentransport.
• Für eine Karte, die sich mit dem Benutzer dreht, kombinieren Sie die Richtung mit der Geolocation. Wenn Sie die Standortinformationen benötigen, während die App im Hintergrund läuft, sehen Sie sich das Hintergrund-Geolocation-Plugin.

Schrittzähler: Schritte, Entfernung und Etagen

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 Anfragen für etwa die letzten sieben Tage und liefert außerdem Entfernung, Stockwerke, Geschwindigkeit 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 Basislinie.

Für eine lange Zeitreihe, tägliche Gesamtsummen auf verschiedenen Geräten oder Daten von einem Armband, lesen Sie aus dem Gesundheitsstore mit @capgo/capacitor-health anstatt. Es aggregiert Schritte aus allen Quellen in Apple Health und Health Connect. Unsere Health Connect-Migrationshandbuch 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 wird auf beiden Plattformen in Hektopascalen angezeigt. relativeAltitude seit Updates gestartet wurden, angegeben in Metern, nur auf iOS verfügbar. Auf Android ist es immer 0so berechnen Sie sie 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 dem Druck ist um Zehner von Metern falsch, weil sich das Wetter den Meeresdruck ändert. Relative Änderungen über Minuten sind genau auf etwa einen Meter genau, was ausreicht, um Stockwerke oder Anstiege zu zählen. Viele Budget-Android-Smartphones haben keinen Barometer, also überprüfen Sie immer isAvailable.

Luftlichtsensor (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 direktes Sonnenlicht. Verwenden Sie es für eine Lesemodus, der sich an den Raum anpasst, oder um den Contrast draußen zu erhöhen. Um die Bildschirmhelligkeit selbst zu ändern, pair es mit @capgo/capacitor-brightness.

Nahesensorkennung

Der Nahsensore erzählt Ihnen, 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, während er bedeckt ist. Bei Android hört der Plugin auf den Nahsensore und dimmt das App-Fenster. Aktivieren Sie es nur während eines Sprachanrufs, Sprachnachricht oder Walkie-Talkie-Modus, damit das Ohr des Benutzers keine Tasten drückt.

Praktische Regeln für Sensoren-Apps

1. Überprüfen Sie die Verfügbarkeit zuerst. Tablets fehlen oft einen Schrittzähler oder Barometer, und Emulatoren faken die meisten Sensoren. Verbergen Sie Funktionen, die Sie nicht unterstützen.
2. Halten Sie Updates an, wenn nicht sichtbar. Use @capacitor/app's appStateChange Um Hintergrundläufer zu stoppen, wenn die App in den Hintergrund geht und sie bei der Wiederaufnahme zu starten. Lautende Sensoren verbrauchen die Batterie und verursachen eine einstellige Bewertung.
3. Throttlung in native code wenn der Plugin dies zulässt (Kompass) minInterval, Lichtsensor) updateInterval, nicht in JavaScript.
4. Bei Bedarf um Erlaubnis bitten. 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. Respektiere die Datenschutzregeln. Bewegungs- und Standortdaten gelten als sensibel in den Datenschutzlabels des App Stores und der Play-Datensicherheitsform. Erklären Sie, was Sie sammeln.

Troubleshooting

Keine Ereignisse auf iOSDie Verwendungsschleife 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 besitzt. Ü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 0Berechnen Sie es aus dem Druck wie oben gezeigt.

DeviceMotionEvent.requestPermission throwsEs wurde nicht aus einer Benutzereingabe ausgelöst.

Akkuentleerungsberichte: Hintergrundprozesse bleiben laufen. Beenden Sie sie auf appStateChange.

Sensorfunktionen schnell bereitstellen

Schwellenwerte, Glättungsfaktoren und Benutzeroberfläche für Sensorfunktionen benötigen in der Regel mehrere Runden an Anpassungen mit echten Benutzern. Diese Logik befindet sich in JavaScript, sodass Sie sie mit Capgo Live-Updates ohne eine App-Store-Überprüfung, während neue Plugins und Berechtigungszeichen durch einen regulären Build gehen. Wenn Sie externe Sensoren wie Brustgurten anschließen, fahren Sie mit unserer Anleitung fort, um ein Herzfrequenz-Monitor mit __CAPGO_KEEP_0__ Ein Herzfrequenzmesser bauen mit Capacitor.