Erstellen Sie eine App, die für einen Bildschirm bestimmt ist

Ob die injizierte Laufzeit angehängt ist. Jedes Dokument startet mit inert und wird active, wenn der Handshake und Kontext des Players eintreffen; eine Seite, die noch nicht auf dem Bildschirm ist, bleibt inert. Warten Sie auf active mit screenrig.waitUntilActive(); behandeln Sie inert beim Laden nicht als „außerhalb von screenRIG“. Bei failed oder wenn window.screenrig fehlt, rendern Sie Ihren eigenen Inhalt und überspringen Sie die darunterliegende Oberfläche, sodass derselbe Build auch außerhalb von screenRIG läuft. Während inert, ready(), log(), emit(), emitConfirmed(), nextPage(), skip() und das Lesen und Schreiben von kv mit Code inert werfen oder ablehnen; kv.onChange kann jederzeit registriert werden.

Typ

"inert" | "active" | "failed"

Wo dieses Dokument ausgeführt wird.

context ist Beschreibung, kein Anforderungsmaterial. Nichts darin soll signiert, weitergeleitet oder an screenRIG zurückgesendet werden; die untenstehenden Methoden tragen, was die Laufzeit benötigt.

Startparameter sind nicht Teil von context: Eine Playlist kann einer Anwendung params geben (siehe Bildschirm-Token in Iframe-Adressen und Anwendungsparametern), und der Player hängt jeden als Query-Parameter nach ticket an die Adresse der Seite an. Lesen Sie sie aus location.search, zum Beispiel new URLSearchParams(location.search).get("kiosk"). Sie sind Hinweise, keine Zugangsdaten, und jeder, der die Seite öffnen kann, kann beliebige Werte senden; behandeln Sie sie daher als nicht vertrauenswürdige Eingabe; context.screen_id bleibt der Weg, um zu erfahren, welcher Bildschirm spielt. Die Qt-, Android-, Apple- und Windows-Player laden eine Anwendung aus ihrem lokalen Paket, das keine Startadresse hat, und übergeben ihr keine Parameter.

Zehn Booleans, die angeben, welche gesperrten Methoden für diese Aktivierung etwas bewirken. Die Schlüssel sind gepunktet, lesen Sie sie mit der Klammernotation.

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

Abonnieren Sie mit onCapabilities anstelle des einmaligen Lesens der Flags beim Start.

Typ

Objekt aus Booleans

Rufen Sie es zuerst auf, vor jeder anderen Methode, und rendern Sie Ihre UI, während es wartet. Es wird aufgelöst, wenn der Player diese Seite aktiviert hat, oder sofort, wenn die Laufzeit bereits active ist, und es erklärt die Anwendung nicht als gerendert. Es lehnt mit activation_timeout nach timeoutMs ab (Standard 10000, maximal 300000); eine Seite, die auf ihren Zug wartet, kann einfach erneut warten. Starten Sie den Ton, nachdem es aufgelöst wurde, denn der Player lädt eine Anwendung, bevor ihre Seite erscheint: Ein Bildschirm, dessen Browser Autoplay erlaubt, startet ihn sofort; auf einem, dessen Browser es verweigert, wird play() mit NotAllowedError abgelehnt, fangen Sie den Fehler also ab und spielen Sie stumm ab.

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

Prüfen Sie readyState === "active" vor einem SDK-Aufruf aus einem Ereignishandler, Timer oder catch und fügen Sie Eingaben hinzu, die früher eintreffen. Ein log() von einem Handler, der während inert läuft, wirft ebenfalls eine Ausnahme, was den Start vor dem Senden eines Ereignisses beenden kann.

Gibt zurück

Promise<void>

Rufen Sie es nach der Auflösung von waitUntilActive() auf und bevor Sie von context, kv oder nextPage abhängen, sobald die Anwendung alles hat, was sie für die Anzeige benötigt. Wird während inert aufgerufen, löst es einen Fehler aus.

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

Gibt zurück

Promise<void>

