Capacitor 기기 센서 가이드: 운동, 지평선, 단계

Capacitor 기기 센서는 작은, 집중된 플러그인으로 사용할 수 있습니다: @capgo/capacitor-accelerometer 운동에 대한 @capgo/capacitor-barometer 공기 압력에 대한 @capgo/capacitor-compass heading @capgo/capacitor-pedometer for steps, plus light, proximity and shake plugins. Each follows the same pattern: check availability, request permission if needed, start updates, listen, and stop when you are done. This guide covers every sensor with Capacitor 8 code, the platform differences that matter, and the battery rules that keep apps out of trouble.

센서 개요

사용하지 않는 플러그인을 설치하지 마세요. 각 플러그인은 작고, 권한 문자열이 적으면 앱 리뷰에서 더 적은 질문이 생깁니다.

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

iOS 설정

사용자에게 필요한 센서의 권한 문자열을 추가하세요. 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>

사용자에게 이익을 설명하세요. 일반적인 텍스트인 “이 앱은 운동 접근이 필요합니다.”는 자주 앱 리뷰에서 거절되는 이유입니다.

안드로이드 설정

대부분의 센서는 권한이 필요하지 않습니다.歩数 센서 플러그인은 ACTIVITY_RECOGNITION Android 10 이상에서 런타임에 요청합니다.

센서가 필수적이라면 Google Play에서 장치가 해당 센서를 지원하지 않으면 앱을 숨깁니다. 센서가 선택적이라면 required="false" 런타임에 사용 가능 여부를 확인하세요:

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

가속도계: 운동 및 기울기

가속도계는 x, y, z 축의 가속도 값을 G 단위로 보고합니다. 평평하게 놓인 전화기는 약 z = -1 또는 1 플랫폼의 규칙에 따라, 중력은 포함됩니다.

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

사용 사례: 게임에서 기울기 제어, “lift to wake” UI, 충돌 또는 충격 감지, 활동 강도. raw 데이터는 노이즈가 많기 때문에 low-pass 필터를 사용하여 데이터를 평활화하세요.

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

DOM을 매 샘플마다 업데이트하지 마세요. 최신 값을 저장하고 루프에서 렌더링하세요. requestAnimationFrame 반짝이 동작

‘shake to report a bug’ 또는 ‘shake to undo’와 같은 경우에는 스스로 임계값을 조정할 필요가 없습니다:

Android 10 이상에서 런타임에 요청합니다.

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

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

자이로스코프 및 장치 방향

회전에 대한 별도의 플러그인은 필요하지 않습니다. WebView는 이미 노출하고 있습니다:

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

호출 requestPermission 버튼 탭에서, 페이지 로드 시, 또는 iOS가 요청을 거부합니다.

자이로스코프: 방향

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 0에서 360도까지磁北쪽에서 각도입니다. 알아야 할 점:

• 자이로스코프는 전화 케이스, 노트북 및 자동차 모니터에 있는 자석에 의해 방해를 받습니다. Android가 정확도가 낮다고 보고할 때, 전화의 움직임을 8자 모양으로 이동하는 캘리브레이션 힌트를 표시하세요.
• 가속도계와 minInterval 그리고 minHeadingChange JavaScript에서 대신 사용합니다. 이로 인해 브리지 트래픽이 절약됩니다.
• 사용자가 회전하는 맵을 만들려면, 방향과 위치 정보를 combine하세요. 앱이 백그라운드에서 위치 정보가 필요하다면, 백그라운드 위치 정보 플러그인.

步수計: 걸음 수, 거리 및 층수

단말기가 작동하지 않아도 항상 연속적으로 카운트하는 저전력 칩입니다.

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

플랫폼 차이:

• iOS (Core Motion) 지원되는 장치에서 7일 이내의 역사적 쿼리와 거리, 층수, 속도 및 발동을 제공합니다.
• Android 단말기가 재부팅되면 하드웨어 카운터가 초기화되므로 수명 총계로 다루지 마십시오. 자신의 기준점을 저장하십시오.

장기적인 기록, 일일 총계, 장치 간 데이터 또는腕시계 데이터를 읽으려면 @capgo/capacitor-health 대신 사용하십시오. 이는 Apple Health와 Health Connect에서 모든 소스에서 걸음 수를 집계합니다. Health Connect 마이그레이션 가이드 설정을 설명합니다.

바로미터: 압력 및 고도

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 both platforms에서 hectopascals 단위로 표시됩니다. relativeAltitude iOS에서만 제공되는 업데이트가 시작된 후에 since의 변화는 meter 단위입니다. Android에서는 항상 0, 따라서 바로메트릭 공식으로 계산하세요:

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

