Fique acordado com a API Screen Wake Lock

# O que é a API Screen Wake Lock?

Para evitar esgotar a bateria, a maioria dos dispositivos adormece rapidamente quando fica ociosa. Embora isso seja normal na maioria das vezes, alguns aplicativos precisam manter a tela ativada para concluir seu trabalho. Os exemplos incluem aplicativos 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 fornece uma maneira de evitar que o dispositivo escureça e bloqueie a tela. Esse recurso permite novas experiências que, até agora, exigiam um aplicativo específico da plataforma.

A API Screen Wake Lock reduz a necessidade de 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 ligada e tinha uma série de problemas de segurança e privacidade.

# Casos de uso sugeridos para a API Screen Wake Lock

O RioRun, um aplicativo da web desenvolvido pelo The Guardian, era um caso de uso perfeito (embora não esteja mais disponível). O aplicativo leva você por um áudio tour virtual pelo Rio de Janeiro, acompanhando o percurso da maratona olímpica de 2016. Sem os wake locks, as telas dos usuários desligariam com frequência durante o tour, tornando-o difícil de usar.

Claro, há muitos outros casos de uso:

• Um aplicativo de receitas que mantém a tela ligada enquanto você assa um bolo ou prepara o jantar
• Um aplicativo de cartão de embarque ou bilhete que mantém a tela ligada até que o código de barras seja lido
• Um aplicativo estilo quiosque que mantém a tela continuamente
• Um aplicativo de apresentação baseado na web que mantém a tela ligada durante uma apresentação

# Status atual

# Usando a API Screen Wake Lock

# Tipos de wake lock

A API Screen Wake Lock fornece atualmente apenas um tipo de wake lock: a screen.

# screen wake lock

Um screen evita que a tela do dispositivo desligue para que o usuário possa ver as informações que são exibidas na tela.

# Detecção de recursos

O suporte do navegador para a API Screen Wake Lock pode ser testado da seguinte forma:

if ('wakeLock' in navigator) {
  // Screen Wake Lock API supported 🎉
}

# Como obter um wake lock da tela

Para solicitar um bloqueio de ativação da tela, você precisa chamar o navigator.wakeLock.request() que retorna um objeto WakeLockSentinel Você passa este 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), portanto, é uma boa prática encerrar a chamada em uma instrução try…catch. A mensagem de exceção conterá mais detalhes em caso de falha.

# Liberando um wake lock da tela

Você também precisa de uma maneira de liberar o bloqueio de ativação da tela, que é obtido chamando o método release() do objeto WakeLockSentinel. Se você não armazenar uma referência ao WakeLockSentinel, não há como liberar o bloqueio manualmente, mas ele será liberado assim que a guia atual ficar invisível.

Se desejar liberar automaticamente o bloqueio de ativação da tela após um certo 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 WakeLockSentinel tem uma propriedade chamada released que indica se uma sentinela já foi liberada. Seu valor é inicialmente false e muda para true assim que um "release" é despachado. Esta propriedade ajuda os desenvolvedores da web a saber quando um bloqueio foi liberado, para que não precisem controlar isso manualmente. Ele está disponível a partir do Chrome 87.

# O ciclo de vida do wake lock da tela

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

Para readquirir o bloqueio de ativação da tela, ouça o visibilitychange e solicite um novo bloqueio de ativação da tela quando eles ocorrerem:

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

document.addEventListener('visibilitychange', handleVisibilityChange);

# Minimize o seu impacto nos recursos do sistema

Você deve usar um bloqueio de ativação de tela em seu aplicativo? A abordagem que você adota depende das necessidades do seu aplicativo. Independentemente disso, você deve usar a abordagem mais leve possível para seu aplicativo para minimizar seu impacto nos recursos do sistema.

Antes de adicionar um wake lock de tela ao seu aplicativo, considere se seus casos de uso podem ser resolvidos com uma das seguintes soluções alternativas:

• Se seu aplicativo estiver realizando downloads de longa duração, considere o uso de busca em segundo plano.
• Se seu aplicativo estiver sincronizando dados de um servidor externo, considere o uso de sincronização em segundo plano.

# Demo

Confira a demonstração do Screen Wake Lock e o código-fonte da demonstração. Observe como o bloqueio de ativação da tela é liberado automaticamente quando você alterna entre guias ou aplicativos.

# Screen Wake Locks no gerenciador de tarefas do sistema operacional

Você pode usar o gerenciador de tarefas do sistema operacional para ver se um aplicativo está impedindo o computador de hibernar. O vídeo abaixo mostra o macOS Activity Monitor indicando que o Chrome tem um wake lock de tela ativo que mantém o sistema ativo.

# Feedback

O Web Platform Incubator Community Group (WICG) e a equipe do Chrome desejam saber mais sobre seus pensamentos e experiências com a API Screen Wake Lock.

# Conte-nos sobre o design da API

Existe algo na API que não funciona conforme o esperado? Ou faltam métodos ou propriedades de que você precisa para implementar sua ideia?

• Registre um problema de especificação no repositório GitHub da API Screen Wake Lock ou adicione suas ideias a um problema existente.

# Comunicar 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. Certifique-se de incluir o máximo de detalhes possível, fornecer instruções simples para reproduzir o bug e definir Componentes como Blink>WakeLock. O Glitch funciona muito bem para compartilhar reproduções rápidas e fáceis.

# Mostrar suporte para a API

Você está planejando usar a API Screen Wake Lock? Seu apoio público ajuda a equipe do Chrome a priorizar os recursos e mostra a outros fornecedores de navegadores como é fundamental apoiá-los.

• Compartilhe como você planeja usar a API no thread do WICG Discourse.
• Envie um tweet para @ChromiumDev usando a hashtag #WakeLock e diga-nos onde e como você está usando a API.

# Links úteis

• Especificação da recomendação do candidato | Rascunho do Editor
• Demonstração do Screen Wake Lock | Código-fonte da demonstração do Screen Wake Lock
• Bug de rastreamento
• Entrada ChromeStatus.com
• Experimentando a API Wake Lock
• Componente Blink: Blink>WakeLock

# Reconhecimentos

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