Battery API

Battery API en JavaScript: Monitorización del estado de la batería

La Battery API en JavaScript es una interfaz que permite a las páginas web leer el estado de la batería de un dispositivo: cuánta carga tiene, si está cargando y cuánto tiempo falta para que esté completa o se agote. Con esta información, una aplicación web puede adaptar su comportamiento — por ejemplo, reducir tareas en segundo plano o atenuar animaciones pesadas cuando el dispositivo tiene poca batería. Este artículo explica qué es la Battery API, los datos que expone, cuándo merece la pena usarla y cómo leerla correctamente con promesas y eventos.

Nota: Dado que el nivel de batería es una señal de identificación muy precisa (es un número casi único que cambia lentamente), los navegadores han ido retirando la Battery API. Ha sido eliminada de Firefox y Safari, y navigator.getBattery() solo está disponible en navegadores basados en Chromium (Chrome, Edge, Opera) bajo un contexto seguro (HTTPS). Trátala como una mejora progresiva y siempre detecta su disponibilidad antes de llamarla — tu código debe funcionar cuando la API no esté presente.

¿Qué es la Battery API?

La Battery API se expone a través de un único método, navigator.getBattery(), que devuelve una Promise que se resuelve en un objeto BatteryManager. Ese objeto contiene cuatro propiedades de solo lectura que describen el estado actual, más cuatro eventos que se disparan cuando alguno de esos valores cambia. Como getBattery() es asíncrono, se lee con .then() o con async/await.

Propiedades de BatteryManager

Eventos de BatteryManager

Cada evento es un evento DOM estándar, por lo que te suscribes con addEventListener sobre el BatteryManager.

Ventajas de la Battery API

• Mejora de la experiencia de usuario: Al acceder a la información del estado de la batería, las aplicaciones web pueden adaptar su comportamiento para ahorrar energía cuando el dispositivo funciona con batería, o proporcionar funciones mejoradas cuando está conectado y cargando.
• Eficiencia energética: Utilizando la información del estado de la batería, las aplicaciones web pueden optimizar operaciones que consumen muchos recursos para reducir el consumo de energía y prolongar la vida útil de la batería.
• Actualizaciones en tiempo real: La API proporciona actualizaciones en tiempo real sobre los cambios en el estado de la batería, lo que permite a las aplicaciones web responder de inmediato a cambios como desconectar el dispositivo o niveles de batería bajos.
• Compatibilidad con navegadores: La Battery API está disponible en varios navegadores modernos, aunque los desarrolladores deben implementar la detección de características para garantizar la compatibilidad en diferentes entornos.

Cuándo usar la Battery API

Considera usar la Battery API cuando tu aplicación web necesite:

1. Ofrecer funciones adaptadas a la energía: Adapta las funciones y el comportamiento de tu aplicación en función de si el dispositivo funciona con batería, está cargando o totalmente cargado.
2. Conservar la vida útil de la batería: Optimiza las operaciones que consumen muchos recursos cuando el dispositivo funciona con batería para reducir el consumo de energía y prolongar su duración.
3. Mostrar el estado de la batería: Muestra información relacionada con la batería a los usuarios, como el nivel actual o el tiempo estimado hasta que la batería esté completamente cargada.
4. Desencadenar acciones ante eventos de batería: Ejecuta acciones específicas cuando cambia el estado de la batería, como mostrar una advertencia de batería baja o pausar tareas que consumen muchos recursos.

Casos de uso prácticos

1. Alerta de batería baja: Puedes usar la Battery API para activar una alerta de batería baja cuando el nivel de batería del dispositivo cae por debajo de un umbral determinado, instando a los usuarios a ahorrar energía o conectar su dispositivo.
2. Animaciones eficientes energéticamente: Las aplicaciones web pueden ajustar la intensidad y frecuencia de las animaciones en función del estado de la batería del dispositivo para reducir el consumo de energía.
3. Gestión de procesos en segundo plano: Optimiza los procesos en segundo plano, como la sincronización de datos o el envío de notificaciones, para que ocurran con menos frecuencia cuando el dispositivo funciona con batería y así conservar energía.
4. Carga dinámica de recursos: Carga imágenes de alta resolución o contenido que consume muchos recursos solo cuando el dispositivo está cargando o cuando el nivel de batería supera un umbral determinado, mejorando el rendimiento y la eficiencia energética.

