Panduan Sensor Perangkat Capacitor: Gerakan, Kompas, Langkah

Sensor perangkat Capacitor tersedia lewat plugin kecil yang spesifik: @capgo/capacitor-accelerometer untuk gerakan, @capgo/capacitor-barometer untuk tekanan udara, @capgo/capacitor-compass untuk heading, @capgo/capacitor-pedometer untuk plugin light, proximity, dan shake. Semuanya mengikuti pola yang sama: cek ketersediaan, minta izin jika perlu, mulai update, listen, dan stop setelah selesai. Panduan ini membahas setiap sensor dengan Capacitor 8 code, perbedaan platform yang penting, serta aturan baterai agar aplikasi tetap aman.

Ringkasan Sensor

Instal hanya yang Anda pakai. Setiap plugin kecil, dan makin sedikit string izin berarti makin sedikit pertanyaan di App Review.

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

Setup iOS

Tambahkan usage string yang dibutuhkan sensor Anda ke 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>

Jelaskan manfaat bagi pengguna dengan bahasa yang jelas. Teks generik seperti “Aplikasi ini butuh akses gerakan” sering menjadi alasan penolakan App Review.

Setup Android

Sebagian besar sensor tidak butuh izin. Plugin pedometer menambahkan ACTIVITY_RECOGNITION ke manifest gabungan, dan Anda memintanya saat runtime di Android 10+.

Jika sensor bersifat esensial, deklarasikan fitur hardware agar Google Play menyembunyikan aplikasi Anda dari perangkat tanpa fitur tersebut. Jika opsional, deklarasikan dengan required="false" dan cek ketersediaannya saat runtime:

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

Akselerometer: gerakan dan kemiringan

Akselerometer melaporkan akselerasi pada sumbu x, y, dan z dalam satuan G. Ponsel yang diletakkan datar akan membaca sekitar z = -1 atau 1 tergantung konvensi platform, karena gravitasi ikut terhitung.

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 case: kontrol kemiringan di game, UI “lift to wake”, deteksi jatuh atau benturan, intensitas aktivitas. Data mentah itu noisy, jadi haluskan dengan low-pass filter sebelum dipakai:

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

Jangan update DOM di setiap sampel. Simpan nilai terbaru dan render dalam requestAnimationFrame loop.

Gesture shake

Untuk fitur “shake to report a bug” atau “shake to undo”, Anda tidak perlu mengatur threshold secara manual:

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

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

Gyroscope dan orientasi perangkat

Tidak perlu plugin terpisah untuk rotasi. WebView sudah menyediakannya:

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

Panggil requestPermission dari ketukan tombol, jangan saat page load, atau iOS akan menolak permintaan tersebut.

Kompas: arah mata angin

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 adalah derajat dari utara magnetik, 0 hingga 360. Hal yang perlu diketahui:

• Magnetometer dapat terganggu oleh magnet pada casing ponsel, laptop, atau dudukan mobil. Tampilkan petunjuk kalibrasi (gerakkan ponsel membentuk angka delapan) saat Android melaporkan akurasi rendah.
• Throttle dengan minInterval dan minHeadingChange daripada di JavaScript. Ini menghemat traffic bridge.
• Untuk peta yang berputar mengikuti pengguna, gabungkan heading dengan geolocation. Jika Anda butuh lokasi saat aplikasi berjalan di background, lihat plugin background geolocation.

Pedometer: langkah, jarak, dan lantai

Step counter adalah chip hemat daya yang menghitung terus-menerus, bahkan saat aplikasi Anda tidak sedang berjalan.

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

Perbedaan Platform:

• iOS (Core Motion) menjawab query historis untuk sekitar tujuh hari terakhir serta menyediakan data jarak, lantai, pace, dan cadence pada perangkat yang mendukung.
• Android hanya melaporkan langkah. Counter hardware akan reset saat reboot, jadi jangan anggap ini total seumur hidup. Simpan baseline Anda sendiri.

Untuk riwayat jangka panjang, total harian antar perangkat, atau data dari smartwatch, bacalah dari health store menggunakan @capgo/capacitor-health instead. It aggregates steps from all sources in Apple Health and Health Connect. Our panduan migrasi Health Connect menjelaskan cara setup-nya.

