Crea un’app che appartiene a uno schermo

Se il runtime iniettato è collegato. Ogni documento inizia inert e diventa active quando arrivano handshake e contesto del Player; una pagina non ancora su schermo resta inert. Aspetta active con screenrig.waitUntilActive(); non considerare inert al caricamento come “fuori screenRIG”. Su failed, o quando window.screenrig manca, mostra il tuo contenuto e salta la superficie sottostante, così la stessa build funziona anche fuori screenRIG. Mentre inert, ready(), log(), emit(), emitConfirmed(), nextPage(), skip() e kv leggono e scrivono lanciando o rifiutando con codice inert; kv.onChange può essere registrato in qualsiasi momento.

Tipo

"inert" | "active" | "failed"

Dove viene eseguito questo documento.

context è descrizione, non materiale di richiesta. Nulla in esso è destinato a essere firmato, inoltrato o inviato a screenRIG; i metodi seguenti portano ciò che il runtime richiede.

I parametri di avvio non fanno parte di context: una playlist può dare a un'applicazione params (vedi Token dello schermo negli indirizzi iframe e nei parametri dell'applicazione), e il Player aggiunge ciascuno all'indirizzo della pagina come parametro di query dopo ticket. Leggili da location.search, ad esempio new URLSearchParams(location.search).get("kiosk"). Sono suggerimenti, non credenziali, e chiunque possa aprire la pagina può inviare qualsiasi valore, quindi trattali come input non attendibile; context.screen_id resta il modo per sapere quale schermo sta riproducendo. I Player Qt, Android, Apple e Windows caricano un'applicazione dal pacchetto locale, che non ha un indirizzo di avvio, e non le passano parametri.

Dieci booleani che indicano quali metodi gated faranno qualcosa per questa attivazione. Le chiavi sono puntate, quindi leggile con la notazione a parentesi quadre.

if (window.screenrig.capabilities["kv.write"]) {
  saveButton.hidden = false;
}

Iscriviti con onCapabilities invece di leggere i flag una volta all’avvio.

Tipo

oggetto di booleani

Chiamalo per primo, prima di qualsiasi altro metodo, e rendi la tua UI mentre attende. Si risolve quando il Player ha attivato questa pagina, o subito se il runtime è già active, e non dichiara l’applicazione resa. Rifiuta con activation_timeout dopo timeoutMs (default 10000, massimo 300000); una pagina in attesa può semplicemente attendere di nuovo. Avvia l’audio dopo la risoluzione, perché il Player carica un’applicazione prima che la sua pagina compaia: uno schermo il cui browser consente la riproduzione automatica lo avvia subito, mentre su uno il cui browser la rifiuta play() viene rifiutato con NotAllowedError; intercetta l’errore e riproduci senza audio.

const sr = window.screenrig;
async function start() {
  render(); // the UI works with or without screenRIG
  if (!sr) return;
  for (;;) {
    try { await sr.waitUntilActive(60000); break; }
    catch (err) { if (err.code !== "activation_timeout") return; }
  }
  await sr.ready();
  // From here: emit, emitConfirmed, log, kv, nextPage.
}
start();

Controlla readyState === "active" prima di una chiamata SDK da un gestore eventi, timer o catch, e metti in coda l’input che arriva prima. Un log() da un gestore che gira mentre inert lancia un’eccezione, che può terminare l’avvio prima che venga inviato un evento.

Restituisce

Promise<void>

Chiamalo dopo che waitUntilActive() si risolve e prima di dipendere da context, kv o nextPage, una volta che l’applicazione ha ciò che serve per essere sullo schermo. Se chiamato durante inert, genera un errore.

await window.screenrig.waitUntilActive();
await window.screenrig.ready();

Restituisce

Promise<void>

Chiamalo solo su una pagina di avanzamento applicazione dove questa primitiva è il controller, quando l’applicazione ha finito il suo turno. È one-shot: un’attivazione ottiene un avanzamento.

window.screenrig.nextPage();

