Rimani attivo con l'API Screen Wake Lock

L'API Screen Wake Lock fornisce un modo per impedire ai dispositivi di oscurare o bloccare lo schermo quando un'applicazione deve continuare a funzionare.

Che cos'è l'API Screen Wake Lock?

Per evitare di scaricare la batteria, la maggior parte dei dispositivi entra rapidamente in modalità sospensione quando non viene utilizzata. Sebbene nella maggior parte dei casi non ci siano problemi, alcune applicazioni devono mantenere attivo lo schermo per completare il loro lavoro. Alcuni esempi sono le app di cucina che mostrano i passaggi di una ricetta o un gioco come Ball Puzzle, che utilizza le API di movimento del dispositivo per l'input.

L'API Screen Wake Lock fornisce un modo per impedire al dispositivo di attenuare e bloccare lo schermo. Questa funzionalità consente nuove esperienze che, finora, richiedevano un'app specifica per la piattaforma.

L'API Screen Wake Lock riduce la necessità di soluzioni alternative poco sicure e potenzialmente molto dispendiose in termini di energia. Risolve le carenze di un'API precedente che si limitava a mantenere semplicemente acceso lo schermo e presentava una serie di problemi di sicurezza e privacy.

Casi d'uso suggeriti per l'API Screen Wake Lock

RioRun, un'app web sviluppata da The Guardian, era un caso d'uso perfetto (anche se non è più disponibile). L'app ti accompagna in un tour audio virtuale di Rio, seguendo il percorso della maratona olimpica del 2016. Senza i blocchi di attivazione, gli schermi degli utenti si spegnerebbero di frequente durante la riproduzione del tour, rendendolo difficile da usare.

Naturalmente, esistono molti altri casi d'uso:

  • Un'app di ricette che mantiene lo schermo attivo mentre cucini una torta o la cena
  • Un'app per tessere di imbarco o biglietti che mantiene attivo lo schermo fino alla scansione del codice a barre
  • Un'app in stile chiosco che mantiene lo schermo sempre attivo
  • Un'app di presentazione basata sul web che mantiene attivo lo schermo durante una presentazione

Stato attuale

Passaggio Stato
1. Creare un video esplicativo N/D
2. Creare una bozza iniziale della specifica Completato
3. Raccogli i feedback e esegui l'iterazione del design Completato
4. Prova dell'origine Completa
5. Avvia Completato

Utilizzo dell'API Screen Wake Lock

Tipi di wakelock

Al momento l'API Screen Wake Lock fornisce un solo tipo di blocco sveglia: screen.

screen wake lock

Un screen blocco riattivazione impedisce lo spegnimento dello schermo del dispositivo in modo che l'utente possa vedere le informazioni visualizzate sullo schermo.

Ottenere un blocco risveglio dello schermo

Per richiedere un blocco di attivazione dello schermo, devi chiamare il metodo navigator.wakeLock.request() che restituisce un oggetto WakeLockSentinel. A questo metodo viene passato come parametro il tipo di blocco di riattivazione desiderato, che attualmente è limitato solo a 'screen' ed è quindi facoltativo. Il browser può rifiutare la richiesta per vari motivi (ad esempio perché il livello di carica della batteria è troppo basso), quindi è buona norma racchiudere la chiamata in un'istruzione try…catch. Il messaggio dell'eccezione conterrà ulteriori dettagli in caso di errore.

Rilasciare un blocco risveglio dello schermo

Devi anche avere un modo per rilasciare il blocco sveglia dello schermo, che viene ottenuto chiamando il metodo release() dell'oggetto WakeLockSentinel. Se non memorizzi un riferimento a WakeLockSentinel, non c'è modo di sbloccare manualmente la serratura, ma verrà sbloccata quando la scheda corrente non sarà visibile.

Se vuoi rilasciare automaticamente il blocco sveglia dello schermo dopo un determinato periodo di tempo, puoi utilizzare window.setTimeout() per chiamare release(), come mostrato nell'esempio seguente.

// 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);

L'oggetto WakeLockSentinel ha una proprietà denominata released che indica se è già stato rilasciato un'sentinella. Il valore è inizialmente false e diventa true quando viene inviato un evento "release". Questa proprietà aiuta gli sviluppatori web a sapere quando è stato rilasciato un blocco in modo da non dover tenere traccia manualmente. È disponibile a partire da Chrome 87.

Ciclo di vita del blocco risveglio dello schermo

Quando esegui la demo di blocco schermo, noterai che i blocchi schermo sono sensibili alla visibilità della pagina. Ciò significa che il wakelock dello schermo verrà rilasciato automaticamente quando riduci a icona una scheda o una finestra o esci da una scheda o una finestra in cui è attivo un wakelock dello schermo.

Per acquisire nuovamente il blocco schermo attivo, ascolta l'evento visibilitychange e richiedi un nuovo blocco schermo attivo quando si verificano:

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

document.addEventListener('visibilitychange', handleVisibilityChange);

Riduci al minimo l'impatto sulle risorse di sistema

Dovresti usare un blocco di attivazione schermo nella tua app? L'approccio che scegli dipende dalle esigenze della tua app. In ogni caso, devi utilizzare l'approccio più leggero possibile per la tua app per ridurre al minimo l'impatto sulle risorse di sistema.

Prima di aggiungere un blocco schermo alla tua app, valuta se i tuoi casi d'uso possono essere risolti con una delle seguenti soluzioni alternative:

  • Se la tua app esegue download di lunga durata, ti consigliamo di utilizzare il recupero in background.
  • Se la tua app sincronizza i dati da un server esterno, ti consigliamo di utilizzare la sincronizzazione in background.

Demo

Dai un'occhiata alla demo di Screen Wake Lock e al codice sorgente della demo. Nota che il blocco di attivazione dello schermo viene rilasciato automaticamente quando cambi scheda o app.

Wakelock dello schermo nel task manager del sistema operativo

Puoi utilizzare il Task Manager del sistema operativo per verificare se un'applicazione impedisce al computer di entrare in modalità di sospensione. Il video di seguito mostra Activity Monitor su macOS che indica che Chrome ha un blocco di attivazione dello schermo attivo che mantiene attivo il sistema.

Feedback

Il gruppo della community dell'incubatore della piattaforma web (WICG) e il team di Chrome vogliono conoscere le tue opinioni e le tue esperienze con l'API Screen Wake Lock.

Fornisci informazioni sul design dell'API

C'è qualcosa nell'API che non funziona come previsto? In alternativa, mancano metodi o proprietà necessari per implementare la tua idea?

Segnalare un problema con l'implementazione

Hai trovato un bug nell'implementazione di Chrome? Oppure l'implementazione è diversa dalla specifica?

  • Segnala un bug all'indirizzo https://new.crbug.com. Assicurati di includere il maggior numero possibile di dettagli, fornisci istruzioni semplici per riprodurre il bug e imposta Componenti su Blink>WakeLock. Glitch è perfetto per condividere riproduzioni rapide e semplici.

Mostra il supporto per l'API

Intendi utilizzare l'API Screen Wake Lock? Il tuo sostegno pubblico aiuta il team di Chrome a dare la priorità alle funzionalità e mostra ad altri fornitori di browser quanto sia importante supportarle.

Link utili

Ringraziamenti

Immagine hero di Kate Stone Matheson su Unsplash. Video di Task Manager per gentile concessione di Henry Lim.