Usar a API Screen Wake Lock

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

Pete LePage
Thomas Steiner

O que é a API Screen Wake Lock?

Para evitar o consumo da bateria, a maioria dos dispositivos entra em suspensão rapidamente quando fica inativo. 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 de alto consumo de energia. Ele aborda as deficiências de uma API mais antiga, que se limitava a simplesmente manter a tela ligada e apresentava 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 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 aplicativo de cartão de embarque ou de bilhetes que mantém a tela acesa 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 wake lock de tela, é necessário chamar o método navigator.wakeLock.request(), que retorna um objeto WakeLockSentinel. Você transmite a esse método o tipo de wake lock desejado como um parâmetro, que está limitado atualmente a apenas '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 no 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 wake lock de tela, detecte o evento visibilitychange e solicite um novo wake lock de 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ê deve usar um wake lock de tela no seu app? A abordagem adotada depende das necessidades do app. Seja qual for o caso, 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 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 de 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?

Mostrar suporte à 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.