Rester activé avec l'API Screen Wake Lock

Pete LePage
Thomas Steiner

Publié le 18 décembre 2018

Browser Support

  • Chrome: 84.
  • Edge: 84.
  • Firefox: 126.
  • Safari: 16.4.

Source

Qu'est-ce que l'API Screen Wake Lock ?

Pour éviter de décharger la batterie, la plupart des appareils se mettent rapidement en veille lorsqu'ils sont laissés inactifs. Bien que cela soit généralement acceptable, certaines applications doivent maintenir l'écran allumé pour effectuer leur travail. Par exemple, les applications de cuisine qui affichent les étapes d'une recette ou un jeu comme Ball Puzzle, qui utilise les API de mouvement de l'appareil pour les entrées.

L'API Screen Wake Lock permet d'empêcher l'appareil de réduire la luminosité et de verrouiller l'écran. Cette fonctionnalité permet de créer de nouvelles expériences qui, jusqu'à présent, nécessitaient une application spécifique à la plate-forme.

L'API Screen Wake Lock réduit le besoin de solutions de contournement complexes et potentiellement énergivores. Elle corrige les lacunes d'une ancienne API qui se limitait à maintenir l'écran allumé et qui présentait un certain nombre de problèmes de sécurité et de confidentialité.

Cas d'utilisation suggérés pour l'API Screen Wake Lock

RioRun, une application Web développée par The Guardian, était un cas d'utilisation idéal (bien qu'elle ne soit plus disponible). L'application vous emmène pour une visite audio virtuelle de Rio, en suivant le parcours du marathon olympique de 2016. Sans les verrous de réveil, l'écran des utilisateurs s'éteindrait fréquemment pendant la lecture de la visite, ce qui rendrait l'application difficile à utiliser.

Bien sûr, il existe de nombreux autres cas d'utilisation :

  • Une application de recettes qui maintient l'écran allumé pendant que vous préparez un gâteau ou le dîner
  • Une application de carte d'embarquement ou de billet qui maintient l'écran allumé jusqu'à ce que le code-barres soit scanné
  • Une application de type borne interactive qui maintient l'écran allumé en permanence
  • Application de présentation Web qui maintient l'écran allumé pendant une présentation

Utiliser l'API Screen Wake Lock

L'API Screen Wake Lock ne fournit qu'un seul type de wake lock : screen.

screen wakelock

Un verrouillage de réveil screen empêche l'écran de l'appareil de s'éteindre afin que l'utilisateur puisse voir les informations affichées à l'écran.

Obtenir un wakelock forçant l'activation de l'écran

Pour demander un verrouillage de réveil de l'écran, vous devez appeler la méthode navigator.wakeLock.request() qui renvoie un objet WakeLockSentinel. Vous pouvez également transmettre le type, screen, en tant que paramètre. Le navigateur peut refuser la requête pour diverses raisons (par exemple, parce que le niveau de charge de la batterie est trop faible). Il est donc recommandé d'encapsuler l'appel dans une instruction try...catch. En cas d'échec, le message de l'exception contient plus de détails.

Libérer un wakelock forçant l'activation de l'écran

Vous devez également trouver un moyen de libérer le verrouillage de l'écran, ce qui se fait en appelant la méthode release() de l'objet WakeLockSentinel. Si vous ne stockez pas de référence à WakeLockSentinel, il n'y a aucun moyen de libérer le verrou manuellement, mais il sera libéré une fois l'onglet actuel invisible.

Si vous souhaitez libérer automatiquement le verrouillage de l'écran après un certain temps, vous pouvez utiliser window.setTimeout() pour appeler release(), comme indiqué dans l'exemple.

// The wake lock sentinel.
let wakeLock = null;

// Function that attempts to request a screen wake lock.
const requestWakeLock = async () => {
  try {
    wakeLock = await navigator.wakeLock.request();
    wakeLock.addEventListener('release', () => {
      console.log('Screen Wake Lock released:', wakeLock.released);
    });
    console.log('Screen Wake Lock released:', wakeLock.released);
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
};

// Request a screen wake lock…
await requestWakeLock();
// …and release it again after 5s.
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 5000);

L'objet WakeLockSentinel possède une propriété appelée released qui indique si un sentinelle a déjà été libéré. Sa valeur est initialement false et passe à true une fois qu'un événement "release" est distribué. Cette propriété aide les développeurs Web à savoir quand un verrou a été libéré, sans suivi manuel.

Cycle de vie du wakelock forçant l'activation de l'écran

Lorsque vous jouez avec la démonstration de verrouillage de l'activation de l'écran, vous pouvez constater que les verrouillages de l'activation de l'écran sont sensibles à la visibilité de la page. Cela signifie que le wakelock forçant l'activation de l'écran est automatiquement libéré lorsque vous réduisez un onglet ou une fenêtre, ou lorsque vous quittez un onglet ou une fenêtre où un wakelock forçant l'activation de l'écran est actif.

Pour récupérer le wakelock forçant l'activation de l'écran, écoutez l'événement visibilitychange et demandez un nouveau wakelock forçant l'activation de l'écran lorsqu'il se produit :

const handleVisibilityChange = async () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    await requestWakeLock();
  }
};

document.addEventListener('visibilitychange', handleVisibilityChange);

Minimiser votre impact sur les ressources système

Dois-je utiliser un verrouillage de l'écran de réveil dans mon application ? L'approche que vous adoptez dépend des besoins de votre application. Dans tous les cas, vous devez utiliser l'approche la plus légère possible pour que votre application ait un impact minimal sur les ressources système.

Avant d'ajouter un verrouillage de réveil de l'écran à votre application, réfléchissez à la possibilité de résoudre vos cas d'utilisation avec l'une des solutions alternatives suivantes :

Démo

Consultez la démonstration de Screen Wake Lock et la source de la démonstration. Notez que le verrouillage de l'activation de l'écran est automatiquement désactivé lorsque vous changez d'onglet ou d'application.

Wakelocks forçant l'activation de l'écran dans le gestionnaire des tâches de l'OS

Vous pouvez utiliser le gestionnaire des tâches de votre système d'exploitation pour vérifier si une application empêche votre ordinateur de se mettre en veille. La vidéo montre le Moniteur d'activité de macOS indiquant que Chrome dispose d'un verrouillage d'activation de l'écran actif qui maintient le système en éveil.

Commentaires

Avez-vous trouvé un bug dans l'implémentation de Chrome ? Ou l'implémentation est-elle différente de la spécification ?

  • Signaler un bug Fournissez autant de détails que possible. Fournissez des instructions claires pour reproduire le bug et définissez Composants sur Blink>WakeLock.

Ressources

Remerciements

Vidéo sur le gestionnaire de tâches fournie par Henry Lim.