Rufen Sie es nur auf einer Anwendungs-Advance-Seite auf, auf der dieses Primitive der Controller ist, wenn die Anwendung ihren Zug beendet hat. Es ist einmalig: eine Aktivierung erhält einen Advance.

window.screenrig.nextPage();

Die Methode ist für eine Seite, deren advance.mode application ist, wobei dieses Primitive der Controller ist:

{
  "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
    }
  ]
}

Genau ein Primitive auf dieser Seite trägt controller: true und es muss ein Anwendungsprimitive sein. max_ms auf dem Seitenfortschrittsobjekt begrenzt den Zug.

Erfordert

capabilities["page.advance"]

Gibt zurück

Promise<void>

Rufen Sie sie anstelle von ready() auf, wenn die Anwendung gerade nichts anzuzeigen hat. Der Bildschirm geht sofort mit dem normalen Übergang der Seite weiter, und dieser Auftritt zählt keine Wiedergabe. Es ist eine Entscheidung zum Start: Rufen Sie sie innerhalb von zehn Sekunden nach der Aktivierung und vor ready() auf.

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();
}

Der Controller der Seite oder die Anwendung, die allein auf ihrer Seite ist, besitzt die Berechtigung, auf einer Seite ohne Bild oder Video. Die Methode lehnt ohne sie mit capability_denied ab, mit skip_after_ready, sobald ready() aufgerufen wurde, und mit not_supported auf einem Player, der sie nicht kennt. Sie lehnt mit forbidden ab, wenn der Player die Seite behält: Der Operator hält sie fest, der Bildschirm ist dunkel, keine andere Seite kann laufen, oder alle anderen Seiten wurden ebenfalls übersprungen. Zeigen Sie dann Ihren Ersatzinhalt an und rufen Sie ready() auf. Eine Playlist aus Kacheln, die alle überspringen, zeigt die letzte in voller Dauer, statt im Kreis zu laufen. Der optionale reason (höchstens 64 Zeichen) erscheint im Player-Protokoll des Projekts als player.application_skipped. skip() kommt mit der Laufzeit, die app pack und app upload einfügen, packen Sie ein Release also neu, um ihm die Methode zu geben.

Erfordert

capabilities["page.skip"]

Gibt zurück

Promise<void>

Verwenden Sie es, wenn der Agent sehen soll, dass etwas passiert ist: eine Seite hat einen Schritt abgeschlossen, ein Kioskformular wurde abgeschickt, die Anwendung hat bewiesen, dass sie lief. Dies ist ein benanntes Anwendungsereignis, das im Ereignisprotokoll des Projekts landet, wo der Agent es mit dem mitgelieferten CLI events list oder events follow überwacht. Ein Code, keine Nachrichteninhalte.

log ist kein Ersatz. Eine Diagnose ist kein Anwendungsereignis, und ein Agent, der das Ereignisprotokoll liest, wird es nicht sehen.

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

Die SDK-Methoden emit() und emitConfirmed() fügen application.event-Datensätze hinzu, deren Ressource der Bildschirm ist. Lesen Sie diese mit --type application.event und optional --screen-id. Die zurückgegebenen Felder details.primitive_id und details.code identifizieren das sendende Primitive und die benannte Aktion. --app-id wählt Ereignisse der Anwendungsressource, ihrer Releases und K/V-Einträge aus und schließt diese Bildschirmereignisse daher aus.

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

Gibt zurück

void

Verwenden Sie es, wenn die Anwendung wissen muss, dass das Ereignis angekommen ist: eine Kioskbestellung wurde aufgegeben, ein Formular gesendet, ein Besuch beendet. Es sendet dasselbe benannte Anwendungsereignis wie emit, und sein Versprechen wird erst erfüllt, wenn der Player bestätigt, dass das Backend das Ereignis akzeptiert hat.

Sie lehnt mit dem Backend-Problem ab, wenn das Ereignis abgelehnt wird, und mit ack_timeout nach 10 Sekunden ohne Antwort. Nach einem Timeout nicht automatisch erneut versuchen: Das Backend hat das Ereignis möglicherweise bereits akzeptiert. Eine Empfangsbestätigung beweist, dass das Ereignis im Projekt-Ereignisprotokoll ist, nicht dass bereits etwas darauf reagiert hat.

