Guide des capteurs de dispositif de Capacitor: Mouvement, Boussole, Étapes

les capteurs de dispositif Capacitor sont disponibles à travers de petits plugins ciblés : @capgo/capacitor-accelerometer pour le mouvement, @capgo/capacitor-barometer pour la pression atmosphérique, @capgo/capacitor-compass pour titre, @capgo/capacitor-pedometer pour étapes, plus lumineux, de proximité et de secousses plugins. Chacun suit le même modèle : vérifiez la disponibilité, demandez la permission si nécessaire, commencez les mises à jour, écoutez, et arrêtez lorsque vous avez terminé. Ce guide couvre tous les capteurs avec Capacitor 8 code, les différences de plateforme qui comptent, et les règles de batterie qui gardent les applications hors de la difficulté.

Vue d'ensemble du capteur

Installez uniquement ce dont vous avez besoin. Chaque plugin est léger, et moins de chaînes de permission signifie moins de questions lors de la revue de l'application.

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

Configuration iOS

Ajoutez les chaînes d'utilisation dont vos capteurs ont besoin 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>

Explain the user benefit in plain words. Generic text like “This app needs motion access” is a frequent App Review rejection reason.

Configuration Android

La plupart des capteurs n'ont pas besoin de permission. Le plugin du pédomètre ajoute ACTIVITY_RECOGNITION au manifest fusionné, et vous le demandez en temps réel sur Android 10+.

Si un capteur est essentiel, déclarez la fonctionnalité matérielle pour que Google Play cache votre application sur les appareils sans elle. Si elle est facultative, déclarez-l’avec required="false" et vérifiez sa disponibilité en temps réel :

<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" />

Accéléromètre : mouvement et inclinaison

L'accéléromètre rapporte l'accélération sur les axes x, y et z en G. Un téléphone posé sur le dos lit environ z = -1 ou 1 Selon la convention de la plateforme, car la gravité est incluse.

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

N'actualisez pas la page entière à chaque échantillon. Stockez la valeur la plus récente et affichez-la dans un requestAnimationFrame loop.

Shake gestures

Pour “secouer pour signaler un bug” ou “secouer pour annuler”, vous n'avez pas besoin de réglage des seuils vous-même.

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

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

Gyroscope et orientation du dispositif

Une extension spécifique n'est pas nécessaire pour la rotation. Le WebView l'expose déjà :

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

Appeler requestPermission ne jamais sur la charge de la page, ou iOS rejette la demande.

Appflow Migration Step2

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 Les choses à savoir : jusqu'à 360 degrés par rapport au nord magnétique.

• 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.
• Throtte avec minInterval and minHeadingChange plutôt en JavaScript. Cela économise le trafic de pont.
• 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 plugin de géolocalisation de fond.

Pedomètre : pas, distance et étages

Le compteur d'étapes est un circuit à faible consommation qui compte sans arrêt, même lorsque votre application n'est pas en cours d'exécution.

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();

Différences entre les plateformes :

• iOS Répond à des requêtes historiques pendant environ les sept derniers jours et fournit également la distance, les étages, le rythme et la cadence sur les appareils pris en charge.
• Android se limite aux pas. Le compteur matériel est réinitialisé à chaque redémarrage, il ne faut donc pas le considérer comme un total à vie. Enregistrez votre propre valeur de référence.

Pour une histoire à long terme, des totaux quotidiens sur plusieurs appareils ou des données provenant d'un montre, lisez à la place de @capgo/capacitor-health qui agrège les pas provenant de toutes les sources dans Apple Health et Health Connect. Notre guide de migration vers Health Connect explique la configuration.

Baromètre : pression et altitude

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 est en hectopascals sur les deux plateformes. relativeAltitude La différence en mètres depuis les mises à jour ont commencé, fournie par iOS uniquement. Sur Android, c'est toujours 0Par conséquent, calculez-le vous-même à l'aide de la formule barométrique :

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

