Mantente activo con la API de Screen Wake Lock

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

¿Qué es la API de Screen Wake Lock?

Para evitar que la batería se agote, la mayoría de los dispositivos pasan rápidamente al modo de suspensión cuando están inactivos. Si bien esto es correcto la mayor parte del tiempo, algunas aplicaciones necesitan mantener la pantalla activa para completar su trabajo. Algunos ejemplos 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 como entrada.

La API de Screen Wake Lock proporciona una forma de evitar que el dispositivo atenúe y bloquee la pantalla. Esta función permite 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 ingeniosas y que posiblemente consuman mucha batería. Aborda las deficiencias de una API anterior que se limitaba a mantener la pantalla encendida y presentaba 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, fue un caso de uso perfecto (aunque ya no está disponible). La app te lleva en un recorrido virtual de audio por Río para seguir la ruta de la maratón Olímpica de 2016. Sin los bloqueos de activación, las pantallas de los usuarios se apagarían con frecuencia mientras se reproducía el viaje, lo que dificultaba su uso.

Por supuesto, hay muchos otros casos de uso:

  • Una app de recetas que mantiene la pantalla encendida mientras horneas un pastel o cocinas una cena.
  • Una app de tarjetas de embarque o boletos que mantiene la pantalla encendida hasta que se escanea el código
  • Una aplicación tipo kiosco que mantiene la pantalla encendida continuamente
  • Una aplicación de presentación basada en la Web que mantiene la pantalla encendida durante una presentación

Estado actual

Step Estado
1. Crear explicación No disponible
2. Crea el borrador inicial de la especificación Completo
3. Recopila comentarios e itera el diseño Completo
4. Prueba de origen Completado
5. Lanzamiento Completo

Cómo usar la API de Screen Wake Lock

Tipos de bloqueos de activación

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

Bloqueo de activación de screen

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

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. Pasa a este método el tipo de bloqueo de activación deseado como parámetro, que actualmente se limita a solo '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 declaración try…catch. El mensaje de la excepción incluirá más detalles en caso de que se produzca un error.

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

También necesitas una forma de liberar el bloqueo de activación de 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 pantalla después de 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 liberó 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 manual. Está disponible a partir de Chrome 87.

Ciclo de vida del bloqueo de activación de pantalla

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

Para volver a adquirir el bloqueo de activación de pantalla, busca 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

¿Deberías usar un bloqueo de activación de pantalla en tu app? El enfoque que adoptes dependerá de las necesidades de tu app. Independientemente de ello, debes usar el enfoque más simple posible para tu app a fin de minimizar su impacto en los recursos del sistema.

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

Demostración

Consulta la demostración del bloqueo de activación de pantalla y la fuente de la demostración. Observa cómo el bloqueo de activación de pantalla se libera automáticamente 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 impide que la computadora se suspenda. En el siguiente video, se muestra el Monitor de actividad de macOS en el que se indica que Chrome tiene un bloqueo de activación de pantalla activo que mantiene el sistema activo.

Comentarios

El Grupo de la comunidad de Web Platform Incubator (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 API

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

Informar un problema con la implementación

¿Encontraste un error en la implementación de Chrome? ¿La implementación es diferente de las especificaciones?

  • Informa el error en https://new.crbug.com. Asegúrate de incluir todos los detalles que puedas, proporciona instrucciones simples para reproducir el error y configura los componentes como Blink>WakeLock. Glitch funciona muy bien para compartir repros rápidos y fáciles.

Demuestra compatibilidad con la API

¿Tienes pensado usar la API de Screen Wake Lock? La asistencia pública ayuda al equipo de Chrome a priorizar funciones y les muestra a otros proveedores de navegadores la importancia de admitirlas.

Vínculos útiles

Agradecimientos

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