기압에서 절대 고도는 기상 변화로 인해 수십 미터 차이가 나므로, 상대적인 변화를 분 단위로 계산하면 약 1미터의 정확도를 얻을 수 있습니다. 이는 층수나 등산을 계산할 때 충분합니다. 많은 저가 안드로이드폰에는 바로메터가 없으므로 항상 isAvailable.

주변 조도 센서 (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 });
}

일반적인 값: 10lux 이하는 어두운 방, 수백 lux는 사무실, 수십 만 lux는 직사광선입니다. 사용자는 방에 따라 읽기 모드를 조정하거나, 야외에서는 대비를 높일 수 있습니다. 화면 밝기를 직접 변경하려면 @capgo/capacitor-brightness.

근접 센서

근접 센서가 화면 상단을 가리는 것을 알려줍니다. 일반적으로 사용자는 통화 중에耳을 화면 위에 대는 경우입니다.

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

iOS에서는 UIDevice.isProximityMonitoringEnabled, 화면을 가리면 화면을 끄는 기능을 켭니다. Android에서는 근접 센서를 감지하여 앱 창의 밝기를 줄입니다. 통화, 음성 메시지, walkie-talkie 모드가 활성화된 경우에만 활성화하세요. 사용자의 볼을 눌러 버튼을 누르지 않도록 하세요.

센서 앱의 실용적인 규칙

1. 사용 가능 여부를 먼저 확인하세요. 태블릿은 일반적으로 단계 센서나 바로미터를 지원하지 않으며, 에뮬레이터는 대부분의 센서를 가짜로 만듭니다. 지원하지 않는 기능을 숨기세요.
2. 비활성화된 상태에서 업데이트를 중지하세요. 사용 @capacitor/app의 appStateChange 앱이 백그라운드에 가면 리스너를 중지하고 다시 시작하세요. 센서를 계속 실행하면 배터리가 소모되고 1점 리뷰가 발생합니다.
3. native code를 사용할 때 플러그인이 허용하는 경우 가속기 권한을 요청하세요. minIntervalcontext: Capgo 마케팅 웹사이트. 역할: Call-to-action 버튼이나 링크 레이블. Seen in: component AskAiSection.astro. Message key `ask_ai_button` (Ask Ai Button). updateInterval운동을 시작할 때 사용자가 운동 앱을 시작할 때만 운동 센서 접근을 요청하세요.
4. 실제 하드웨어에서 테스트하세요. 업데이트를 중지하세요.
5. 사용하세요. Simulator는 일정한 또는 가상의 값을 반환합니다. 최소한 한대의 저렴한 안드로이드폰을 테스트하여 센서가 누락되거나 잡음이 발생하는지 확인하세요.
6. 개인 정보 보호 규칙을 준수하세요. 운동 및 위치 데이터는 앱 스토어 개인 정보 레이블 및 플레이 데이터 안전 양식에서敏感한 데이터로 간주됩니다. 수집하는 데이터를 선언하세요.

문제 해결

컨텍스트: 지원 / 프리미엄 지원 페이지 또는 푸터 지원 섹션. 역할: 섹션 또는 페이지 제목. 보이는 곳: 페이지 support-policy.astro. 메시지 키 `support_policy_troubleshooting_title` (지원 정책 문제 해결 제목).iOS에서 이벤트가 없습니다. Info.plist: 사용 문자열이 누락되거나

또는 권한이 거부되었습니다. 설정, 개인 정보 보호 및 보안, 운동 및 건강을 확인하세요.: ACTIVITY_RECOGNITION 안드로이드에서 페이스 메터는 0을 반환합니다. isAvailable().stepCounting.

권한이 거부되거나 장치가 스텝 카운터가 없는 경우 확인하세요.자이روس콥스(Compass)는 흔들립니다.

relativeAltitude 0은 항상 0입니다.: Android에서 예상되는 압력을 계산하세요.

DeviceMotionEvent.requestPermission throws: 사용자 동작이 없으면 호출되지 않았습니다.

배터리 소모 보고서: 리스너가 배경에서 계속 실행됩니다. appStateChange.

: 센서 기능을 빠르게 배포하세요.

센서 기능의 임계값, smoothing factor 및 UI는 일반적으로 실제 사용자와의 여러 반복적인 조정을 통해 튜닝됩니다. 이 논리는 자바스크립트에서 실행되므로, Capgo 실시간 업데이트 context Capacitor.