Mantente activo con la API de Screen Wake Lock

Pete LePage
Thomas Steiner

Publicado: 18 de diciembre de 2018

Browser Support

  • Chrome: 84.
  • Edge: 84.
  • Firefox: 126.
  • Safari: 16.4.

Source

¿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 están 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 que consumen mucha 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, hay 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

Usa la API de Screen Wake Lock

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

Bloqueo de activación de screen

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. De manera opcional, puedes pasar el tipo, screen, como un parámetro. 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 contiene 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 manualmente, 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 un período determinado, puedes usar window.setTimeout() para llamar a release(), como se muestra en el 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ó una versión 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, sin necesidad de realizar un seguimiento manual.

Ciclo de vida del bloqueo de activación de pantalla

Cuando juegas con la demostración del bloqueo de activación de la pantalla, puedes ver 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 pantalla se libera automáticamente cuando minimizas una pestaña o ventana, o cuando cambias 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 el código 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 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

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

  • Informa un error. Incluye tantos detalles como puedas. Proporciona instrucciones claras para reproducir el error y establece Components en Blink>WakeLock.

Recursos

Agradecimientos

Video del administrador de tareas cortesía de Henry Lim.