Rimani attivo con l'API Screen Wake Lock

L'API Screen Wake Lock consente di impedire ai dispositivi di oscurare o bloccare lo schermo quando un'applicazione deve rimanere in esecuzione.

Pete LePage
Thomas Steiner

Che cos'è l'API Screen Wake Lock?

Per evitare di consumare la batteria, la maggior parte dei dispositivi entra rapidamente in modalità di sospensione quando non è attiva. Anche se questo va bene per la maggior parte del tempo, 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 consente di impedire al dispositivo di oscurare 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 ingannevoli e potenzialmente dispendiose di energia. Risponde ai difetti di un'API meno recente, che si limitava al semplice mantenimento dello 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, è stato un caso d'uso perfetto (anche se non è più disponibile). L'app ti permette di fare un tour audio virtuale di Rio, seguendo il percorso della maratona olimpica del 2016. Senza i wakelock, gli schermi degli utenti si disattivavano spesso durante la riproduzione del tour, rendendo difficile l'utilizzo.

Naturalmente, ci sono molti altri casi d'uso:

  • Un'app di ricette che mantiene lo schermo acceso mentre cucini una torta o cucini la cena
  • Un'app di carte d'imbarco o di biglietti che mantiene lo schermo attivo finché non viene scansionato il codice a barre
  • Un'app in stile kiosk che mantiene lo schermo acceso in modo continuo
  • Un'app di presentazione basata sul web che mantiene lo schermo acceso durante una presentazione

Stato attuale

Passaggio Stato
1. Crea messaggio esplicativo N/A
2. Crea una bozza iniziale della specifica Completato
3. Raccogli feedback e ottimizza il design Completato
4. Prova dell'origine Completo
5. Avvia Completato

Utilizzo dell'API Screen Wake Lock

Tipi di wakelock

L'API Screen Wake Lock attualmente fornisce un solo tipo di wakelock: screen.

Wakelock di screen

Un wakelock di screen impedisce allo schermo del dispositivo di disattivarsi in modo che l'utente possa vedere le informazioni visualizzate sullo schermo.

Attivazione del wakelock schermo

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

Rilascio di un wakelock schermo

Devi anche trovare un modo per rilasciare il blocco riattivazione schermo, che si ottiene chiamando il metodo release() dell'oggetto WakeLockSentinel. Se non memorizzi un riferimento a WakeLockSentinel, non è possibile rilasciare il blocco manualmente, ma verrà rilasciato una volta che la scheda corrente sarà invisibile.

Se vuoi rilasciare automaticamente il blocco riattivazione 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 una sentinel è già stata rilasciata. Il suo valore è inizialmente false e cambia in true una volta inviato un evento "release". Questa proprietà consente agli sviluppatori web di sapere quando è stato rilasciato un blocco, in modo che non debbano tenerne traccia manualmente. È disponibile a partire da Chrome 87.

Ciclo di vita del wakelock dello schermo

Quando giochi con la demo della funzionalità di riattivazione schermo, noterai che i wakelock dello schermo sono sensibili alla visibilità delle pagine. Ciò significa che il wakelock schermo verrà rilasciato automaticamente quando riduci a icona una scheda o una finestra oppure esci da una scheda o una finestra in cui è attivo il blocco riattivazione schermo.

Per riacquisire il wakelock schermo, ascolta l'evento visibilitychange e richiedi un nuovo blocco riattivazione schermo quando si verifica:

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 attivazione schermo nella tua app? L'approccio da adottare dipende dalle esigenze della tua app. In ogni caso, dovresti utilizzare l'approccio più leggero possibile per la tua app per ridurre al minimo il suo impatto sulle risorse di sistema.

Prima di aggiungere un wakelock schermo alla tua app, valuta se è possibile risolvere i tuoi casi d'uso con una delle seguenti soluzioni alternative:

Demo

Dai un'occhiata alla demo di Blocco attivazione schermo e alla fonte della demo. Osserva come il wakelock schermo viene rilasciato automaticamente quando cambi scheda o app.

Wakelock dello schermo nel Task Manager del sistema operativo.

Puoi utilizzare la gestione delle attività del sistema operativo per verificare se un'applicazione impedisce al computer di eseguire la sospensione. Il video seguente mostra la funzionalità Monitoraggio attività di macOS che indica che Chrome ha un wakelock dello schermo attivo che mantiene attivo il sistema.

Feedback

Il Web Platform Incubator Community Group (WICG) e il team di Chrome vogliono conoscere le tue opinioni ed esperienze con l'API Screen Wake Lock.

Parlaci della progettazione dell'API

C'è qualcosa nell'API che non funziona come previsto? Oppure mancano metodi o proprietà di cui hai bisogno per implementare la tua idea?

Segnala un problema con l'implementazione

Hai trovato un bug nell'implementazione di Chrome? Oppure l'implementazione è diversa dalle specifiche?

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

Mostra il supporto dell'API

Hai intenzione di utilizzare l'API Screen Wake Lock? Il tuo supporto pubblico aiuta il team di Chrome a dare la priorità alle funzionalità e mostra ad altri fornitori di browser quanto è fondamentale supportarle.

Link utili

Ringraziamenti

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