Mantente activo con la API de Screen Wake Lock

La API de Screen Wake Lock proporciona una forma de evitar que los dispositivos atenúen o bloqueen la pantalla cuando una aplicación necesita seguir ejecutándose.

Pete LePage
Thomas Steiner

¿Qué es la API de Screen Wake Lock?

Para evitar que la batería se agote, la mayoría de los dispositivos se suspenden rápidamente cuando están inactivos. Si bien esto funciona la mayor parte del tiempo, algunas aplicaciones necesitan mantener la pantalla activa para completar su trabajo. Entre los ejemplos, se incluyen apps de cocina que muestran los pasos de una receta o un juego como Ball Puzzle, que usa las APIs de movimiento del dispositivo para la entrada.

La API de Screen Wake Lock proporciona una forma de evitar que el dispositivo atenúe y bloquee la pantalla. Esta función habilita experiencias nuevas que, hasta ahora, requerían una app específica de la plataforma.

La API de Screen Wake Lock reduce la necesidad de soluciones alternativas y que podrían requerir mucha energía. Aborda las deficiencias de una API más antigua que se limitaba a mantener la pantalla encendida y tenía varios problemas de seguridad y privacidad.

Casos de uso sugeridos para la API de Screen Wake Lock

RioRun, una app web desarrollada por The Guardian, era un caso de uso perfecto (aunque ya no está disponible). La app te lleva a una audioguía virtual por Río, siguiendo la ruta del maratón olímpico de 2016. Sin los bloqueos de activación, las pantallas de los usuarios se apagarían con frecuencia mientras se reproduce el viaje, lo que dificultaría el uso.

Por supuesto, existen muchos otros casos de uso:

  • Una app de recetas que mantiene la pantalla encendida mientras horneas un pastel o preparas la cena
  • Una app de tarjeta de embarque o boleto que mantiene la pantalla encendida hasta que se escanea el código de barras
  • Una app de estilo kiosco que mantiene la pantalla encendida de forma continua
  • Una app de presentación basada en la Web que mantiene la pantalla encendida durante una presentación

Estado actual

Paso Estado
1. Crea una explicación N/A
2. Crea un borrador inicial de la especificación Completar
3. Recopila comentarios y itera el diseño Completar
4. Prueba de origen Completado
5. Lanzamiento Completar

Cómo usar la API de Screen Wake Lock

Tipos de bloqueo de activación

Actualmente, la API de Screen Wake Lock solo proporciona un tipo de bloqueo de activación: screen.

bloqueo de activación de screen

Un bloqueo de activación screen evita que la pantalla del dispositivo se apague para que el usuario pueda ver la información que se muestra en ella.

Cómo obtener un bloqueo de activación de pantalla

Para solicitar un bloqueo de activación de pantalla, debes llamar al método navigator.wakeLock.request() que muestra un objeto WakeLockSentinel. A este método, le pasas el tipo de bloqueo de activación deseado como parámetro, que por el momento está limitado a 'screen' y, por lo tanto, es opcional. El navegador puede rechazar la solicitud por varios motivos (por ejemplo, porque el nivel de carga de la batería es demasiado bajo), por lo que se recomienda unir la llamada en una sentencia try…catch. El mensaje de la excepción contendrá más detalles en caso de falla.

Cómo liberar un bloqueo de activación de pantalla

También necesitas una forma de liberar el bloqueo de activación de la pantalla, que se logra llamando al método release() del objeto WakeLockSentinel. Si no almacenas una referencia a WakeLockSentinel, no hay forma de liberar el bloqueo de forma manual, pero se liberará una vez que la pestaña actual sea invisible.

Si quieres liberar automáticamente el bloqueo de activación de la pantalla después de que haya transcurrido un período determinado, puedes usar window.setTimeout() para llamar a release(), como se muestra en el siguiente ejemplo.

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

El objeto WakeLockSentinel tiene una propiedad llamada released que indica si ya se lanzó un centinela. Inicialmente, su valor es false y cambia a true una vez que se envía un evento "release". Esta propiedad ayuda a los desarrolladores web a saber cuándo se liberó un bloqueo para que no necesiten realizar un seguimiento de esto manualmente. Está disponible a partir de Chrome 87.

Ciclo de vida del bloqueo de activación de la pantalla

Cuando juegues con la demo de bloqueo de activación de la pantalla, notarás que los bloqueos de activación de la pantalla son sensibles a la visibilidad de la página. Esto significa que el bloqueo de activación de la pantalla se liberará automáticamente cuando minimices una pestaña o ventana, o cambies de una pestaña o ventana en la que esté activo un bloqueo de activación de la pantalla.

Para volver a adquirir el bloqueo de activación de pantalla, escucha el evento visibilitychange y solicita un nuevo bloqueo de activación de pantalla cuando ocurra:

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

document.addEventListener('visibilitychange', handleVisibilityChange);

Minimiza el impacto en los recursos del sistema

¿Debes usar un bloqueo de activación de pantalla en tu app? El enfoque que elijas dependerá de las necesidades de tu app. Sin embargo, debes usar el enfoque más ligero posible para tu app para minimizar su impacto en los recursos del sistema.

Antes de agregar un bloqueo de activación de pantalla a tu app, considera si los casos de uso podrían resolverse con una de las siguientes soluciones alternativas:

Demostración

Consulta la demostración de Screen Wake Lock y la fuente de demostración. Observa cómo se libera automáticamente el bloqueo de activación de la pantalla cuando cambias de pestaña o de app.

Bloqueos de activación de pantalla en el administrador de tareas del SO

Puedes utilizar el administrador de tareas de tu sistema operativo para ver si una aplicación evita que la computadora se suspenda. En el siguiente video, se muestra el Monitor de actividad de macOS, que indica que Chrome tiene un bloqueo de activación de pantalla activo que mantiene el sistema activo.

Comentarios

El Web Platform Incubator Community Group (WICG) y el equipo de Chrome quieren conocer tus opiniones y experiencias con la API de Screen Wake Lock.

Cuéntanos sobre el diseño de la API

¿Hay algo en la API que no funciona como se espera? ¿O faltan métodos o propiedades que necesites para implementar tu idea?

Informar un problema con la implementación

¿Encontraste un error en la implementación de Chrome? ¿O la implementación es diferente a la especificación?

  • Informa un error en https://new.crbug.com. Asegúrate de incluir la mayor cantidad de detalles posible, proporciona instrucciones simples para reproducir el error y establece Componentes en Blink>WakeLock. Glitch funciona muy bien para compartir repros rápidos y fáciles.

Cómo mostrar compatibilidad con la API

¿Piensas usar la API de Screen Wake Lock? Tu apoyo público ayuda al equipo de Chrome a priorizar las funciones y les muestra a otros proveedores de navegadores lo importante que es admitirlas.

Vínculos útiles

Agradecimientos

Hero image de Kate Stone Matheson en Unsplash. Video del Administrador de tareas cortesía de Henry Lim.