Battery API

Battery API em JavaScript: Monitorando o Status da Bateria do Dispositivo

A Battery API em JavaScript é uma interface que permite que páginas web leiam o status da bateria de um dispositivo: qual é o nível de carga, se está carregando e quanto tempo falta para carregar ou descarregar completamente. Com essas informações, uma aplicação web pode adaptar seu comportamento — por exemplo, reduzindo tarefas em segundo plano ou diminuindo animações pesadas quando o dispositivo está com pouca bateria. Este artigo explica o que é a Battery API, quais dados ela expõe, quando vale a pena usá-la e como lê-la corretamente com promises e eventos.

Observação: Como o nível da bateria é um sinal forte de fingerprinting (é um número quase único que muda lentamente), os navegadores recuaram na Battery API. Ela foi removida do Firefox e do Safari, e navigator.getBattery() está disponível apenas em navegadores baseados em Chromium (Chrome, Edge, Opera) em um contexto seguro (HTTPS). Trate-a como uma melhoria progressiva e sempre faça a detecção de recursos antes de chamá-la — seu código deve funcionar mesmo quando a API não estiver disponível.

O que é a Battery API?

A Battery API é exposta por meio de um único método, navigator.getBattery(), que retorna uma Promise que resolve para um objeto BatteryManager. Esse objeto contém quatro propriedades somente leitura que descrevem o estado atual, além de quatro eventos que são disparados sempre que algum desses valores muda. Como getBattery() é assíncrono, você o lê com .then() ou com async/await.

Propriedades do BatteryManager

Eventos do BatteryManager

Cada evento é um evento DOM simples, portanto você se inscreve com addEventListener no BatteryManager.

Benefícios da Battery API

• Melhoria da Experiência do Usuário: Ao acessar informações sobre o status da bateria, as aplicações web podem adaptar seu comportamento para economizar energia quando o dispositivo está funcionando com bateria ou oferecer recursos aprimorados quando está conectado à tomada.
• Eficiência Energética: Usando as informações de status da bateria, as aplicações web podem otimizar operações que consomem muitos recursos para reduzir o consumo de energia e prolongar a vida útil da bateria.
• Atualizações em Tempo Real: A API fornece atualizações em tempo real sobre mudanças no status da bateria, permitindo que as aplicações web respondam imediatamente a eventos como desconectar o dispositivo ou níveis baixos de bateria.
• Suporte dos Navegadores: A Battery API está disponível em vários navegadores modernos, embora os desenvolvedores devam implementar a detecção de recursos para garantir compatibilidade em diferentes ambientes.

Quando Usar a Battery API

Considere usar a Battery API quando sua aplicação web precisar:

1. Oferecer Recursos Adaptados à Energia: Adaptar os recursos e o comportamento da sua aplicação com base em se o dispositivo está funcionando com bateria, carregando ou com a carga completa.
2. Conservar a Vida Útil da Bateria: Otimizar operações que consomem muitos recursos quando o dispositivo está funcionando com bateria para reduzir o consumo de energia e prolongar a vida útil da bateria.
3. Exibir o Status da Bateria: Mostrar informações relacionadas à bateria para os usuários, como o nível atual de carga ou o tempo estimado até que a bateria esteja completamente carregada.
4. Disparar Ações em Eventos de Bateria: Executar ações específicas quando o status da bateria muda, como exibir um aviso de bateria fraca ou pausar tarefas que consomem muitos recursos.

Casos de Uso Práticos

1. Alerta de Bateria Fraca: Você pode usar a Battery API para disparar um alerta de bateria fraca quando o nível da bateria do dispositivo cair abaixo de um determinado limite, incentivando os usuários a economizar energia ou conectar o dispositivo à tomada.
2. Animações com Eficiência Energética: As aplicações web podem ajustar a intensidade e a frequência das animações com base no status da bateria do dispositivo para reduzir o consumo de energia.
3. Gerenciamento de Processos em Segundo Plano: Otimize processos em segundo plano, como sincronização de dados ou envio de notificações, para ocorrer com menos frequência quando o dispositivo estiver funcionando com bateria e assim economizar energia.
4. Carregamento Dinâmico de Recursos: Carregue imagens em alta resolução ou conteúdo que consome muitos recursos apenas quando o dispositivo estiver carregando ou quando o nível da bateria estiver acima de um determinado limite, melhorando o desempenho e a eficiência energética.

