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 se agote la batería, la mayoría de los dispositivos se suspenden rápidamente cuando se dejan inactivos. Si bien esto es correcto la mayoría de las veces, 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 capacidad permite nuevas experiencias que, hasta ahora, requerían una app específica para la plataforma.

La API de Screen Wake Lock reduce la necesidad de soluciones alternativas poco prácticas y potencialmente con un alto consumo de energía. Aborda las deficiencias de una API anterior 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, fue un caso de uso perfecto (aunque ya no está disponible). La app te lleva a un recorrido de audio virtual por Río, siguiendo 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 reproduce el recorrido, lo que dificultaría su 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 boletos o pases de abordar que mantiene la pantalla encendida hasta que se escanea el código de barras
  • Una app de estilo quiosco 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 el borrador inicial de la especificación Completar
3. Recopila comentarios y realiza iteraciones en 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.

screen bloqueo de activación

Un screen bloqueo de activación impide que se apague la pantalla del dispositivo 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 devuelve un objeto WakeLockSentinel. Le pasas a este método el tipo de bloqueo de activación deseado como parámetro, que actualmente se limita solo 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 es una buena práctica incluir la llamada en una instrucción 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, lo 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 deseas liberar automáticamente el bloqueo de activación de la pantalla después de un cierto período, 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. Su valor es false inicialmente 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, de modo que no tengan que 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 los bloqueos de activación de pantalla son sensibles a la visibilidad de la página. Esto significa que el bloqueo de activación de pantalla se liberará automáticamente cuando minimices una pestaña o ventana, o cuando cambies a 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 un nuevo bloqueo de activación de pantalla cuando se produzcan:

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

document.addEventListener('visibilitychange', handleVisibilityChange);

Minimiza tu impacto en los recursos del sistema

¿Deberías usar un bloqueo de activación de pantalla en tu app? El enfoque que elijas dependerá de las necesidades de tu app. De todos modos, te recomendamos que uses el enfoque más sencillo 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 la demostración. Observa cómo se libera automáticamente el bloqueo de activación de la pantalla cuando cambias de pestañas o apps.

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

Puedes usar el administrador de tareas de tu sistema operativo para ver si una aplicación impide que se suspenda la computadora. 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 sobre la API que no funciona como se espera? ¿O faltan métodos o propiedades que necesitas para implementar tu idea?

Informa un problema con la implementación

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

  • Informa el error en https://new.crbug.com. Asegúrate de incluir la mayor cantidad de detalles posible, proporcionar instrucciones sencillas para reproducir el error y establecer Components en Blink>WakeLock.

Cómo mostrar compatibilidad con la API

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

Vínculos útiles

Agradecimientos

Imagen de encabezado de Kate Stone Matheson en Unsplash. Video del administrador de tareas cortesía de Henry Lim.