Rester activé avec l'API Screen Wake Lock

L'API Screen Wake Lock permet d'empêcher les appareils de réduire la luminosité ou de verrouiller l'écran lorsqu'une application doit continuer à s'exécuter.

Pete LePage
Thomas Steiner

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 ne sont pas utilisés. Bien que cela ne pose pas de problème la plupart du temps, certaines applications doivent garder l'écran activé pour terminer leur travail. Il peut s'agir, par exemple, d'applications de cuisine qui montrent les étapes d'une recette ou d'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 s'assombrir et de verrouiller l'écran. Cette fonctionnalité permet d'offrir 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 gourmandes en énergie. Elle corrige les lacunes d'une ancienne API qui se limitait au simple maintien de l'écran allumé et 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 parfait (bien qu'elle ne soit plus disponible). L'application vous fait faire une visite audio virtuelle de Rio, en suivant le parcours du marathon olympique de 2016. Sans wakelock, les écrans des utilisateurs s'éteignaient fréquemment pendant la lecture de la visite, ce qui la rendait difficile à utiliser.

Il existe évidemment de nombreux autres cas d'utilisation:

  • Une application de recettes qui maintient l'écran allumé pendant que vous préparez un gâteau ou un dîner
  • Application de carte d'embarquement ou de billetterie qui maintient l'écran allumé jusqu'à ce que le code-barres ait été scanné
  • Application de style kiosque qui maintient l'écran allumé en continu
  • Une application de présentation Web qui maintient l'écran allumé pendant une présentation

État actuel

Step État
1. Créer une vidéo explicative N/A
2. Créer un brouillon initial de la spécification Fin
3. Recueillir les commentaires et itérer la conception Fin
4. Phase d'évaluation Terminé
5. Lancement Fin

Utiliser l'API Screen Wake Lock

Types de wakelocks

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

Wakelock screen

Un wakelock screen empêche l'écran de l'appareil de s'éteindre afin que l'utilisateur puisse voir les informations qui s'affichent à l'écran.

Activer le verrouillage de l'écran

Pour demander un wakelock de verrouillage de l'écran, vous devez appeler la méthode navigator.wakeLock.request() qui renvoie un objet WakeLockSentinel. Vous transmettez à cette méthode le type de wakelock souhaité en tant que paramètre, qui actuellement est limité à 'screen' et qui est donc facultatif. 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. Le message de l'exception contiendra plus de détails en cas d'échec.

Libérer le wakelock de l'écran

Vous devez également libérer le wakelock de l'écran, obtenu 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 déverrouiller manuellement le verrouillage. Toutefois, il sera libéré une fois que l'onglet actuel sera invisible.

Si vous souhaitez libérer automatiquement le wakelock de l'écran au bout d'un certain temps, vous pouvez utiliser window.setTimeout() pour appeler release(), comme illustré dans l'exemple ci-dessous.

// 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 une sentinelle a déjà été libérée. Sa valeur est initialement false, et devient true une fois qu'un événement "release" est envoyé. Cette propriété permet aux développeurs Web de savoir quand un verrou a été libéré, afin de ne pas avoir à en effectuer le suivi manuellement. Elle est disponible à partir de Chrome 87.

Cycle de vie du wakelock de l'écran

Lorsque vous jouez avec la démonstration du wakelock en cas d'écran, vous remarquerez que les wakelocks de l'écran sont sensibles à la visibilité de la page. Cela signifie que le wakelock en cas d'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ù le verrouillage de l'écran est actif.

Pour réacquérir le wakelock de l'écran, écoutez l'événement visibilitychange et demandez un nouveau wakelock de l'écran lorsqu'il se produit:

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

document.addEventListener('visibilitychange', handleVisibilityChange);

Réduire votre impact sur les ressources système

Faut-il utiliser un wakelock de démarrage de l'écran dans votre application ? L'approche que vous adoptez dépend des besoins de votre application. Quoi qu'il en soit, vous devez utiliser l'approche la plus légère possible pour votre application afin de minimiser son impact sur les ressources système.

Avant d'ajouter un wakelock de démarrage de l'écran à votre application, demandez-vous si vos cas d'utilisation peuvent être résolus à l'aide de l'une des solutions alternatives suivantes:

Démonstration

Consultez la démo du wakelock de démarrage de l'écran et la source de démonstration. Notez que le wakelock de démarrage de l'écran est automatiquement libéré lorsque vous changez d'onglet ou d'application.

Wakelocks forçant l'activation de l'écran dans le gestionnaire de tâches du système d'exploitation

Vous pouvez utiliser le gestionnaire de tâches de votre système d'exploitation pour voir si une application empêche votre ordinateur de se mettre en veille. La vidéo ci-dessous montre le moniteur d'activité de macOS, qui indique que Chrome dispose d'un wakelock de démarrage actif qui maintient le système activé.

Commentaires

Le Web Platform Incubator Community Group (WICG) et l'équipe Chrome souhaitent connaître vos réflexions et expériences concernant l'API Screen Wake Lock.

Décrivez-nous la conception de l'API.

Y a-t-il quelque chose dans l'API qui ne fonctionne pas comme prévu ? Ou manque-t-il des méthodes ou des propriétés dont vous avez besoin pour mettre en œuvre votre idée ?

Signaler un problème d'implémentation

Avez-vous détecté un bug dans l'implémentation de Chrome ? Ou l'implémentation est-elle différente des spécifications ?

  • Signalez un bug à l'adresse https://new.crbug.com. Veillez à inclure autant de détails que possible, à fournir des instructions simples pour reproduire le bug et à définir le champ Composants sur Blink>WakeLock. Glitch est idéal pour partager des reproductions rapides et faciles.

Afficher la compatibilité avec l'API

Comptez-vous utiliser l'API Screen Wake Lock ? Votre assistance publique aide l'équipe Chrome à hiérarchiser les fonctionnalités et montre aux autres fournisseurs de navigateurs à quel point il est essentiel de les prendre en charge.

Liens utiles

Remerciements

Image principale de Kate Stone Matheson sur Unsplash. Vidéo du gestionnaire de tâches avec l'aimable autorisation de Henry Lim.