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 no modo suspenso rapidamente quando é deixado inativo. Embora isso não seja um problema na maioria das vezes, alguns aplicativos precisam manter com a tela acordado para concluir o trabalho. Por exemplo, apps de culinária que mostram as etapas de uma receita ou de um jogo como o Ball Puzzle, que usa o dispositivo Motion APIs para entrada.

A API Screen Wake Lock oferece uma maneira de impedir o escurecimento do dispositivo. e bloquear a tela. Isso permite novas experiências que, até agora, exigiam um app específico da plataforma.

A API Screen Wake Lock reduz a necessidade de hackers e potencialmente soluções alternativas que consomem muita energia. Ele aborda as deficiências de uma API mais antiga que se limitava a simplesmente manter a tela acesa e tinha várias problemas de segurança e privacidade.

Casos de uso sugeridos para a API Screen Wake Lock

RioRun (em inglês). um app da Web desenvolvido pelo The Guardian era um caso de uso perfeito (embora não esteja mais disponível). O aplicativo leva você em um tour de áudio virtual pelo Rio, seguindo a rota da Nação 2016 maratona olímpica. Sem os wake locks, os usuários telas se desligavam frequentemente enquanto o tour era reproduzido, dificultando o uso.

É claro que 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 ingressos que protege a tela até que o código de barras seja lido
  • Um aplicativo no estilo quiosque que mantém a tela ligada o tempo todo
  • Um aplicativo de apresentação baseado na web que mantém a tela durante uma apresentação
.

Status atual

Etapa Status
1. Criar explicação N/A
2. Criar um rascunho inicial da especificação Concluído
3. Reunir feedback e iterar o design Concluído
4. Teste de origem Concluído
5. lançamento 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 wake lock: screen.

Wake lock do screen

Um wake lock screen impede que a tela do dispositivo gire para que o usuário possa ver as informações exibidas na tela.

Receber um wake lock 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 atualmente está limitado a apenas 'screen' e, portanto, é opcional. O navegador pode recusar o pedido 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 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 wake lock de tela, que é conseguido chamando o Método release() do objeto WakeLockSentinel. Se você não armazenar uma referência ao WakeLockSentinel, não será possível para liberar o bloqueio manualmente, mas ele será liberado quando a guia atual estiver invisível.

Se quiser liberar automaticamente o wake lock de tela após um determinado período de tempo, você pode 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 com o nome released que indica se uma sentinela já foi liberada. Seu valor é inicialmente false e muda para true quando um "release" é despachado. Essa propriedade ajuda os desenvolvedores Web a saber quando um bloqueio foi lançado para que não precisem acompanhar isso manualmente. Ela está disponível a partir do Chrome 87.

O ciclo de vida do wake lock de tela

Ao brincar com a demonstração do wake lock de tela, você vai notar que os wake locks de tela são sensíveis à visibilidade da página. Isso significa que o wake lock de tela serão liberados automaticamente quando você minimizar 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, detectar o evento visibilitychange e solicite um novo wake lock de 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 wake lock de tela no seu app? A abordagem adotada depende das necessidades do seu app. Independentemente disso, você deve usar a abordagem mais leve possível para que seu aplicativo minimize a nos recursos do sistema.

Antes de adicionar um wake lock de tela ao seu app, considere se seus casos de uso poderiam pode ser resolvido com uma das seguintes soluções alternativas:

.

Demonstração

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

Wake locks de tela no gerenciador de tarefas do SO

Você pode usar o gerenciador de tarefas do seu sistema operacional para ver se um aplicativo está impedindo o computador do dispositivo à suspensão. O vídeo abaixo mostra o console do Monitor de atividade indicando que o Chrome tem um wake lock ativo de tela que mantém o sistema ativo.

Feedback

O Web Platform Incubator Community Group (WICG) (link em inglês) e a equipe do Chrome querem saber sobre seus ideias e experiências com a API Screen Wake Lock.

Fale sobre o design da API

Alguma coisa na API não funciona como esperado? Ou estão faltando métodos ou propriedades de 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 das especificações?

  • Registre um bug em https://new.crbug.com. Não deixe de incluir possível, fornecer instruções simples para reproduzir o bug e Defina Componentes como Blink>WakeLock. O Glitch funciona muito bem para compartilhar reproduções rápidas e fáceis.

Mostrar suporte à API

Você planeja usar a API Screen Wake Lock? Seu apoio público ajuda os A equipe do Chrome prioriza recursos e mostra a outros fornecedores de navegador como é crucial apoiá-las.

Links úteis

Agradecimentos

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