Mantente activo con la API de Screen Wake Lock

La API de Screen Wake Lock API es una forma 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 se suspenden rápidamente cuando están inactivos. Si bien esto es correcto la mayor parte del tiempo, algunas aplicaciones necesitan mantener la pantalla encendida 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 entradas.

La API de Screen Wake Lock proporciona una manera 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 que requieren mucha energía. Además, 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 preparas un pastel o 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 N/A
2. Crea el borrador inicial de la especificación Completo
3. Recopila comentarios e itera el diseño Completo
4. Prueba de origen Completo
5. Lanzamiento Completo

Usa 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

El 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 por el momento 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 contendrá más detalles en caso de error.

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 al WakeLockSentinel, no hay manera de desbloquear 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 hacer 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 salgas de una pestaña o ventana en la que esté activo un bloqueo de activación de pantalla.

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

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 adoptes dependerá de las necesidades de tu app. Independientemente de ello, debes usar el enfoque más ligero 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 de Screen Wake Lock y la fuente de 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 está impidiendo que tu 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 pensamientos y experiencias con la API de Screen Wake Lock.

Cuéntanos sobre el diseño de la 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 un error en https://new.crbug.com. Asegúrate de incluir todos los detalles que puedas, proporciona instrucciones simples para reproducir el error y establece Componentes como Blink>WakeLock. Glitch funciona muy bien para compartir repros rápidos y fáciles.

Muestra compatibilidad con la API

¿Planeas usar la API de Screen Wake Lock? La asistencia pública ayuda al equipo de Chrome a priorizar funciones y le 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.