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 continuare in esecuzione.

Pete LePage
Thomas Steiner

Che cos'è l'API Screen Wake Lock?

Per evitare di esaurire la batteria, la maggior parte dei dispositivi passa rapidamente in modalità di sospensione quando è inattiva. 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, è stato 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 acceso mentre prepari una torta o cucini
  • Un'app per tessere di imbarco o biglietti che mantiene lo schermo attivo 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'animazione esplicativa 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. lancio 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.

Wakelock di screen

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

Recupero di un wakelock 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.

Rilascio di un wakelock dello schermo

Devi anche trovare un modo per rilasciare il wakelock dello schermo, che si ottiene 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à consente agli sviluppatori web di sapere quando è stato rilasciato un blocco, in modo che non sia necessario tenerne traccia manualmente. È disponibile a partire da Chrome 87.

Ciclo di vita del blocco risveglio dello schermo

Quando esegui la demo del 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 wakelock dello schermo, ascolta l'evento visibilitychange e richiedi un nuovo wakelock dello 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 di attivazione schermo nella tua app? L'approccio da adottare dipende dalle esigenze della tua app. In ogni caso, dovresti usare l'approccio più leggero possibile per ridurre al minimo il suo 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:

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.

Blocchi di attivazione schermo nel Task Manager del sistema operativo

Puoi utilizzare Task Manager del sistema operativo per verificare se un'applicazione impedisce al computer di eseguire la sospensione. Il video seguente mostra il Monitoraggio attività di macOS che indica che Chrome ha un wakelock 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.

Parlaci della progettazione dell'API

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

Segnala 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.