Battery API

Battery API in JavaScript: Monitoraggio dello Stato della Batteria del Dispositivo

La Battery API in JavaScript è un'interfaccia che consente alle pagine web di leggere lo stato della batteria di un dispositivo: il livello di carica, se è in carica e quanto tempo manca prima che sia piena o scarica. Con queste informazioni, un'applicazione web può adattare il proprio comportamento — ad esempio, rallentare le operazioni in background o ridurre le animazioni pesanti quando il dispositivo ha poca carica. Questo articolo spiega cos'è la Battery API, i dati che espone, quando vale la pena utilizzarla e come leggerla correttamente con promise ed eventi.

Nota: Poiché il livello della batteria è un forte segnale di fingerprinting (è un numero quasi univoco che cambia lentamente), i browser hanno ridotto il supporto alla Battery API. È stata rimossa da Firefox e Safari, e navigator.getBattery() è disponibile solo nei browser basati su Chromium (Chrome, Edge, Opera) in un contesto sicuro (HTTPS). Trattala come un miglioramento progressivo e individua sempre la funzionalità prima di chiamarla — il codice deve funzionare anche quando l'API non è disponibile.

Cos'è la Battery API?

La Battery API è esposta tramite un unico metodo, navigator.getBattery(), che restituisce una Promise che si risolve in un oggetto BatteryManager. Quell'oggetto contiene quattro proprietà di sola lettura che descrivono lo stato corrente, più quattro eventi che si attivano ogni volta che uno di questi valori cambia. Poiché getBattery() è asincrono, lo si legge con .then() o con async/await.

Proprietà di BatteryManager

Eventi di BatteryManager

Ogni evento è un semplice evento DOM, quindi ci si iscrive con addEventListener sul BatteryManager.

Vantaggi della Battery API

• Miglioramento dell'esperienza utente: Accedendo alle informazioni sullo stato della batteria, le applicazioni web possono adattare il proprio comportamento per risparmiare energia quando il dispositivo funziona a batteria o offrire funzionalità avanzate quando è collegato alla corrente.
• Efficienza energetica: Utilizzando le informazioni sullo stato della batteria, le app web possono ottimizzare le operazioni intensive in termini di risorse per ridurre il consumo energetico e prolungare la durata della batteria del dispositivo.
• Aggiornamenti in tempo reale: L'API fornisce aggiornamenti in tempo reale sui cambiamenti dello stato della batteria, consentendo alle app web di rispondere immediatamente a eventi come lo scollegamento del dispositivo o livelli di batteria bassi.
• Supporto dei browser: La Battery API è disponibile in diversi browser moderni, anche se gli sviluppatori dovrebbero implementare il rilevamento delle funzionalità per garantire la compatibilità nei diversi ambienti.

Quando utilizzare la Battery API

Considera l'utilizzo della Battery API quando la tua applicazione web deve:

1. Fornire funzionalità consapevoli dell'alimentazione: Adattare le funzionalità e il comportamento dell'applicazione in base al fatto che il dispositivo stia funzionando a batteria, sia in carica o completamente carico.
2. Preservare la durata della batteria: Ottimizzare le operazioni intensive di risorse quando il dispositivo funziona a batteria per ridurre il consumo energetico e prolungare la durata della batteria.
3. Visualizzare lo stato della batteria: Mostrare agli utenti informazioni relative alla batteria, come il livello di carica corrente o il tempo stimato prima che la batteria sia completamente carica.
4. Attivare azioni sugli eventi della batteria: Eseguire azioni specifiche quando lo stato della batteria cambia, ad esempio visualizzare un avviso di batteria scarica o mettere in pausa operazioni intensive di risorse.

Casi d'uso pratici

1. Avviso di batteria scarica: È possibile utilizzare la Battery API per attivare un avviso di batteria scarica quando il livello della batteria del dispositivo scende al di sotto di una certa soglia, sollecitando gli utenti a risparmiare energia o collegare il dispositivo.
2. Animazioni a basso consumo energetico: Le applicazioni web possono regolare l'intensità e la frequenza delle animazioni in base allo stato della batteria del dispositivo per ridurre il consumo della batteria.
3. Gestione dei processi in background: Ottimizzare i processi in background, come la sincronizzazione dei dati o l'invio di notifiche, in modo che avvengano meno frequentemente quando il dispositivo funziona a batteria per risparmiare energia.
4. Caricamento dinamico delle risorse: Caricare immagini ad alta risoluzione o contenuti intensivi di risorse solo quando il dispositivo è in carica o quando il livello della batteria è superiore a una certa soglia, migliorando le prestazioni e l'efficienza energetica.

Rilevamento delle funzionalità

Non assumere mai che getBattery() esista. Proteggi ogni chiamata in modo che i browser non supportati gestiscano il fallback correttamente invece di generare un TypeError:

async function readBattery() {
  if (!('getBattery' in navigator)) {
    return 'Battery API not supported';
  }

  const battery = await navigator.getBattery();
  const percent = Math.round(battery.level * 100);
  return `${percent}% — ${battery.charging ? 'charging' : 'on battery'}`;
}

'getBattery' in navigator è il controllo canonico: è true solo dove l'API è presente. La forma async/await legge il BatteryManager risolto esattamente come la forma .then() ma scorre dall'alto verso il basso.

Esempio di base: Monitoraggio dello stato della batteria