Il metodo è per una pagina il cui advance.mode è application, dove questa primitiva è il controller:

{
  "advance": { "mode": "application", "max_ms": 60000 },
  "primitives": [
    {
      "id": "app",
      "primitive": "application",
      "release_id": "rel_01EXAMPLERELEASE000000000",
      "rect": { "x": 0, "y": 0, "width": 1920, "height": 1080 },
      "layer": 0,
      "content_fit": "fill",
      "controller": true
    }
  ]
}

Esattamente una primitiva in quella pagina contiene controller: true e deve essere una primitiva applicativa. max_ms nella pagina avanza i limiti dell’oggetto turno.

Richiede

capabilities["page.advance"]

Restituisce

Promise<void>

Chiamalo al posto di ready() quando l’applicazione non ha nulla da mostrare in questo momento. Lo schermo passa subito oltre con la normale transizione della pagina e questa apparizione non conta alcuna riproduzione. È una decisione presa all’avvio: chiamalo entro dieci secondi dall’attivazione e prima di ready().

await window.screenrig.waitUntilActive();
const events = await loadToday();
if (events.length === 0) {
  await window.screenrig.skip("no events today");
} else {
  render(events);
  await window.screenrig.ready();
}

Il controller della pagina, o l’applicazione da sola sulla sua pagina, ha la capacità, su una pagina senza immagini né video. Il metodo rifiuta con capability_denied senza di essa, con skip_after_ready dopo che ready() è stato chiamato e con not_supported su un Player che non lo supporta. Rifiuta con forbidden quando il Player mantiene la pagina: l’operatore la trattiene, il display è spento, nessun’altra pagina può essere riprodotta o anche tutte le altre pagine sono state saltate. Mostra allora il tuo contenuto di ripiego e chiama ready(). Una playlist di riquadri che saltano tutti mostra l’ultimo per tutta la sua durata invece di girare in ciclo. Il reason facoltativo (al massimo 64 caratteri) compare nel log del Player del progetto come player.application_skipped. skip() è incluso nel runtime che app pack e app upload iniettano, quindi reimpacchetta una release per darle il metodo.

Richiede

capabilities["page.skip"]

Restituisce

Promise<void>

Usalo quando l’agente deve sapere che qualcosa è successo: una pagina ha completato un passaggio, un modulo kiosk è stato inviato, l’applicazione ha dimostrato di essere eseguita. Questo è un evento applicativo nominato, che arriva nel registro eventi del progetto dove l’agente lo osserva con la CLI inclusa events list o events follow. Un codice, nessun corpo messaggio.

log non è un sostituto. Una diagnostica non è un evento applicativo e un agente che legge il registro eventi non lo vedrà.

window.screenrig.emit("menu.rendered");

I metodi SDK emit() ed emitConfirmed() aggiungono record application.event la cui risorsa è lo schermo. Leggili con --type application.event, aggiungendo facoltativamente --screen-id. I campi restituiti details.primitive_id e details.code identificano la primitiva emittente e l’azione denominata. --app-id seleziona gli eventi della risorsa applicazione, delle release e delle voci K/V, quindi esclude questi eventi dello schermo.

screenrig events list --type application.event --screen-id scr_SCREEN

Restituisce

void

Usalo quando l’applicazione deve sapere che l’evento è arrivato: un ordine kiosk è stato effettuato, un modulo inviato, una visita terminata. Invia lo stesso evento applicativo nominato di emit, e la sua promessa si risolve solo quando il Player conferma che il backend ha accettato l’evento.

Rifiuta con il problema backend quando l’evento è rifiutato, e con ack_timeout dopo 10 secondi senza risposta. Non riprovare automaticamente dopo timeout: il backend potrebbe aver già accettato l’evento. Una ricevuta prova che l’evento è nel log eventi progetto, non che qualcosa abbia ancora agito su di esso.

Le ricevute funzionano su ogni Player che esegue applicazioni.