L'altitude absolue à partir de la pression est en erreur de dizaines de mètres en raison des changements météorologiques de la pression de niveau de la mer. Les changements relatifs sur quelques minutes sont précis à environ un mètre, ce qui est suffisant pour compter les étages ou les ascensions. Beaucoup de téléphones Android de budget n'ont pas de baromètre, il faut donc toujours vérifier isAvailable.

Capteur de lumière ambiante (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 });
}

Valeurs typiques : une pièce sombre est inférieure à 10 lux, quelques centaines de lux sont une salle de bureau, des dizaines de milliers sont un soleil direct. Utilisez-le pour un mode de lecture qui s'adapte à la pièce, ou pour augmenter le contraste en plein air. Pour modifier l'éclat de l'écran lui-même, associez-l’à @capgo/capacitor-brightness.

Capteur de proximité

Le capteur de proximité vous indique quand quelque chose recouvre le haut de l'écran, généralement l'oreille de l'utilisateur pendant une conversation téléphonique.

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();

Sur iOS, cela déclenche UIDevice.isProximityMonitoringEnabledqui éteint l'écran pendant que cela est recouvert. Sur Android, le plugin écoute le capteur de proximité et diminue la fenêtre de l'application. Activez-l’uniquement pendant une conversation téléphonique, un message vocal ou un mode walkie-talkie, afin que la joue de l'utilisateur ne presse pas les boutons.

Règles pratiques pour les applications de capteurs

1. Vérifiez la disponibilité en premier lieu. Tablets often lack a step counter or barometer, and emulators fake most sensors. Hide features you cannot support.
2. Arrêtez les mises à jour lorsqu'il n'est pas visible. Utilisez @capacitor/app's appStateChange pour arrêter les écouteurs lorsque l'application passe en arrière-plan et les redémarrer à la reprise. Les capteurs laissés en marche drainent la batterie et provoquent des critiques de 1 étoile.
3. Limitez en natif code lorsque le plugin le permet (boussole minInterval, capteur de lumière updateInterval), pas en JavaScript.
4. Demandez la permission dans le contexte. Demandez l'accès à la mouvement lorsque l'utilisateur commence un entraînement, pas lors du premier démarrage.
5. Testez sur des matériel réel. Les simulateurs retournent des valeurs constantes ou synthétiques. Testez au moins un téléphone Android de budget, où les capteurs manquent ou sont bruyants.
6. Respectez les règles de confidentialité. Motion and location data count as sensitive in App Store privacy labels and the Play data safety form. Declare what you collect.

Troubleshooting

Aucun événement sur iOSla chaîne d'utilisation manque Info.plistVérifiez les paramètres, la vie privée et la sécurité, le mouvement et la forme physique.

: la chaîne d'utilisation manque dans: ACTIVITY_RECOGNITION n'a pas été autorisé, ou le dispositif n'a pas de compteur d'étapes. Vérifiez isAvailable().stepCounting.

Le pédomètre retourne 0 sur Android: le consentement a été refusé ou le dispositif n'a pas de compteur d'étapes. Vérifiez

relativeAltitude est toujours 0: attendu sur Android. Calculez-l’à partir de la pression comme indiqué ci-dessus.

DeviceMotionEvent.requestPermission lance: il n'a pas été appelé à partir d'un geste utilisateur.

Rapports de consommation de batterie: les écouteurs restent en cours d'exécution en arrière-plan. Arrêtez-les sur appStateChange.

Expédiez rapidement les fonctionnalités de capteurs

Les seuils, les facteurs de lissage et l'interface utilisateur pour les fonctionnalités de capteurs nécessitent généralement plusieurs tours de réglage avec des utilisateurs réels. Cette logique se trouve dans JavaScript, vous pouvez donc l'ajuster avec Capgo mises à jour en direct sans passer par une revue de magasin, tandis que de nouveaux plugins et des chaînes de permissions passent par une construction régulière. Si vous connectez des capteurs externes comme des bandes de poitrine, continuez avec notre guide pour construire un moniteur de fréquence cardiaque avec Capacitor.