Créer une app qui appartient à un écran

Si le runtime injecté est attaché. Chaque document commence inert et devient active lorsque la poignée de main et le contexte du Player arrivent ; une page qui n’est pas encore affichée reste inert. Attendez active avec screenrig.waitUntilActive() ; ne considérez pas inert au chargement comme « hors screenRIG ». Sur failed, ou lorsque window.screenrig est absent, affichez votre propre contenu et sautez la surface ci-dessous, ainsi la même version fonctionne aussi hors screenRIG. Pendant inert, ready(), log(), emit(), emitConfirmed(), nextPage(), skip() et la lecture/écriture kv lèvent ou rejettent avec le code inert ; kv.onChange peut être enregistré à tout moment.

Type

"inert" | "active" | "failed"

Où ce document s’exécute.

context est une description, pas un matériel de demande. Rien dedans n’est destiné à être signé, transféré ou renvoyé à screenRIG ; les méthodes ci-dessous transportent ce dont le runtime a besoin.

Les params de lancement ne font pas partie de context : une liste de lecture peut donner à une application params (voir Jetons d’écran dans les adresses d’iframe et les params d’application), et le Player ajoute chacun à l’adresse de la page comme paramètre de requête après ticket. Lisez-les depuis location.search, par exemple new URLSearchParams(location.search).get("kiosk"). Ce sont des indications, pas des identifiants, et quiconque peut ouvrir la page peut envoyer n’importe quelle valeur, donc traitez-les comme une entrée non fiable ; context.screen_id reste le moyen de savoir quel écran est en lecture. Les Players Qt, Android, Apple et Windows chargent une application depuis leur paquet local, qui n’a pas d’adresse de lancement, et ne lui passent aucun param.

Dix booléens qui indiquent quelles méthodes protégées feront quelque chose pour cette activation. Les clés sont pointées, donc lisez-les avec la notation entre crochets.

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

Abonnez-vous avec onCapabilities au lieu de lire les indicateurs une fois au démarrage.

Type

objet de booléens

Appelez-le d’abord, avant toute autre méthode, et affichez votre interface pendant qu’il attend. Il se résout lorsque le Player a activé cette page, ou immédiatement si le runtime est déjà active, et il ne déclare pas l’application rendue. Il rejette avec activation_timeout après timeoutMs (par défaut 10000, au maximum 300000) ; une page en attente peut simplement attendre à nouveau. Démarrez le son après sa résolution, car le Player charge une application avant l’affichage de sa page : un écran dont le navigateur autorise la lecture automatique le démarre aussitôt, et sur un écran dont le navigateur la refuse, play() est rejeté avec NotAllowedError ; interceptez l’erreur et lisez en sourdine.

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

Vérifiez readyState === "active" avant un appel SDK depuis un gestionnaire d’événements, un minuteur ou catch, et mettez en file d’attente les entrées arrivant plus tôt. Un log() d’un gestionnaire qui s’exécute pendant inert lance aussi une exception, ce qui peut interrompre le démarrage avant qu’un événement ne soit envoyé.

Retourne

Promise<void>

Appelez-le après la résolution de waitUntilActive() et avant de dépendre de context, kv ou nextPage, une fois que l’application a ce qu’il faut pour être à l’écran. Appelé pendant inert, il lance une exception.

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

Retourne

Promise<void>

Appelez-le uniquement sur une page d’avancement d’application où cette primitive est le contrôleur, lorsque l’application a terminé son tour. C’est un coup unique : une activation obtient un avancement.

window.screenrig.nextPage();

La méthode est pour une page dont le advance.mode est application, où ce primitif est le contrôleur :

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

Exactement un primitif sur cette page porte controller: true, et il doit s’agir d’un primitif d’application. max_ms sur l’objet page advance borne le tour.

Requiert

capabilities["page.advance"]

Retourne

Promise<void>

Appelez-la à la place de ready() lorsque l’application n’a rien à afficher pour le moment. L’écran passe aussitôt à la suite avec la transition normale de la page, et cette apparition ne compte aucune lecture. C’est une décision prise au démarrage : appelez-la dans les dix secondes suivant l’activation et avant 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();
}