Detección de características

Nunca asumas que getBattery() existe. Protege cada llamada para que los navegadores que no lo admiten fallen de forma elegante en lugar de lanzar 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 es la comprobación canónica: es true solo donde la API está presente. La forma con async/await lee el BatteryManager resuelto exactamente igual que la forma con .then(), pero fluye de arriba a abajo.

Ejemplo básico: Monitorización del estado de la batería

El ejemplo siguiente lee la batería una vez y luego mantiene el texto en pantalla sincronizado escuchando los eventos relevantes. Observa el helper toHours — chargingTime y dischargingTime se reportan en segundos, por lo que dividir entre 3600 los convierte en horas legibles. Ambos valores pueden ser Infinity, por lo que manejamos ese caso de forma explícita.

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

Cómo funciona:

• Estimación de tiempo: El script comprueba si la batería está cargando o descargando y muestra un tiempo estimado hasta que la batería esté completamente cargada o agotada.
• Escuchadores de eventos: Actualiza la pantalla en tiempo real a medida que cambia el estado de la batería.

Este ejemplo ayuda a ilustrar cómo la Battery API puede proporcionar información detallada sobre el uso de la batería, incluyendo estimaciones de tiempo, lo que puede ser especialmente útil para dispositivos móviles y portátiles en la gestión del consumo de energía y la planificación del uso.

Reaccionando ante una batería baja

Un patrón habitual es cambiar la página a un modo de "ahorro de energía" cuando la carga cae por debajo de un umbral mientras funciona con batería. Escucha levelchange y chargingchange juntos para reevaluar el modo ante cualquiera de las dos señales:

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

Esto es mucho más eficiente que hacer sondeos con un temporizador: la función de retorno solo se ejecuta cuando el estado de la batería realmente cambia.

Errores comunes

• Es posible que nunca resuelva datos útiles. En un ordenador de escritorio sin batería, charging es true, level es 1, y ambas propiedades de tiempo son 0 o Infinity. No trates la API como una señal fiable de "estoy en un portátil."
• Infinity es normal. chargingTime es Infinity siempre que el dispositivo no esté cargando, y dischargingTime es Infinity siempre que el tiempo no pueda estimarse. Comprueba siempre este caso antes de formatear.
• Las estimaciones son aproximadas y limitadas. Para reducir la identificación de usuarios, los navegadores redondean level y los valores de tiempo, por lo que no construyas cuentas regresivas precisas sobre ellos.
• Se requiere contexto seguro. getBattery() solo está disponible en páginas HTTPS (y localhost). En HTTP simple es undefined, lo que tu comprobación de características detecta.
• Elimina los escuchadores que ya no necesites. Si adjuntas escuchadores dentro de un componente, desconéctalos con removeEventListener al desmontarlo para evitar fugas de memoria.

Conclusión

La Battery API en JavaScript proporciona a los desarrolladores web una herramienta para acceder y responder al estado de la batería de los dispositivos de los usuarios. Al utilizar esta API, las aplicaciones web pueden mejorar la experiencia de usuario, conservar la vida útil de la batería y optimizar la eficiencia energética. Aunque la compatibilidad con los navegadores varía por razones de privacidad, la Battery API te permite crear experiencias adaptadas a la energía donde esté disponible — siempre que detectes la característica, gestiones los valores de tiempo Infinity y trates los datos como una estimación aproximada y no como una garantía.

Temas relacionados

• Promises — getBattery() devuelve una.
• async / await — la forma más limpia de leerla.
• Introducción a los eventos del navegador — cómo funcionan los eventos de BatteryManager.
• Geolocation API — otra API de estado del dispositivo con patrones similares de permisos y detección de características.

Práctica