Usar a API Screen Wake Lock

Pete LePage
Thomas Steiner

Publicado em: 18 de dezembro de 2018

Browser Support

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

Source

O que é a API Screen Wake Lock?

Para evitar o descarregamento da bateria, a maioria dos dispositivos entra em estado de suspensão rapidamente quando fica ociosa. Embora isso não seja um problema na maioria das vezes, alguns aplicativos precisam manter a tela ativa para concluir o trabalho. Por exemplo, apps de culinária que mostram as etapas de uma receita ou um jogo como Ball Puzzle, que usa as APIs de movimento do dispositivo para entrada.

A API Screen Wake Lock oferece uma maneira de impedir que o dispositivo escureça e bloqueie a tela. Essa capacidade permite novas experiências que, até agora, exigiam um app específico da plataforma.

A API Screen Wake Lock reduz a necessidade de soluções alternativas com hacks e potencialmente com alto consumo de energia. Ela aborda as deficiências de uma API mais antiga que era limitada a manter a tela ligada e tinha vários problemas de segurança e privacidade.

Casos de uso sugeridos para a API Screen Wake Lock

O RioRun, um web app desenvolvido pelo The Guardian, foi um caso de uso perfeito, mas não está mais disponível. O app faz um tour de áudio virtual pelo Rio de Janeiro, seguindo o percurso da maratona olímpica de 2016. Sem bloqueios de despertar, as telas dos usuários seriam desligadas com frequência durante a reprodução do tour, dificultando o uso.

É claro que há muitos outros casos de uso:

  • Um app de receitas que mantém a tela ligada enquanto você assa um bolo ou cozinha o jantar
  • Um app de cartão de embarque ou passagem que mantém a tela ligada até que o código de barras seja digitalizado
  • Um app de estilo quiosque que mantém a tela sempre ligada
  • Um app de apresentação baseado na Web que mantém a tela ligada durante uma apresentação

Usar a API Screen Wake Lock

A API Screen Wake Lock oferece apenas um tipo de wake lock: screen.

screen wake lock

Um bloqueio de ativação screen impede que a tela do dispositivo seja desligada para que o usuário possa ver as informações exibidas.

Receber um wake lock de tela

Para solicitar um bloqueio de despertar da tela, chame o método navigator.wakeLock.request() que retorna um objeto WakeLockSentinel. Opcionalmente, é possível transmitir o tipo, screen, como um parâmetro. O navegador pode recusar a solicitação por vários motivos (por exemplo, porque o nível de carga da bateria está muito baixo). Por isso, é recomendável envolver a chamada em uma instrução try...catch. A mensagem da exceção contém mais detalhes em caso de falha.

Liberar um wake lock de tela

Você também precisa de uma maneira de liberar o bloqueio de ativação da tela, o que é feito chamando o método release() do objeto WakeLockSentinel. Se você não armazenar uma referência ao WakeLockSentinel, não será possível liberar o bloqueio manualmente, mas ele será liberado quando a guia atual ficar invisível.

Se você quiser liberar automaticamente o bloqueio de despertar da tela depois de um determinado período, use window.setTimeout() para chamar release(), conforme mostrado no exemplo.

// 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);

O objeto WakeLockSentinel tem uma propriedade chamada released que indica se um sentinela já foi lançado. O valor inicial é false, e muda para true quando um evento "release" é enviado. Essa propriedade ajuda os desenvolvedores da Web a saber quando um bloqueio foi liberado, sem rastreamento manual.

O ciclo de vida do wake lock de tela

Ao jogar com a demonstração de bloqueio de ativação da tela, você pode ver que os bloqueios de ativação da tela são sensíveis à visibilidade da página. Isso significa que o wake lock de tela é liberado automaticamente quando você minimiza uma guia ou janela ou muda de uma guia ou janela em que um wake lock de tela está ativo.

Para adquirir novamente o wake lock da tela, ouça o evento visibilitychange e solicite um novo wake lock da tela quando eles ocorrerem:

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

document.addEventListener('visibilitychange', handleVisibilityChange);

Minimizar o impacto nos recursos do sistema

Você deve usar um bloqueio de despertar da tela no seu app? A abordagem escolhida depende das necessidades do app. No entanto, use a abordagem mais leve possível para minimizar o impacto nos recursos do sistema.

Antes de adicionar um wake lock de tela ao app, considere se os casos de uso podem ser resolvidos com uma das seguintes soluções alternativas:

Demonstração

Confira a demonstração do Screen Wake Lock e a fonte da demonstração. Observe como o bloqueio de ativação da tela é liberado automaticamente quando você troca de guias ou apps.

Wake locks de tela no gerenciador de tarefas do SO

Use o gerenciador de tarefas do seu sistema operacional para verificar se um aplicativo está impedindo que o computador entre em modo de suspensão. O vídeo mostra o Monitor de Atividade do macOS indicando que o Chrome tem um bloqueio de ativação de tela ativo que mantém o sistema ativo.

Feedback

Você encontrou um bug na implementação do Chrome? Ou a implementação é diferente da especificação?

  • Informar um bug. Forneça o máximo de detalhes possível. Dê instruções claras para reproduzir o bug e defina Componentes como Blink>WakeLock.

Recursos

Agradecimentos

Vídeo do gerenciador de tarefas cortesia de Henry Lim.