Detecção de Recursos

Nunca presuma que getBattery() existe. Proteja cada chamada para que os navegadores sem suporte tenham um fallback adequado em vez de lançar um 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 é a verificação canônica: é true apenas onde a API está presente. A forma async/await lê o BatteryManager resolvido exatamente como a forma .then(), mas flui de cima para baixo.

Exemplo Básico: Monitorando o Status da Bateria

O exemplo abaixo lê a bateria uma vez e mantém o texto na tela atualizado ouvindo os eventos relevantes. Observe o auxiliar toHours — chargingTime e dischargingTime são reportados em segundos, portanto dividir por 3600 os converte em horas legíveis. Ambos os valores podem ser Infinity, então tratamos esse caso explicitamente.

<!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>

Como Funciona:

• Estimativa de Tempo: O script verifica se a bateria está carregando ou descarregando e exibe um tempo estimado até que a bateria esteja completamente carregada ou descarregada.
• Ouvintes de Evento: Atualiza a exibição em tempo real conforme o status da bateria muda.

Este exemplo ajuda a ilustrar como a Battery API pode fornecer informações detalhadas sobre o uso da bateria, incluindo estimativas de tempo, o que pode ser particularmente útil para dispositivos móveis e laptops no gerenciamento do consumo de energia e no planejamento de uso.

Reagindo a uma Bateria Fraca

Um padrão comum é colocar a página no modo "economia de energia" quando a carga cai abaixo de um limite enquanto está funcionando com bateria. Ouça levelchange e chargingchange juntos para reavaliação do modo em qualquer um dos sinais:

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

Isso é muito mais eficiente do que fazer polling com um temporizador: o callback é executado apenas quando o estado da bateria realmente muda.

Armadilhas Comuns

• Pode nunca resolver para dados úteis. Em um desktop sem bateria, charging é true, level é 1 e ambas as propriedades de tempo são 0 ou Infinity. Não trate a API como um sinal confiável de "está em um laptop."
• Infinity é normal. chargingTime é Infinity sempre que o dispositivo não está carregando, e dischargingTime é Infinity sempre que o tempo não pode ser estimado. Sempre verifique esse caso antes de formatar.
• As estimativas são grosseiras e limitadas. Para reduzir o fingerprinting, os navegadores arredondam level e os valores de tempo, portanto não construa contagens regressivas precisas com base neles.
• Contexto seguro obrigatório. getBattery() está disponível apenas em páginas HTTPS (e localhost). Em HTTP simples, é undefined, o que sua verificação de recursos detecta.
• Remova os ouvintes que não são mais necessários. Se você anexar ouvintes dentro de um componente, desanexe-os com removeEventListener ao desmontar para evitar vazamentos.

Conclusão

A Battery API em JavaScript fornece aos desenvolvedores web uma ferramenta para acessar e responder ao status da bateria dos dispositivos dos usuários. Ao utilizar essa API, as aplicações web podem melhorar a experiência do usuário, conservar a vida útil da bateria e otimizar a eficiência energética. Embora o suporte dos navegadores varie devido a considerações de privacidade, a Battery API permite criar experiências adaptadas à energia onde houver suporte — desde que você faça a detecção de recursos, trate valores de tempo Infinity e considere os dados como uma sugestão de melhor esforço, não como uma garantia.

Tópicos Relacionados

• Promises — getBattery() retorna uma.
• async / await — a forma mais limpa de lê-la.
• Introdução a eventos de navegador — como funcionam os eventos do BatteryManager.
• Geolocation API — outra API de status do dispositivo com padrões semelhantes de permissão e detecção de recursos.

Prática