Le contrôleur de la page, ou l’application seule sur sa page, détient la capacité, sur une page sans image ni vidéo. La méthode rejette avec capability_denied sans elle, avec skip_after_ready une fois que ready() a été appelée, et avec not_supported sur un Player qui ne la prend pas en charge. Elle rejette avec forbidden lorsque le Player garde la page : l’opérateur la retient, l’écran est éteint, aucune autre page ne peut jouer, ou toutes les autres pages ont aussi été sautées. Affichez alors votre contenu de repli et appelez ready(). Une liste de lecture de tuiles qui sautent toutes affiche la dernière pendant toute sa durée au lieu de tourner en boucle. Le reason facultatif (64 caractères au plus) apparaît dans le journal du Player du projet sous player.application_skipped. skip() est fourni par le runtime que app pack et app upload injectent : réemballez une version pour lui donner la méthode.

Requiert

capabilities["page.skip"]

Retourne

Promise<void>

Utilisez-le quand l’agent doit voir qu’un événement s’est produit : une page a terminé une étape, un formulaire kiosque a été soumis, l’application a prouvé qu’elle a tourné. C’est un événement nommé de l’application, qui arrive dans le journal des événements du projet où l’agent le surveille avec la CLI fournie events list ou events follow. Un code, pas de corps de message.

log n’est pas un substitut. Un diagnostic n’est pas un événement d’application, et un agent lisant le journal des événements ne le verra pas.

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

Les méthodes emit() et emitConfirmed() du SDK ajoutent des enregistrements application.event dont la ressource est l’écran. Lisez-les avec --type application.event et, au besoin, --screen-id. Les champs details.primitive_id et details.code renvoyés identifient la primitive émettrice et l’action nommée. --app-id sélectionne les événements de la ressource d’application, de ses versions et de ses entrées clé/valeur, et exclut donc ces événements d’écran.

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

Retourne

void

Utilisez-le quand l’application doit savoir que l’événement est arrivé : une commande kiosque a été passée, un formulaire envoyé, une visite terminée. Il envoie le même événement nommé que emit, et sa promesse se résout uniquement une fois que le Player confirme que le backend a accepté l’événement.

Il rejette avec le problème du backend lorsque l'événement est refusé, et avec ack_timeout après 10 secondes sans réponse. Ne pas réessayer automatiquement après un délai : le backend peut déjà avoir accepté l'événement. Un reçu prouve que l'événement est dans le journal d'événements du projet, pas que quelque chose l'a encore traité.

Les reçus fonctionnent sur chaque Player qui exécute des applications.

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

Retourne

Promise<void>

Utilisez-le pour le diagnostic : le debug, info, warn et error sont les textes que le Player et le runtime collectent pendant que l’application est affichée. Le runtime injecté journalise lui-même par cette méthode. La journalisation est limitée : 32 lignes par client, et au maximum 2048 octets par message. Journalisez ce que vous voudriez voir en débogage, pas une ligne par image.

Ne pas utiliser log quand vous voulez dire emit. Les agents ne traitent pas les lignes de journal comme des événements d’application, donc tout ce dont l’agent doit agir appartient dans un code emit.

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

Retourne

void

S’abonner lorsque la disposition peut changer sous vos yeux au lieu de lire context une fois. Le gestionnaire reçoit { viewport, primitive }, les mêmes deux objets que context transporte, et l’appel retourne la fonction qui termine l’abonnement.

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

stopResize();

Retourne

fonction de désabonnement

S’abonner lorsque les capacités accordées peuvent changer au lieu de décider une fois au démarrage. Lisez screenrig.capabilities dans le gestionnaire pour les booléens actuels et activez ou masquez les contrôles affectés ; l’appel retourne la fonction qui termine l’abonnement.

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

Retourne

fonction de désabonnement

Démonter les écouteurs lorsque l’application a fini avec le runtime. Une application qui s’exécute pour tout son tour et laisse le Player remplacer le document n’a pas besoin de l’appeler.

Retourne

void

Le magasin clé/valeur de l’application, pour l’état d’application en direct qui survit à une activation. Cinq méthodes propres : get, list, set, delete, et onChange. Voir le magasin clé/valeur ci-dessous.

Type

espace de noms

Lire l’état en direct de l’application. Attendre la promesse.

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

Requiert

capabilities["kv.read"]

Retourne

promesse

Lire l’état en direct de l’application lorsque vous ne connaissez pas encore les clés : cela liste les clés que l’application a stockées. Attendre la promesse.

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

Requiert

capabilities["kv.read"]

Retourne

promesse

Écrire l’état de l’application en direct. value est une chaîne ou un Uint8Array ; options est optionnel.

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

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