Barometer: tekanan dan ketinggian

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 dalam satuan hectopascals di kedua platform. relativeAltitude adalah perubahan dalam meter sejak update dimulai, hanya tersedia di iOS. Di Android nilainya selalu 0, jadi hitung sendiri menggunakan formula barometrik:

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

Ketinggian absolut dari tekanan bisa meleset puluhan meter karena perubahan tekanan laut akibat cuaca. Perubahan relatif dalam hitungan menit akurat hingga sekitar satu meter, cukup untuk menghitung lantai atau tanjakan. Banyak HP Android murah tidak punya barometer, jadi selalu cek isAvailable.

Sensor cahaya sekitar (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 });
}

Nilai tipikal: di bawah 10 lux adalah ruangan gelap, beberapa ratus lux adalah kantor, puluhan ribu adalah sinar matahari langsung. Gunakan untuk mode baca yang adaptif terhadap ruangan, atau menaikkan kontras di luar ruangan. Untuk mengubah kecerahan layar, pasangkan dengan @capgo/capacitor-brightness.

Sensor Proximity

Sensor proximity memberi tahu Anda saat sesuatu menutupi bagian atas layar, biasanya telinga pengguna saat sedang menelepon.

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

Di iOS, ini akan mengaktifkan UIDevice.isProximityMonitoringEnabled, yang mematikan layar saat tertutup. Di Android, plugin ini memantau sensor proximity dan meredupkan jendela aplikasi. Aktifkan hanya saat panggilan suara, pesan suara, atau mode walkie-talkie aktif, agar pipi pengguna tidak menekan tombol secara tidak sengaja.

Aturan praktis untuk aplikasi sensor

1. Cek ketersediaan terlebih dahulu. Tablet sering kali tidak memiliki penghitung langkah atau barometer, dan emulator memalsukan sebagian besar sensor. Sembunyikan fitur yang tidak dapat Anda dukung.
2. Hentikan update saat tidak terlihat. Gunakan @capacitor/appmilik appStateChange untuk menghentikan listener saat aplikasi masuk ke background dan menjalankannya kembali saat resume. Sensor yang terus berjalan akan menguras baterai dan memicu ulasan bintang satu.
3. Gunakan throttle di native code jika plugin mengizinkannya (kompas minInterval, sensor cahaya updateInterval), bukan di JavaScript.
4. Tanya AI untuk konteks. Minta akses motion saat user mulai workout, bukan saat pertama kali buka aplikasi.
5. Tes di perangkat asli. Simulator hanya mengembalikan nilai konstan atau sintetis. Tes minimal satu HP Android murah, di mana sensor sering tidak ada atau tidak akurat.
6. Patuhi aturan privasi. Data motion dan lokasi dianggap sensitif pada label privasi App Store dan form data safety Play Store. Deklarasikan apa yang Anda kumpulkan.

Pemecahan Masalah

Tidak ada event di iOS: usage string tidak ditemukan di Info.plist, atau izin ditolak. Cek Settings, Privacy and Security, Motion and Fitness.

Pedometer mengembalikan nilai 0 di Android: ACTIVITY_RECOGNITION ditolak, atau perangkat tidak memiliki step counter. Cek isAvailable().stepCounting.

Kompas tidak stabil: gangguan magnetik atau belum dikalibrasi. Pantau akurasi di Android dan tampilkan petunjuk kalibrasi.

relativeAltitude selalu 0: diharapkan pada Android. Hitung dari tekanan seperti di atas.

DeviceMotionEvent.requestPermission melempar error: tidak dipanggil melalui gesture pengguna.

Laporan battery drain: listener tetap berjalan di background. Hentikan pada appStateChange.

Rilis fitur sensor dengan cepat

Threshold, faktor smoothing, dan UI untuk fitur sensor biasanya butuh beberapa kali tuning dengan pengguna nyata. Logika itu ada di JavaScript, jadi Anda bisa menyesuaikannya dengan Live updates Capgo tanpa review store, sementara plugin dan permission string baru melalui build reguler. Jika Anda menghubungkan sensor eksternal seperti chest strap, lanjutkan dengan panduan kami untuk membangun monitor detak jantung dengan Capacitor.