L'esempio seguente legge la batteria una volta e poi mantiene il testo a schermo sincronizzato ascoltando gli eventi pertinenti. Si noti il helper toHours — chargingTime e dischargingTime sono riportati in secondi, quindi dividendo per 3600 si ottengono ore leggibili. Entrambi i valori possono essere Infinity, quindi gestiamo quel caso esplicitamente.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Battery Time Estimation</title>
</head>
<body>
    <h1>Battery Time Estimation</h1>
    <div>Time Remaining: <span id="timeRemaining">Calculating...</span></div>

    <script>
    if ('getBattery' in navigator) {
        navigator.getBattery().then(function(battery) {
            const output = document.getElementById('timeRemaining');

            function toHours(seconds) {
                return (seconds / 3600).toFixed(1);
            }

            function updateTimeRemaining() {
                if (battery.charging) {
                    if (battery.chargingTime === Infinity) {
                        output.textContent = 'Plugged in, charge time unknown';
                    } else {
                        output.textContent = `Charging, ${toHours(battery.chargingTime)} hours until full`;
                    }
                } else if (battery.dischargingTime === Infinity) {
                    output.textContent = 'On battery, time remaining unknown';
                } else {
                    output.textContent = `On battery, ${toHours(battery.dischargingTime)} hours remaining`;
                }
            }

            updateTimeRemaining();

            battery.addEventListener('chargingchange', updateTimeRemaining);
            battery.addEventListener('levelchange', updateTimeRemaining);
            battery.addEventListener('chargingtimechange', updateTimeRemaining);
            battery.addEventListener('dischargingtimechange', updateTimeRemaining);
        }).catch(function(error) {
            document.getElementById('timeRemaining').textContent = 'Battery API not available or access denied.';
            console.error('Battery API error:', error);
        });
    } else {
        document.getElementById('timeRemaining').textContent = 'Battery API not supported in this browser.';
    }
    </script>
</body>
</html>

Come funziona:

• Stima del tempo: Lo script verifica se la batteria è in carica o in scarica e visualizza un tempo stimato fino alla carica completa o all'esaurimento della batteria.
• Listener di eventi: Aggiorna la visualizzazione in tempo reale al variare dello stato della batteria.

Questo esempio aiuta a illustrare come la Battery API possa fornire informazioni dettagliate sull'utilizzo della batteria, incluse le stime temporali, il che può essere particolarmente utile per dispositivi mobili e laptop nella gestione del consumo energetico e nella pianificazione dell'utilizzo.

Reazione a una batteria scarica

Un pattern comune consiste nel passare la pagina in modalità "risparmio energetico" quando la carica scende al di sotto di una soglia mentre si funziona a batteria. Ascoltare levelchange e chargingchange insieme per rivalutare la modalità su entrambi i segnali:

async function watchPowerSaver(onChange) {
  if (!('getBattery' in navigator)) return;

  const battery = await navigator.getBattery();

  function evaluate() {
    // Save power only when on battery and below 20%.
    const lowPower = !battery.charging && battery.level < 0.2;
    onChange(lowPower);
  }

  evaluate();
  battery.addEventListener('levelchange', evaluate);
  battery.addEventListener('chargingchange', evaluate);
}

// Usage: pause heavy animations when low on power.
watchPowerSaver((lowPower) => {
  document.body.classList.toggle('reduce-motion', lowPower);
});

Questo è molto meno costoso che eseguire il polling con un timer: il callback viene eseguito solo quando lo stato della batteria cambia effettivamente.

Errori comuni

• Potrebbe non risolversi mai in dati utili. Su un desktop senza batteria, charging è true, level è 1, e entrambe le proprietà temporali sono 0 o Infinity. Non trattare l'API come un segnale affidabile di "su un laptop."
• Infinity è normale. chargingTime è Infinity ogni volta che il dispositivo non è in carica, e dischargingTime è Infinity ogni volta che il tempo non può essere stimato. Gestisci sempre questo caso prima di formattare il valore.
• Le stime sono approssimate e arrotondate. Per ridurre il fingerprinting, i browser arrotondano level e i valori temporali, quindi non costruire countdown precisi basandosi su di essi.
• È richiesto un contesto sicuro. getBattery() è disponibile solo su pagine HTTPS (e localhost). Su HTTP semplice è undefined, cosa che il controllo della funzionalità individua.
• Rimuovi i listener che non ti servono più. Se aggiungi listener all'interno di un componente, rimuovili con removeEventListener durante lo smontaggio per evitare perdite di memoria.

Conclusione

La Battery API in JavaScript fornisce agli sviluppatori web uno strumento per accedere e rispondere allo stato della batteria dei dispositivi degli utenti. Utilizzando questa API, le applicazioni web possono migliorare l'esperienza utente, preservare la durata della batteria e ottimizzare l'efficienza energetica. Sebbene il supporto dei browser vari a causa di considerazioni sulla privacy, la Battery API consente di creare esperienze consapevoli dell'alimentazione dove supportata — a condizione di rilevare la funzionalità, gestire i valori temporali Infinity e trattare i dati come un suggerimento approssimativo piuttosto che una garanzia.

Argomenti correlati

• Promises — getBattery() ne restituisce una.
• async / await — il modo più semplice per leggerla.
• Introduzione agli eventi del browser — come funzionano gli eventi di BatteryManager.
• Geolocation API — un'altra API di stato del dispositivo con pattern di autorizzazione e rilevamento delle funzionalità simili.

Esercitazione