await window.screenrig.emitConfirmed("order.placed");

Restituisce

Promise<void>

Usalo per la diagnostica: il debug, info, warn e error sono testi che il Player e il runtime raccolgono mentre l’applicazione è sullo schermo. I log del runtime iniettato passano tramite questo metodo stesso. Il logging è limitato: 32 righe per client e al massimo 2048 byte per messaggio. Registra ciò che serve per il debug, non una riga per frame.

Non usare log quando intendi emit. Gli agenti non trattano le righe di log come eventi applicativi, quindi tutto ciò su cui l’agente deve agire appartiene a un codice emit.

window.screenrig.log({
  level: "warn",
  code: "menu.stale",
  message: "Falling back to the cached menu."
});

Restituisce

void

Iscriviti quando il layout può cambiare sotto di te invece di leggere context una volta. Il gestore riceve { viewport, primitive }, gli stessi due oggetti che porta context, e la chiamata restituisce la funzione che termina l’iscrizione.

const stopResize = window.screenrig.onResize(function (size) {
  render(size.viewport, size.primitive);
});

stopResize();

Restituisce

funzione unsubscribe

Iscriviti quando le capacità concesse possono cambiare invece di decidere una volta all’avvio. Leggi screenrig.capabilities dentro il gestore per i booleani correnti e abilita o nascondi i controlli interessati; la chiamata restituisce la funzione che termina l’iscrizione.

const stopCapabilities = window.screenrig.onCapabilities(function () {
  saveButton.hidden = !window.screenrig.capabilities["kv.write"];
});

Restituisce

funzione unsubscribe

Rimuovi i listener quando l’applicazione ha finito con il runtime. Un’applicazione che gira per tutto il suo turno e lascia che il Player sostituisca il documento non deve chiamarla.

Restituisce

void

Il key/value store dell’applicazione, per lo stato live dell’app che sopravvive a un’attivazione. Cinque metodi propri: get, list, set, delete e onChange. Vedi il key/value store sotto.

Tipo

namespace

Leggi lo stato live dell’applicazione. Attendi la promessa.

const entry = await window.screenrig.kv.get("menu");

Richiede

capabilities["kv.read"]

Restituisce

promessa

Leggi lo stato live dell’applicazione quando non conosci ancora le chiavi: questo elenca le chiavi memorizzate dall’applicazione. Attendi la promessa.

const keys = await window.screenrig.kv.list();

Richiede

capabilities["kv.read"]

Restituisce

promessa

Scrivi stato live dell’applicazione. value è una stringa o un Uint8Array; options è opzionale.

await window.screenrig.kv.set("menu", JSON.stringify(menu), {
  contentType: "application/json"
});

await window.screenrig.kv.set("badge.png", pngBytes, {
  contentType: "image/png"
});

Richiede

capabilities["kv.write"]

Restituisce

promessa

Scrivi stato live dell’applicazione rimuovendo una voce. expectedRevision è opzionale: omettilo per eliminare la voce corrente, o forniscilo per rifiutare modifiche concorrenti.

await window.screenrig.kv.delete("menu");

Richiede

capabilities["kv.write"]

Restituisce

promessa

Aggiorna lo stato live dell’applicazione al cambiamento invece di interrogarlo. Il gestore si attiva ogni volta che una chiave di questa applicazione cambia, chiunque l’abbia modificata: l’agente con kv set, un sistema esterno tramite un webhook chiave/valore, o questa applicazione su qualsiasi schermo. Riceve quale chiave è cambiata, non il valore, quindi leggi il nuovo valore con kv.get. La chiamata restituisce la funzione che termina l’iscrizione.

const sr = window.screenrig;

async function showMenu() {
  render(await sr.kv.get("menu"));
}

const stopChanges = sr.kv.onChange(function (change) {
  if (change.key === "menu" && !change.deleted) showMenu();
});

await sr.waitUntilActive();
await sr.ready();
await showMenu();