Belege funktionieren auf jedem Player, der Anwendungen ausführt.

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

Gibt zurück

Promise<void>

Verwenden Sie es für Diagnosen: die debug, info, warn und error Texte, die der Player und die Laufzeit sammeln, während die Anwendung auf dem Bildschirm ist. Die injizierten Laufzeitprotokolle erfolgen über diese Methode selbst. Das Logging ist begrenzt: 32 Zeilen pro Client und maximal 2048 Bytes pro Nachricht. Protokollieren Sie, was Sie beim Debuggen benötigen, nicht eine Zeile pro Frame.

Greifen Sie nicht auf log zu, wenn Sie emit meinen. Agenten behandeln Protokollzeilen nicht als Anwendungsereignisse, daher gehört alles, worauf der Agent reagieren muss, in einen emit-Code.

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

Gibt zurück

void

Abonnieren, wenn sich das Layout unter Ihnen ändern kann, anstatt context einmal zu lesen. Der Handler erhält { viewport, primitive }, dieselben zwei Objekte, die context trägt, und der Aufruf gibt die Funktion zurück, die das Abonnement beendet.

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

stopResize();

Gibt zurück

Abmeldefunktion

Abonnieren, wenn sich die gewährten Fähigkeiten ändern können, anstatt einmalig beim Start zu entscheiden. Lesen Sie screenrig.capabilities im Handler für die aktuellen Booleans und aktivieren oder verbergen Sie die betroffenen Steuerelemente; der Aufruf gibt die Funktion zurück, die das Abonnement beendet.

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

Gibt zurück

Abmeldefunktion

Listener abbauen, wenn die Anwendung die Laufzeit beendet. Eine Anwendung, die ihre gesamte Runde läuft und den Player das Dokument ersetzen lässt, muss dies nicht aufrufen.

Gibt zurück

void

Der Schlüssel/Wert-Speicher der Anwendung für den Live-Anwendungszustand, der eine Aktivierung überdauert. Fünf eigene Methoden: get, list, set, delete und onChange. Siehe den Schlüssel/Wert-Speicher unten.

Typ

Namespace

Live-Anwendungsstatus lesen. Warten Sie auf das Versprechen.

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

Erfordert

capabilities["kv.read"]

Gibt zurück

Versprechen

Live-Anwendungsstatus lesen, wenn Sie die Schlüssel noch nicht kennen: Dies listet die vom Programm gespeicherten Schlüssel auf. Warten Sie auf das Versprechen.

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

Erfordert

capabilities["kv.read"]

Gibt zurück

Versprechen

Live-Anwendungsstatus schreiben. value ist ein String oder ein Uint8Array; options ist optional.

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

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

Erfordert

capabilities["kv.write"]

Gibt zurück

Versprechen

Live-Anwendungsstatus schreiben, indem ein Eintrag entfernt wird. expectedRevision ist optional: Lassen Sie ihn weg, um den aktuellen Eintrag zu löschen, oder geben Sie ihn an, um gleichzeitige Änderungen abzulehnen.

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

Erfordert

capabilities["kv.write"]

Gibt zurück

Versprechen

Aktualisieren Sie den Live-Anwendungsstatus bei Änderungen, anstatt ihn abzufragen. Der Handler wird ausgeführt, wann immer sich ein Schlüssel dieser Anwendung ändert, egal wer ihn geschrieben hat: der Agent mit kv set, ein externes System über einen Key/Value-Webhook oder diese Anwendung auf einem beliebigen Bildschirm. Er erhält, welcher Schlüssel sich geändert hat, nicht den Wert, daher lesen Sie den neuen Wert mit kv.get. Der Aufruf gibt die Funktion zurück, die das Abonnement beendet.

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

Abonnieren Sie vor der ersten Lektüre, damit eine Änderung, die während des Lesens eintrifft, nicht verpasst wird; ein vor der Aktivierung registrierter Handler startet, sobald die Seite aktiv ist. Rufen Sie stopChanges() auf, um das Abonnement zu beenden.

