시작하기

호환성

@capgo/capacitor-device-info Capacitor 8 이상 필요 (@capacitor/core >=8.0.0).

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-device-info` plugin in my project.

수동 설정의 경우, 패키지를 설치하고 네이티브 프로젝트를 동기화하세요:

npm install @capgo/capacitor-device-info
npx cap sync

가져오기

import { DeviceInfo } from '@capgo/capacitor-device-info';

빠른 시작

import { DeviceInfo } from '@capgo/capacitor-device-info';

const result = await DeviceInfo.getInfo();
console.log(result);

예시: startMonitoring

import { DeviceInfo } from '@capgo/capacitor-device-info';

const result = await DeviceInfo.startMonitoring();
console.log(result);

예시: stopMonitoring

import { DeviceInfo } from '@capgo/capacitor-device-info';

const result = await DeviceInfo.stopMonitoring();
console.log(result);

자주 하는 실수

• 리스너: 화면이 언마운트될 때 핸들을 제거합니다.
• 네이티브 동기화: 실행 npx cap sync 플러그인 업그레이드 후.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

스냅샷 1개 읽기

const snapshot = await DeviceInfo.getInfo();

console.log(snapshot.cpu.cores);
console.log(snapshot.memory.usedPercent);
console.log(snapshot.storage.freeBytes);
console.log(snapshot.sensors?.pressureHpa);

cpu.usagePercent 델타 기반입니다. 첫 번째 네이티브 샘플에서는 이 값이 생략될 수 있으니, getInfo() 나중에 다시 호출하거나 모니터링을 통해 두 번째 샘플 이후 CPU 사용량이 채워진 값을 받으세요.

업데이트 스트림

const handle = await DeviceInfo.addListener('deviceInfoUpdate', (sample) => {
  console.log(sample.sequence, sample.elapsedMs);
  console.log(sample.cpu.usagePercent);
  console.log(sample.sensors?.readings);
});

const session = await DeviceInfo.startMonitoring({
  intervalMs: 1000,
  emitImmediately: true,
});

console.log(session.intervalMs, session.startedAt);

모니터링 동작

• intervalMs 기본값은 1000 밀리초입니다. 이보다 낮은 값은 250 밀리초로 제한됩니다. 250.
• emitImmediately 기본값은 true.
• 설정 durationMs 또는 sampleCount 자동으로 모니터링을 중단하려면.
• 호출 시 startMonitoring() 모니터링이 활성화된 상태에서 호출하면 새로운 옵션으로 세션이 재시작됩니다.
• 모든 deviceInfoUpdate 1부터 시작하는 sequence, 세션의 startedAt 타임스탬프, 그리고 elapsedMs.

업데이트 중단 및 리스너 제거

await DeviceInfo.stopMonitoring();
await handle.remove();

// Or remove every listener registered on this plugin:
await DeviceInfo.removeAllListeners();

모니터링 상태 확인

const state = await DeviceInfo.isMonitoring();

if (state.monitoring) {
  console.log(state.samplesEmitted);
}

센서 필드 온보딩

const { sensors, cpu, gpu } = await DeviceInfo.getInfo();

console.log(cpu.temperatureCelsius);
console.log(gpu?.temperatureCelsius);
console.log(sensors?.batteryTemperatureCelsius);
console.log(sensors?.ambientTemperatureCelsius);
console.log(sensors?.relativeHumidityPercent);
console.log(sensors?.pressureHpa);
console.log(sensors?.illuminanceLux);
console.log(sensors?.proximityDistanceCm);
console.log(sensors?.availableSensors);

센서 필드는 선택 사항입니다. 기기, OS 및 앱 샌드박스에서 해당 메트릭을 제공하는 경우에만 표시됩니다.

플랫폼 참고 사항

• iOS는 노출된 메트릭에 대해 별도의 권한이 필요하지 않습니다. CoreMotion 센서 가용성은 보고하지만, CPU 또는 GPU의 원시 온도는 보고하지 않습니다.
• Android는 노출된 메트릭에 대해 별도의 권한이 필요하지 않습니다. CPU 및 GPU 온도는 thermal-zone에서 best-effort로 읽어옵니다.
• 웹 지원은 best effort이며, 브라우저가 네이티브 디바이스 센서를 일관되게 노출하지 않기 때문에 빈 온보드 센서 배열을 보고합니다.

API 레퍼런스

메서드	반환값	참고 사항
getInfo()	Promise<DeviceInfoSnapshot>	스냅샷을 한 번 가져옵니다.
startMonitoring(options?)	Promise<StartMonitoringResult>	주기적인 스냅샷을 시작하거나, 새로운 옵션으로 활성 세션을 재시작합니다.
stopMonitoring()	Promise<StopMonitoringResult>	활성 세션을 중지합니다.
isMonitoring()	Promise<MonitoringState>	현재 세션 상태를 반환합니다.
addListener('deviceInfoUpdate', listener)	Promise<PluginListenerHandle>	주기적 스냅샷 리스너를 등록합니다.
removeAllListeners()	Promise<void>	플러그인에 등록된 모든 리스너를 제거합니다.
getPluginVersion()	Promise<PluginVersionResult>	네이티브 플러그인 버전을 읽습니다.

PluginListenerHandle Capacitor에서 제공되며 remove() 해당 개별 리스너를 제거하는 데 사용됩니다.

스냅샷 유형

interface CpuInfo {
  cores: number;
  activeCores?: number;
  architecture?: string;
  model?: string;
  usagePercent?: number | null;
  maxFrequencyHz?: number;
  temperatureCelsius?: number;
}

interface MemoryInfo {
  totalBytes?: number;
  freeBytes?: number;
  usedBytes?: number;
  usedPercent?: number;
  appUsedBytes?: number;
  appLimitBytes?: number;
  lowMemory?: boolean;
  pressure?: 'normal' | 'warning' | 'critical' | 'unknown';
}

interface StorageInfo {
  totalBytes?: number;
  freeBytes?: number;
  usedBytes?: number;
  usedPercent?: number;
}

interface GpuInfo {
  api?: 'metal' | 'opengl' | 'webgl' | 'unknown';
  vendor?: string;
  renderer?: string;
  version?: string;
  maxTextureSize?: number;
  temperatureCelsius?: number;
}

type ThermalState = 'nominal' | 'fair' | 'serious' | 'critical' | 'unknown';

interface DeviceInfoSnapshot {
  timestamp: number;
  platform: 'ios' | 'android' | 'web';
  cpu: CpuInfo;
  memory: MemoryInfo;
  storage: StorageInfo;
  gpu?: GpuInfo;
  thermalState?: ThermalState;
  lowPowerMode?: boolean;
  sensors?: OnboardSensorsInfo;
}

크기는 바이트 단위이며, maxFrequencyHz 주파수는 헤르츠, 온도 값은 섭씨 단위입니다. usagePercent 가능합니다 null 플랫폼이 이를 계산할 수 있을 만큼 충분한 샘플을 확보할 때까지.

센서 유형

interface OnboardSensorDescriptor {
  type: string;
  name?: string;
  vendor?: string;
  platformType?: number;
  maximumRange?: number;
  resolution?: number;
  powerMilliamp?: number;
  minDelayMicroseconds?: number;
  wakeUp?: boolean;
}

interface OnboardSensorReading {
  type: string;
  unit: string;
  value: number;
  name?: string;
  timestamp?: number;
}

interface OnboardSensorsInfo {
  availableSensors?: OnboardSensorDescriptor[];
  readings?: OnboardSensorReading[];
  batteryTemperatureCelsius?: number;
  ambientTemperatureCelsius?: number;
  relativeHumidityPercent?: number;
  pressureHpa?: number;
  illuminanceLux?: number;
  proximityDistanceCm?: number;
}

센서 판독값 타임스탬프는 Unix epoch 기준 밀리초입니다. 일반적인 단위는 섭씨, 퍼센트, hPa, lux, 센티미터입니다.

모니터링 유형

interface MonitoringOptions {
  intervalMs?: number;
  durationMs?: number;
  sampleCount?: number;
  emitImmediately?: boolean;
}

interface StartMonitoringResult {
  monitoring: boolean;
  intervalMs: number;
  startedAt: number;
}

interface StopMonitoringResult {
  monitoring: boolean;
}

interface MonitoringState {
  monitoring: boolean;
  intervalMs?: number;
  startedAt?: number;
  samplesEmitted?: number;
}

interface DeviceInfoUpdate extends DeviceInfoSnapshot {
  sequence: number;
  startedAt: number;
  elapsedMs: number;
}

interface PluginVersionResult {
  version: string;
}

startedAt, timestamp, 그리고 elapsedMs 밀리초입니다. sequence 시작 시점 1 각 모니터링 세션마다.

신뢰할 수 있는 소스

이 레퍼런스는 플러그인의 공개 API를 따릅니다. src/definitions.ts. 해당 소스가 변경되면 이 페이지를 업데이트하세요.

시작하기 다음 단계

사용 중이라면 시작하기 기기 진단을 위해 다음과 연결하세요 @capgo/capacitor-device-info 개요는, @capgo/capacitor-device-info 사용하기 튜토리얼 페이지는 @capgo/capacitor-barometer 집중적인 압력 측정을 위해, 그리고 @capgo/capacitor-light-sensor 조도 센서 측정값에 집중하기 위해.