Iscriviti prima della prima lettura, così una modifica che arriva mentre leggi non viene persa; un gestore registrato prima dell’attivazione parte una volta che la pagina è attiva. Chiama stopChanges() per terminare l’iscrizione.

Una modifica raggiunge ogni schermo la cui playlist posiziona questa app entro secondi. Diverse scritture rapide a una chiave possono arrivare come una modifica che porta la revisione più recente, quindi considera una modifica come “leggi di nuovo questa chiave”, non come un conteggio di scritture. Una modifica è un segnale, non una storia: leggi ciò che serve all’avvio dell’app, poi segui le modifiche.

Richiede

capabilities["kv.read"]; senza di esso il gestore non viene mai eseguito

Restituisce

funzione unsubscribe

Attenuare, oscurare o riattivare il display. brightness va da 0 a 1 (0 è il livello più basso della retroilluminazione, non lo spegnimento); on: false oscura il display e on: true lo riaccende. Ometti un membro per lasciarlo com’è. I tocchi raggiungono comunque l’applicazione mentre il display è scuro, quindi un tocco può riattivarlo. Una programmazione del display che lo tiene scuro prevale sull’applicazione, e il Player ripristina il display quando la pagina lascia lo schermo.

await window.screenrig.device.display.set({ brightness: 0.3 });
await window.screenrig.device.display.set({ on: false });

Si risolve con

{ on, brightness }, il display dopo la chiamata (brightness è null quando il Player non riesce a leggerlo); set({}) si limita a leggere, e brightness mantiene il suo valore mentre il display è scuro

Richiede

capabilities["device.display"]

Lo stato attuale del display, come { on, brightness }.

Richiede

capabilities["device.display"]

Chiamato con { on, brightness } ogni volta che il display cambia, sia che lo abbia cambiato questa applicazione, una programmazione del display o un operatore.

Restituisce

funzione unsubscribe

Richiede

capabilities["device.display"]

Chiamato quando il dispositivo vede qualcuno muoversi davanti allo schermo, al massimo una volta al secondo. Il Player legge la fotocamera del dispositivo e non conserva alcuna immagine: nessuna immagine viene memorizzata, registrata nel log o inviata. La fotocamera è attiva solo finché è registrato un gestore.

window.screenrig.device.onPresence(function () {
  window.screenrig.device.display.set({ on: true, brightness: 1 });
});

Restituisce

funzione unsubscribe

Richiede

capabilities["device.presence"]

Chiamato con "volume_up" o "volume_down" a ogni pressione di un tasto volume fisico, ripetizioni incluse. Finché è registrato un gestore, i tasti appartengono all’applicazione e il volume del dispositivo resta com’è.

Restituisce

funzione unsubscribe

Richiede

capabilities["device.keys"]

Chiamato con la luce ambientale in lux: la prima lettura dopo la registrazione del gestore, poi ogni volta che la luce cambia di almeno il 10% o attraversa 1 lux, al massimo una volta al secondo. Il dispositivo deve avere un sensore di luce.

window.screenrig.device.onLight(function (lux) {
  document.body.classList.toggle("dim-room", lux < 10);
});

Restituisce

funzione unsubscribe

Richiede

capabilities["device.light"]

Chiamato con true o false ogni volta che il dispositivo ottiene o perde la connettività internet convalidata dal sistema, e subito con lo stato corrente quando viene registrato il primo gestore.

window.screenrig.device.onNetwork(function (online) {
  offlineBadge.hidden = online;
});

Restituisce

funzione unsubscribe

Richiede

capabilities["device.network"]

Riproduci un impulso aptico. ms è un numero intero di millisecondi da 1 a 200 e il valore predefinito è 12. La promessa si risolve senza valore non appena il Player ha avviato la vibrazione, e viene rifiutata con invalid_request, senza inviare nulla, per qualsiasi altro ms.

await window.screenrig.device.vibrate();
await window.screenrig.device.vibrate(40);

Si risolve con

nessun valore

Richiede

capabilities["device.haptics"]