Requiert

capabilities["kv.write"]

Retourne

promesse

Écrire l’état de l’application en direct en supprimant une entrée. expectedRevision est optionnel : omettez-le pour supprimer l’entrée actuelle, ou fournissez-le pour rejeter les modifications concurrentes.

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

Requiert

capabilities["kv.write"]

Retourne

promesse

Mettre à jour l’état de l’application en direct dès qu’il change au lieu de le sonder. Le gestionnaire s’exécute chaque fois qu’une clé de cette application change, quel que soit l’auteur : l’agent avec kv set, un système externe via un webhook clé/valeur, ou cette application sur n’importe quel écran. Il reçoit la clé modifiée, pas la valeur, donc lisez la nouvelle valeur avec kv.get. L’appel retourne la fonction qui termine l’abonnement.

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

Abonnez-vous avant la première lecture, ainsi un changement survenant pendant votre lecture ne sera pas manqué ; un gestionnaire enregistré avant l’activation démarre dès que la page est active. Appelez stopChanges() pour terminer l’abonnement.

Un changement atteint chaque écran dont la liste de lecture place cette application en quelques secondes. Plusieurs écritures rapides sur une clé peuvent arriver comme un seul changement portant la révision la plus récente, donc traitez un changement comme « relire cette clé », pas comme un compte d’écritures. Un changement est un signal, pas un historique : lisez ce dont vous avez besoin au démarrage de l’application, puis suivez les changements.

Requiert

capabilities["kv.read"] ; sans cela, le gestionnaire ne s’exécute jamais

Retourne

fonction de désabonnement

Atténuer, assombrir ou réveiller l’écran. brightness va de 0 à 1 (0 est le niveau le plus bas du rétroéclairage, pas l’extinction) ; on: false assombrit l’écran et on: true le rallume. Omettez un membre pour le laisser tel quel. Les touchers atteignent toujours l’application tant que l’écran est sombre : un toucher peut donc le réveiller. Une programmation d’affichage qui garde l’écran sombre l’emporte sur l’application, et le Player rétablit l’affichage lorsque la page quitte l’écran.

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

Se résout avec

{ on, brightness }, l’écran après l’appel (brightness vaut null lorsque le Player ne peut pas le lire) ; set({}) se contente de lire, et brightness conserve sa valeur tant que l’écran est sombre

Requiert

capabilities["device.display"]

L’état actuel de l’écran, sous la forme { on, brightness }.

Requiert

capabilities["device.display"]

Appelé avec { on, brightness } chaque fois que l’écran change, que ce soit par cette application, par une programmation d’affichage ou par un opérateur.

Retourne

fonction de désabonnement

Requiert

capabilities["device.display"]

Appelé lorsque l’appareil voit quelqu’un bouger devant l’écran, au plus une fois par seconde. Le Player lit la caméra de l’appareil et ne garde aucune image : aucune image n’est stockée, journalisée ni envoyée. La caméra ne fonctionne que tant qu’un gestionnaire est enregistré.

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

Retourne

fonction de désabonnement

Requiert

capabilities["device.presence"]

Appelé avec "volume_up" ou "volume_down" à chaque pression d’une touche de volume matérielle, répétitions comprises. Tant qu’un gestionnaire est enregistré, les touches appartiennent à l’application et le volume de l’appareil reste inchangé.

Retourne

fonction de désabonnement

Requiert

capabilities["device.keys"]

Appelé avec la lumière ambiante en lux : la première mesure après l’enregistrement du gestionnaire, puis chaque fois que la lumière varie d’au moins 10 % ou de 1 lux, au plus une fois par seconde. L’appareil doit avoir un capteur de lumière.

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

Retourne

fonction de désabonnement

Requiert

capabilities["device.light"]

Appelé avec true ou false chaque fois que l’appareil obtient ou perd une connectivité Internet validée par le système, et immédiatement avec l’état actuel lorsque le premier gestionnaire est enregistré.

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

Retourne

fonction de désabonnement

Requiert

capabilities["device.network"]

Jouer un tic haptique. ms est un nombre entier de millisecondes de 1 à 200 et vaut 12 par défaut. La promesse se résout sans valeur une fois que le Player a lancé la vibration, et rejette avec invalid_request, sans rien envoyer, pour tout autre ms.

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

Se résout avec

aucune valeur

Requiert

capabilities["device.haptics"]