Per iniziare

Compatibilità

@capgo/capacitor-device-info richiede Capacitor 8 o superiore (@capacitor/core >=8.0.0).

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Per una configurazione manuale, installa il pacchetto e sincronizza i progetti nativi:

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

Importa

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

Avvio rapido

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

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

Esempio: startMonitoring

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

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

Esempio: stopMonitoring

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

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

Errori comuni

• Listener: rimuovi gli handle quando gli schermi vengono smontati.
• Sync nativo: esegui npx cap sync dopo gli aggiornamenti dei plugin.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Leggi uno snapshot

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 si basa sui delta. Il primo campione nativo può ometterlo; richiama getInfo() in seguito o usa il monitoraggio per ricevere l'uso della CPU dopo il secondo campione.

Stream degli aggiornamenti

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

Comportamento del monitoraggio

• intervalMs ha come default 1000 millisecondi. I valori inferiori a 250 millisecondi vengono limitati a 250.
• emitImmediately ha come default true.
• Imposta durationMs o sampleCount per interrompere il monitoraggio automatico.
• In chiamata startMonitoring() mentre il monitoraggio è attivo, riavvia la sessione con le nuove opzioni.
• Ogni deviceInfoUpdate include un valore basato su sequence, la sessione startedAt timestamp e elapsedMs.

Ferma gli update e rimuovi i listener

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

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

Controlla lo stato del monitoraggio

const state = await DeviceInfo.isMonitoring();

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

Onboarding dei campi del sensore

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

I campi sensore sono opzionali. Sono presenti solo se il dispositivo, l'OS e l'app sandbox espongono tale metrica.

Note sulla piattaforma

• iOS non richiede permessi per le metriche esposte. Riporta la disponibilità dei sensori CoreMotion, ma non la temperatura grezza di CPU o GPU.
• Android non richiede permessi per le metriche esposte. Le temperature di CPU e GPU sono rilevate tramite letture delle zone termiche "best-effort".
• Il supporto web è best effort e restituisce array vuoti per i sensori onboard, perché i browser non espongono i sensori nativi del dispositivo in modo coerente.

riferimento API

Metodo	Restituisce	Note
getInfo()	Promise<DeviceInfoSnapshot>	Legge un singolo snapshot.
startMonitoring(options?)	Promise<StartMonitoringResult>	Avvia snapshot periodici o riavvia una sessione attiva con nuove opzioni.
stopMonitoring()	Promise<StopMonitoringResult>	Interrompe la sessione attiva.
isMonitoring()	Promise<MonitoringState>	Restituisce lo stato della sessione corrente.
addListener('deviceInfoUpdate', listener)	Promise<PluginListenerHandle>	Registra un listener per gli snapshot periodici.
removeAllListeners()	Promise<void>	Rimuove tutti i listener registrati sul plugin.
getPluginVersion()	Promise<PluginVersionResult>	Legge la versione del plugin nativo.

PluginListenerHandle è fornito da Capacitor e ha remove() per rimuovere quel singolo listener.

Tipi di snapshot

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

Le dimensioni sono in byte, maxFrequencyHz è in hertz e i valori della temperatura sono in Celsius. usagePercent può essere null finché la piattaforma non ha abbastanza campioni per calcolarlo.

Tipi di sensori

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

I timestamp delle letture dei sensori sono in millisecondi Unix epoch. Le unità comuni sono Celsius, percentuali, hPa, lux e centimetri.

Tipi di monitoraggio

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, e elapsedMs sono millisecondi. sequence inizia a 1 per ogni sessione di monitoraggio.

Fonte di verità

Questo riferimento segue la API pubblica nel src/definitions.tsAggiorna questa pagina se la sorgente cambia.

Continua da Getting Started

Se stai usando Per iniziare per la diagnostica del dispositivo, connettilo a @capgo/capacitor-device-info per la panoramica, Usando @capgo/capacitor-device-info per la pagina del tutorial, @capgo/capacitor-barometer per letture di pressione mirate, e @capgo/capacitor-light-sensor per letture mirate del sensore di luce.