Mantente despierto con la API de Screen Wake Lock

# ¿Qué es la API de Screen Wake Lock?

Para evitar agotar la batería, la mayoría de los dispositivos se duermen rápidamente cuando se dejan inactivos. Si bien esto está bien la mayor parte del tiempo, algunas aplicaciones necesitan mantener la pantalla activa para completar su trabajo. Los ejemplos incluyen aplicaciones de cocina que muestran los pasos de una receta o un juego como Ball Puzzle, que utiliza las API de movimiento del dispositivo como entrada.

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

La API Screen Wake Lock reduce la necesidad de soluciones del tipo hacker y potencialmente hambrientas de energía. Aborda las deficiencias de una API anterior que se limitaba simplemente a mantener la pantalla encendida y tenía una serie de problemas de seguridad y privacidad.

# Casos de uso sugeridos para la API de Screen Wake Lock

RioRun, una aplicación web desarrollada por The Guardian, fue un caso de uso perfecto (aunque ya no está disponible). La aplicación te lleva a un recorrido de audio virtual por Río, siguiendo la ruta del maratón olímpico del 2016. Sin los wake locks, las pantallas de los usuarios se apagaban con frecuencia mientras se reproducía el recorrido, lo que dificultaba su uso.

Por supuesto, hay muchos otros casos de uso:

• Una aplicación de recetas que mantiene la pantalla encendida mientras horneas un pastel o preparas la cena
• Una aplicación de tarjeta o boleto de embarque que mantiene la pantalla encendida hasta que se escanea el código de barras
• Una aplicación estilo quiosco 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

# Usando la API de Screen Wake Lock

# Tipos de wake lock

La API de Screen Wake Lock actualmente proporciona solo un tipo de wake lock: screen.

# wake lock de screen

Un wake lock de screen evita que la pantalla del dispositivo se apague de manera que el usuario puede ver la información que se muestra en la pantalla.

# Detección de características

La compatibilidad del navegador con la API de Screen Wake Lock se puede probar de la siguiente manera:

if ('wakeLock' in navigator) {
  // El API de Screen Wake Lock es compatible 🎉
}

# Obteniendo un screen wake lock

Para solicitar un scren wake lock, necesitas llamar al método de WakeLockSentinel que regresa un objeto navigator.wakeLock.request(). Luego pasas a este método el tipo de wake lock deseado como parámetro, que actualmente está limitado a solo 'screen' y, por lo tanto, es opcional. El navegador puede rechazar la solicitud por varias razones (por ejemplo, porque el nivel de carga de la batería es demasiado bajo), por lo que es una buena práctica envolver la llamada en una declaración de try…catch. El mensaje de la excepción contendrá más detalles en caso de fallar.

# Liberar un screen wake lock

También necesitas una forma de liberar el screen wake lock, el cual se hace mediante el método de 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 deseas liberar automáticamente el bloqueo de activación de la pantalla después de que haya pasado un cierto período de tiempo, puedes usar window.setTimeout() para llamar a release(), como se muestra en el siguiente ejemplo.

// El sentinela del wake lock.
let wakeLock = null;

// Función que busca hacer un pedido al screen wake lock.
const requestWakeLock = async () => {
  try {
    wakeLock = await navigator.wakeLock.request();
    wakeLock.addEventListener('release', () => {
      console.log('Screen Wake Lock ha sido liberado:', wakeLock.released);
    });
    console.log('Screen Wake Lock ha sido liberado:', wakeLock.released);
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
};

// Pide un screen wake lock…
await requestWakeLock();
// …and release it again after 5s.
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 5000);

El objeto de WakeLockSentinel tiene una propiedad llamada released la cual indica si un centinela ya ha sido liberada. Su valor es inicialmente false y cambia a true una vez que se envía un evento de "release". Esta propiedad ayuda a los desarrolladores web a saber cuándo se ha liberado un bloqueo para que no tengan que realizar un seguimiento de esto manualmente. Esto está disponible a partir de Chrome 87.

# El ciclo de vida de screen wake lock

Cuando juegas con la demostración de screen wake lock, notarás que los screen wake locks son sensibles a la visibilidad de la página. Esto significa que el screen wake lock se liberará automáticamente cuando minimices una pestaña o ventana, o cuando cambies de una pestaña o ventana en la que esté activo un screen wake lock.

Para volver a adquirir el screen wake lock, escucha al evento de visibilitychange y solicita un nuevo screen wake lock cuando ocurra:

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 utilizar un bloqueo de activación de pantalla en tu aplicación? El enfoque que adoptes depende de las necesidades de tu aplicación. Independientemente, debes de utilizar el enfoque más ligero posible para tu aplicación para minimizar su impacto en los recursos del sistema.

Antes de agregar un screen wake lock a tu aplicación, considera si tus casos de uso podrían resolverse con una de las siguientes soluciones alternativas:

• Si tu aplicación está realizando descargas de larga duración, considera usar background fetch (recuperación en segundo plano).
• Si tu aplicación está sincronizando datos de un servidor externo, considera usar background sync (sincronización en segundo plano).

# Demostración

Echale un vistazo a la demostración de Screen Wake Lock y la fuente de la demostración. Observa cómo el screen wake lock se libera automáticamente cuando cambia de pestaña o aplicación.

# Screen Wake Locks en el administrador de tareas del sistema operativo

Puedes usar el administrador de tareas de tu sistema operativo para ver si una aplicación impide que tu computadora entre en suspensión. El video a continuación muestra el Monitor de actividad de macOS que indica que Chrome tiene screen wake lock activo que mantiene el sistema despierto.

# Retroalimentación

El Grupo Comunitario de Incubadora de Plataformas Web (WICG) y el equipo de Chrome desean conocer tus pensamientos 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 funcione como se esperaba? ¿O faltan métodos o propiedades que necesitas para implementar tu idea?

• Presenta un problema de especificación en el repositorio de GitHub de la API de Screen Wake Lock o agrega tus pensamientos a un problema existente.

# Reporta problemas con la implementación

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

• Reporta un error en https://new.crbug.com. Asegúrate de incluir todos los detalles que puedas, proporciona instrucciones sencillas para reproducir el error y configura los Componentes a Blink>WakeLock. Glitch funciona muy bien para compartir reproducciones rápidas y fáciles.

# Mostrar apoyo a la API

¿Estás pensando en utilizar la API de Screen Wake Lock? Tu apoyo público ayuda al equipo de Chrome a priorizar las funciones y muestra a otros proveedores de navegadores lo importante que es brindarles compatibilidad.

• Comparte cómo planeas usar la API en el hilo del discurso de WICG.
• Envía un tweet a @ChromiumDev usando el hashtag #WakeLock y déjanos saber dónde y cómo lo estás usando.

# Enlaces útiles

• Especificación de la Candidate Recommendation | Borrador del editor
• Demostración de Screen Wake Lock | Fuente de la demostración de Screen Wake Lock
• Error de seguimiento
• Entrada de ChromeStatus.com
• Experimentar con la API de Wake Lock
• Componente Blink: Blink>WakeLock

# Agradecimientos

Imagen de héroe de Kate Stone Matheson en Unsplash. Video del administrador de tareas, cortesía de Henry Lim .