Usar a API Screen Wake Lock

A API Screen Wake Lock oferece uma maneira de evitar que os dispositivos escureçam ou bloqueiem a tela quando um aplicativo precisar 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 não seja um problema na maioria das vezes, alguns aplicativos precisam manter a tela ativada 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 evitar que o dispositivo escureça e bloqueie a tela. Esse recurso permite novas experiências que, até agora, precisavam de um app específico da plataforma.

A API Screen Wake Lock reduz a necessidade de soluções alternativas enganosas e que podem consumir muita energia. Ele aborda as deficiências de uma API mais antiga, que se limitava a manter a tela ligada e apresentava vários problemas de segurança e privacidade.

Casos de uso sugeridos para a API Screen Wake Lock

O RioRun, um app da Web desenvolvido pelo The Guardian, foi um caso de uso perfeito (embora não esteja mais disponível). O app leva você a um tour virtual de áudio do Rio, seguindo a rota da Maratona Olímpica de 2016. Sem os wake locks, as telas dos usuários eram desligadas com frequência durante o tour, o que dificultava o uso.

Claro, há muitos outros casos de uso:

  • Um app de receitas que mantém a tela acesa enquanto você assa um bolo ou cozinha o jantar
  • Um app de cartão de embarque ou de passagens que mantém a tela ativada até que o código de barras seja lido
  • Um aplicativo no estilo quiosque que mantém a tela ligada continuamente
  • Um aplicativo de apresentações baseado na Web que mantém a tela acesa durante uma apresentação

Status atual

Step Status
1. Criar explicação N/A
2. Criar rascunho inicial da especificação Concluído
3. Reunir feedbacks e iterar o design Concluído
4. Teste de origem Completos
5. lançamento Concluído

Como usar a API Screen Wake Lock

Tipos de wake lock

No momento, a API Screen Wake Lock fornece apenas um tipo de wake lock: o screen.

Wake lock screen

Um wake lock screen impede que a tela do dispositivo seja desativada para que o usuário possa conferir as informações mostradas na tela.

Como ter um wake lock de tela

Para solicitar um wake lock de tela, você precisa chamar o método navigator.wakeLock.request(), que retorna um objeto WakeLockSentinel. Transmita a esse método o tipo de wake lock desejado como parâmetro, que, atualmente, está limitado 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. 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 wake lock da tela, o que é feito chamando o método release() do objeto WakeLockSentinel. Se você não armazenar uma referência à WakeLockSentinel, não será possível liberar o bloqueio manualmente, mas ele será liberado quando a guia atual estiver invisível.

Se você quiser liberar automaticamente o wake lock de tela após um determinado período, você poderá usar 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. Inicialmente, o valor é 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 eles não precisem monitorar manualmente. Ela está disponível a partir do Chrome 87.

Ciclo de vida do wake lock da tela

Ao testar a demonstração do wake lock de tela, você vai perceber que os wake locks de tela são sensíveis à visibilidade da página. Isso significa que o wake lock de tela será automaticamente liberado quando você minimizar uma guia ou janela, ou sair de uma guia ou janela em que um wake lock de tela esteja ativo.

Para recuperar o wake lock de tela, ouça 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 seu impacto nos recursos do sistema

Você deve usar um wake lock de tela no app? A abordagem adotada depende das necessidades do app. Independentemente disso, use a abordagem mais leve possível para o app 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 soluções alternativas abaixo:

Demonstração

Confira a demonstração do Wake Lock e a origem da demonstração. Observe como o wake lock da tela é liberado automaticamente quando você muda de guia ou de app.

Wake locks de tela no gerenciador de tarefas do SO

Use o gerenciador de tarefas do seu sistema operacional para ver se um aplicativo está impedindo a suspensão do computador. O vídeo abaixo mostra o Monitor de atividades do macOS indicando que o Chrome tem um wake lock de tela ativo que mantém o sistema ativado.

Feedback

O Web Platform Incubator Community Group (WICG) e a equipe do Chrome querem saber o que vocês pensam e têm experiências 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 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 Componentes como Blink>WakeLock. O Glitch funciona muito bem para compartilhar repetições rápidas e fáceis.

Mostrar suporte à API

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

Links úteis

Agradecimentos

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