Eine Änderung erreicht jeden Bildschirm, dessen Playlist diese Anwendung innerhalb von Sekunden platziert. Mehrere schnelle Schreibvorgänge auf einen Schlüssel können als eine Änderung mit der neuesten Revision ankommen, behandeln Sie eine Änderung also als "Lese diesen Schlüssel erneut", nicht als Anzahl der Schreibvorgänge. Eine Änderung ist ein Signal, keine Historie: Lesen Sie, was Sie brauchen, wenn die Anwendung startet, und folgen Sie dann den Änderungen.

Erfordert

capabilities["kv.read"]; ohne dieses läuft der Handler nie

Gibt zurück

Abmeldefunktion

Den Bildschirm dimmen, abdunkeln oder aufwecken. brightness reicht von 0 bis 1 (0 ist die niedrigste Stufe der Hintergrundbeleuchtung, nicht aus); on: false dunkelt den Bildschirm ab und on: true schaltet ihn wieder ein. Lassen Sie ein Member weg, um es unverändert zu lassen. Berührungen erreichen die Anwendung weiterhin, während der Bildschirm dunkel ist, sodass eine Berührung ihn aufwecken kann. Ein Anzeigeplan, der den Bildschirm dunkel hält, hat Vorrang vor der Anwendung, und der Player stellt den Bildschirm wieder her, wenn die Seite ihn verlässt.

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

Wird aufgelöst mit

{ on, brightness }, der Bildschirm danach (brightness ist null, wenn der Player ihn nicht lesen kann); set({}) liest nur, und brightness behält seinen Wert, solange der Bildschirm dunkel ist

Erfordert

capabilities["device.display"]

Der aktuelle Zustand des Bildschirms als { on, brightness }.

Erfordert

capabilities["device.display"]

Wird mit { on, brightness } aufgerufen, sobald sich der Bildschirm ändert, ob diese Anwendung, ein Anzeigeplan oder ein Operator ihn geändert hat.

Gibt zurück

Abmeldefunktion

Erfordert

capabilities["device.display"]

Wird aufgerufen, wenn das Gerät sieht, dass sich jemand vor dem Bildschirm bewegt, höchstens einmal pro Sekunde. Der Player liest die Kamera des Geräts und behält kein Bild: Es wird kein Bild gespeichert, protokolliert oder gesendet. Die Kamera läuft nur, solange ein Handler registriert ist.

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

Gibt zurück

Abmeldefunktion

Erfordert

capabilities["device.presence"]

Wird mit "volume_up" oder "volume_down" bei jedem Druck auf eine Hardware-Lautstärketaste aufgerufen, Wiederholungen eingeschlossen. Solange ein Handler registriert ist, gehören die Tasten der Anwendung, und die Lautstärke des Geräts bleibt unverändert.

Gibt zurück

Abmeldefunktion

Erfordert

capabilities["device.keys"]

Wird mit dem Umgebungslicht in Lux aufgerufen: dem ersten Messwert nach der Registrierung des Handlers, danach jedes Mal, wenn sich das Licht um mindestens 10 % oder über 1 Lux hinweg ändert, höchstens einmal pro Sekunde. Das Gerät braucht einen Lichtsensor.

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

Gibt zurück

Abmeldefunktion

Erfordert

capabilities["device.light"]

Wird mit true oder false aufgerufen, sobald das Gerät eine vom System validierte Internetverbindung erhält oder verliert, und sofort mit dem aktuellen Zustand, wenn der erste Handler registriert wird.

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

Gibt zurück

Abmeldefunktion

Erfordert

capabilities["device.network"]

Einen haptischen Tick auslösen. ms ist eine ganze Zahl von Millisekunden von 1 bis 200 und hat den Standardwert 12. Das Versprechen wird ohne Wert erfüllt, sobald der Player die Vibration gestartet hat, und wird mit invalid_request abgelehnt, ohne etwas zu senden, für jeden anderen ms.

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

Wird aufgelöst mit

kein Wert

Erfordert

capabilities["device.haptics"]