Utiliser l'API Battery Status dans les applications web

La plupart des applications web n’ont aucune idée si la personne qui les utilise est à 8 % de batterie dans un train sans chargeur à portée de main. L’API Battery Status change la donne — du moins dans certains navigateurs. Elle permet à votre JavaScript de lire le niveau de batterie de l’appareil, son état de charge et le temps restant estimé, afin que vous puissiez adapter le comportement de votre application en conséquence.

Cet article explique comment fonctionne l’API, ce que vous pouvez réalistement en faire, et pourquoi vous devez être prudent quant à l’endroit et la manière dont vous l’utilisez.

Qu’est-ce que l’API Battery Status ?

L’API Battery Status expose les informations sur la batterie via la méthode navigator.getBattery(), qui retourne une Promise résolue en un objet BatteryManager. Cet objet vous donne accès à quatre propriétés :

• level — un nombre entre 0 et 1 (par exemple, 0.72 signifie 72 %)
• charging — true si l’appareil est branché, false sinon
• chargingTime — secondes estimées jusqu’à la charge complète
• dischargingTime — secondes estimées jusqu’à ce que la batterie soit vide

Les deux propriétés de temps peuvent retourner Infinity — lorsque l’appareil est un ordinateur de bureau sans batterie, lorsque l’estimation n’est pas encore prête, ou lorsque le navigateur retient délibérément la précision pour limiter les risques de fingerprinting.

Comment utiliser navigator.getBattery() en toute sécurité

Vérifiez toujours la prise en charge avant d’appeler l’API. Elle n’est disponible que dans les contextes sécurisés (HTTPS), et même dans ce cas, uniquement dans les navigateurs qui l’exposent.

Dans les contextes embarqués, l’accès peut également être restreint par la Permissions Policy battery.

async function initBatteryMonitor() {
  // Feature detection — don't assume the API exists
  if (!('getBattery' in navigator)) {
    console.warn('Battery Status API not supported in this browser.')
    return
  }

  let battery

  try {
    battery = await navigator.getBattery()
  } catch (err) {
    console.error('Failed to access battery information:', err)
    return
  }

  // Read initial values
  console.log(`Level: ${battery.level * 100}%`)
  console.log(`Charging: ${battery.charging}`)

  // Handle Infinity gracefully before displaying
  const formatTime = (seconds) =>
    seconds === Infinity ? 'Unknown' : `${Math.round(seconds / 60)} min`

  console.log(`Charging time: ${formatTime(battery.chargingTime)}`)
  console.log(`Discharging time: ${formatTime(battery.dischargingTime)}`)

  // Listen for changes
  battery.addEventListener('levelchange', () => {
    console.log(`Battery level updated: ${battery.level * 100}%`)
  })

  battery.addEventListener('chargingchange', () => {
    console.log(`Charging state changed: ${battery.charging}`)
  })
}

initBatteryMonitor()

Les quatre événements que vous pouvez écouter sont levelchange, chargingchange, chargingtimechange et dischargingtimechange. Chacun se déclenche lorsque sa valeur correspondante change.

Cas d’usage pratiques

L’API est particulièrement utile lorsque vous souhaitez réduire la consommation de ressources pour les utilisateurs avec une batterie faible :

• Mettre en pause la synchronisation en arrière-plan ou le polling lorsque battery.level descend en dessous d’un seuil comme 0.2
• Réduire la complexité des animations ou désactiver la lecture automatique des vidéos
• Inviter les utilisateurs à sauvegarder leur travail avant que la batterie ne s’épuise
• Ajuster le comportement des PWA — par exemple, différer les requêtes réseau non critiques

Ce sont des améliorations progressives. Votre application devrait fonctionner correctement sans elles.

Prise en charge par les navigateurs et préoccupations liées à la confidentialité

C’est là que l’API Battery Status devient compliquée.

La prise en charge actuelle par les navigateurs est limitée. Firefox a supprimé l’API car des chercheurs ont démontré qu’elle pouvait être utilisée comme vecteur de fingerprinting — la combinaison du niveau de batterie et des valeurs de temps était suffisamment spécifique pour aider à suivre les utilisateurs d’un site à l’autre. En réponse, les navigateurs basés sur Chromium peuvent réduire la précision ou exposer des valeurs par défaut pour limiter ce risque.

Cela signifie que vous ne devriez jamais vous fier à l’API Battery comme fonctionnalité principale. Traitez-la comme une amélioration appréciable, et écrivez toujours un comportement de repli pour les cas où elle ne retourne rien.

Tester l’API Battery en développement

Chrome DevTools ne fournit actuellement pas de simulateur de batterie intégré dans la section Sensors. Pour tester le comportement lié à la batterie pendant le développement, vous disposez de quelques options pratiques :

• Utiliser un véritable appareil mobile connecté via le débogage distant USB, et observer les changements réels d’état de la batterie.
• Simuler l’API dans votre code en remplaçant navigator.getBattery par une fonction qui retourne un faux objet BatteryManager avec les propriétés et événements dont vous avez besoin pour tester.
• Utiliser des surcharges de navigateur ou des bibliothèques de test telles que Sinon ou Jest pour créer un stub de navigator.getBattery() dans votre suite de tests.

Voici un mock minimal que vous pouvez intégrer dans votre environnement de développement :

function mockBattery({ level = 0.15, charging = false } = {}) {
  const fake = {
    level,
    charging,
    chargingTime: charging ? 3600 : Infinity,
    dischargingTime: charging ? Infinity : 1800,
    addEventListener: () => {},
  }

  navigator.getBattery = () => Promise.resolve(fake)
}

// Simulate a low-battery, unplugged device
mockBattery({ level: 0.08, charging: false })

Cette approche vous donne un contrôle total sur les valeurs que votre code reçoit, sans dépendre d’outils spécifiques au navigateur.

Conclusion

L’API Battery Status est un outil de niche avec de réelles limitations. La prise en charge par les navigateurs est limitée, les valeurs sont intentionnellement imprécises, et les implications en matière de confidentialité signifient que son avenir est incertain. Mais dans des environnements contrôlés — outils internes, PWA ciblant des navigateurs basés sur Chromium connus, ou applications de type kiosque — elle peut améliorer significativement l’expérience utilisateur.

Utilisez la détection de fonctionnalité, gérez explicitement les valeurs Infinity, nettoyez vos écouteurs d’événements lorsqu’ils ne sont plus nécessaires, et ne construisez jamais une fonctionnalité critique par-dessus.

FAQ

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.