Usar a API Screen Wake Lock

A API Wake Lock de tela oferece uma maneira de impedir que os dispositivos escureçam ou bloqueiem a tela quando um aplicativo precisa continuar funcionando.

Pete LePage
Thomas Steiner

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 ocioso. Embora isso seja aceitável na maioria das vezes, alguns aplicativos precisam manter a tela ativa para concluir o trabalho. Exemplos incluem apps de culinária que mostram as etapas de uma receita ou um jogo como o 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. Esse recurso 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 hackeadas e potencialmente com alto consumo de energia. Ela resolve as falhas de uma API mais antiga que se limitava 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

RioRun, um app da Web desenvolvido pelo The Guardian, foi um caso de uso perfeito (embora não esteja mais disponível). O app oferece um tour virtual em áudio do Rio, seguindo o percurso da maratona olímpica de 2016. Sem os bloqueios de ativação, as telas dos usuários seriam desligadas com frequência durante a apresentação, dificultando o uso.

É claro, 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 de ingresso que mantém a tela ativada até que o código de barras seja lido
  • Um app estilo quiosque que mantém a tela ligada continuamente
  • Um app de apresentação baseado na Web que mantém a tela ligada durante uma apresentação

Status atual

Etapa Status
1. Criar uma explicação N/A
2. Criar um rascunho inicial da especificação Concluído
3. Coletar feedback e iterar o design Concluído
4. Teste de origem Concluído
5. Lançar Concluído

Como usar a API Screen Wake Lock

Tipos de wake lock

No momento, a API Screen Wake Lock oferece apenas um tipo de bloqueio de tela: screen.

screen wake lock

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

Como ativar um bloqueio de ativação de tela

Para solicitar um bloqueio de ativação da tela, chame o método navigator.wakeLock.request() que retorna um objeto WakeLockSentinel. Você transmite a esse método o tipo de bloqueio de ativação desejado como um parâmetro, que atualmente é limitado apenas a 'screen' e, portanto, é opcional. O navegador pode recusar a solicitação por vários motivos (por exemplo, porque o nível de carga da bateria está muito baixo). Portanto, é uma boa prática agrupar a chamada em uma instrução try…catch. A mensagem da exceção vai conter 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, que é alcançado chamando o método release() do objeto WakeLockSentinel. Se você não armazenar uma referência ao WakeLockSentinel, não será possível liberar a trava manualmente, mas ela será liberada quando a guia atual ficar invisível.

Se você quiser liberar automaticamente o bloqueio de ativação da tela após um determinado período, use window.setTimeout() para chamar release(), conforme mostrado no exemplo abaixo.

// 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 uma sentinela já foi liberada. O valor é inicialmente false e muda para true quando um evento "release" é enviado. Essa propriedade ajuda os desenvolvedores da Web a saber quando uma trava foi liberada para que não precisem fazer o acompanhamento manualmente. Ele está disponível a partir do Chrome 87.

Ciclo de vida do bloqueio de ativação da tela

Ao brincar com a demonstração de bloqueio de ativação da tela, você vai notar que os bloqueios de ativação da tela são sensíveis à visibilidade da página. Isso significa que o wake lock de tela será liberado automaticamente quando você minimizar uma guia ou janela ou sair de uma guia ou janela em que um wake lock de tela estiver ativo.

Para recuperar o bloqueio de ativação da tela, detecte o evento visibilitychange e solicite um novo bloqueio de ativação da tela quando ele ocorrer:

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

document.addEventListener('visibilitychange', handleVisibilityChange);

Minimizar o impacto nos recursos do sistema

Você precisa usar um bloqueio de ativação de tela no seu app? O método escolhido depende das necessidades do app. No entanto, é recomendável usar a abordagem mais leve possível para minimizar o impacto no 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 da API Screen Wake Lock e a fonte da demonstração. Observe como o bloqueio de ativação da tela é liberado automaticamente quando você alterna entre guias ou apps.

Wake locks de tela no gerenciador de tarefas do SO

Você pode usar o gerenciador de tarefas do sistema operacional para saber se um aplicativo está impedindo o computador de entrar no modo de suspensão. O vídeo abaixo mostra o Monitor de atividades do macOS indicando que o Chrome tem um bloqueio de ativação da tela ativo que mantém o sistema acordado.

Feedback

O Grupo da comunidade do Incubador da plataforma da Web (WICG, na sigla em inglês) e a equipe do Chrome querem saber sua opinião e experiência com a API Screen Wake Lock.

Conte sobre o design da API

Há algo na API que não funciona como esperado? Ou há métodos ou propriedades ausentes que você precisa implementar para implementar sua ideia?

Informar um problema com a implementação

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

  • Registre um bug em https://new.crbug.com. Inclua o máximo de detalhes possível, forneça instruções simples para reproduzir o bug e defina Components como Blink>WakeLock. O Glitch é ótimo para compartilhar reprosagens rápidas e fáceis.

Mostrar suporte para a API

Você planeja usar a API Screen Wake Lock? Seu apoio público ajuda a equipe do Chrome a priorizar recursos e mostra a outros fornecedores de navegadores como é importante oferecer suporte a eles.

Links úteis

Agradecimentos

Imagem principal de Kate Stone Matheson no Unsplash. Vídeo do gerenciador de tarefas por Henry Lim.