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 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 ociosa. Embora isso seja bom na maioria das vezes, alguns aplicativos precisam manter a tela ativa para concluir o trabalho. Por exemplo, apps de receitas 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. 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 falhas e potencialmente consumidoras de energia. Ela aborda as deficiências de uma API mais antiga que era limitada a simplesmente 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 leva você a um tour de áudio virtual pelo Rio, seguindo o percurso da maratona olímpica de 2016. Sem bloqueios de despertar, as telas dos usuários seriam desligadas com frequência durante o 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 ativada 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

Status atual

Etapa Status
1. Criar explicação N/A
2. Criar o rascunho inicial da especificação Concluído
3. Coletar feedback e iterar o design Concluído
4. Teste de origem Concluído
5. Iniciar 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 despertar: 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 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. Você transmite a esse método o tipo de wake lock 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). Por isso, é uma boa prática incluir a chamada em uma instrução try…catch. A mensagem da exceção vai conter mais detalhes em caso de falha.

Como 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 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 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 para que não precisem acompanhar isso manualmente. Ele está disponível a partir do Chrome 87.

O ciclo de vida do wake lock de tela

Ao jogar 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 mudar 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? O método escolhido 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 seu 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 abaixo 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

O Web Platform Incubator Community Group (WICG) e a equipe do Chrome querem saber sua opinião e experiência com a API Screen Wake Lock.

Fale 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 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 Componentes como Blink>WakeLock.

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 a importância de oferecer suporte a eles.

Links úteis

Agradecimentos

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