Cree una app que pertenezca a una pantalla

Si el runtime inyectado está adjunto. Cada documento comienza inert y cambia a active cuando llegan el apretón de manos y el contexto del Player; una página que aún no está en pantalla permanece inert. Espere active con screenrig.waitUntilActive(); no trate inert al cargar como "fuera de screenRIG". En failed, o cuando falta window.screenrig, renderice su propio contenido y omita la superficie inferior, para que la misma compilación también funcione fuera de screenRIG. Mientras inert, ready(), log(), emit(), emitConfirmed(), nextPage(), skip() y las lecturas y escrituras de kv lanzan o rechazan con código inert; kv.onChange puede registrarse en cualquier momento.

Tipo

"inert" | "active" | "failed"

Dónde se ejecuta este documento.

context es descripción, no material de solicitud. Nada en él está destinado a ser firmado, reenviado o enviado de vuelta a screenRIG; los métodos a continuación llevan lo que el tiempo de ejecución necesita.

Los parámetros de lanzamiento no forman parte de context: una lista de reproducción puede dar a una aplicación params (vea Tokens de pantalla en direcciones de iframe y params de aplicación), y el Player añade cada uno a la dirección de la página como parámetro de consulta después de ticket. Léalos desde location.search, por ejemplo new URLSearchParams(location.search).get("kiosk"). Son indicaciones, no credenciales, y cualquiera que pueda abrir la página puede enviar cualquier valor, así que trátelos como entrada no confiable; context.screen_id sigue siendo la forma de saber qué pantalla está reproduciendo. Los Players Qt, Android, Apple y Windows cargan una aplicación desde su paquete local, que no tiene dirección de lanzamiento, y no le pasan parámetros.

Diez booleanos que indican qué métodos restringidos harán algo para esta activación. Las claves están punteadas, así que léalas con notación de corchetes.

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

Suscríbase con onCapabilities en lugar de leer las banderas una vez al iniciar.

Tipo

objeto de booleanos

Llámelo primero, antes que cualquier otro método, y renderice su interfaz mientras espera. Se resuelve cuando el Player ha activado esta página, o inmediatamente si el tiempo de ejecución ya está active, y no declara la aplicación renderizada. Rechaza con activation_timeout después de timeoutMs (por defecto 10000, máximo 300000); una página que espera su turno puede simplemente esperar de nuevo. Inicie el sonido después de que se resuelva, porque el Player carga una aplicación antes de que se muestre su página: una pantalla cuyo navegador permite la reproducción automática lo inicia de inmediato, y en una que la rechaza, play() se rechaza con NotAllowedError; capture el error y reproduzca sin sonido.

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

Verifique readyState === "active" antes de una llamada SDK desde un controlador de eventos, temporizador o catch, y ponga en cola la entrada que llegue antes. Un log() de un controlador que se ejecuta mientras inert también lanza, lo que puede terminar el inicio antes de que se envíe cualquier evento.

Devuelve

Promise<void>

Llámelo después de que waitUntilActive() se resuelva y antes de depender de context, kv o nextPage, una vez que la aplicación tenga lo necesario para mostrarse. Si se llama mientras inert, lanza un error.

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

Devuelve

Promise<void>

Llámelo solo en una página de avance de aplicación donde esta primitiva es el controlador, cuando la aplicación haya terminado su turno. Es de un solo uso: una activación obtiene un avance.

window.screenrig.nextPage();

El método es para una página cuyo advance.mode es application, donde este primitivo es el controlador:

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

Exactamente un primitivo en esa página lleva controller: true y debe ser un primitivo de aplicación. max_ms en el objeto de avance de página delimita el turno.

Requiere

capabilities["page.advance"]

Devuelve

Promise<void>

Llámelo en lugar de ready() cuando la aplicación no tenga nada que mostrar por ahora. La pantalla pasa de inmediato a la siguiente con la transición normal de la página, y esta aparición no cuenta ninguna reproducción. Es una decisión de arranque: llámelo dentro de los diez segundos posteriores a la activación y antes de 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();
}

El controlador de la página, o la aplicación que está sola en su página, tiene la capacidad, en una página sin imágenes ni video. El método rechaza con capability_denied sin ella, con skip_after_ready una vez que se llamó a ready(), y con not_supported en un Player que no lo admite. Rechaza con forbidden cuando el Player conserva la página: el operador la retiene, la pantalla está apagada, ninguna otra página puede reproducirse, o todas las demás páginas también se han omitido. Entonces muestre su contenido alternativo y llame a ready(). Una lista de reproducción de mosaicos que se omiten todos muestra el último durante todo su tiempo en lugar de dar vueltas. El reason opcional (64 caracteres como máximo) aparece en el registro del Player del proyecto como player.application_skipped. skip() se incluye en el runtime que inyectan app pack y app upload, así que vuelva a empaquetar una versión para darle el método.

Requiere

capabilities["page.skip"]

Devuelve

Promise<void>

Úselo cuando el agente deba ver que algo sucedió: una página terminó un paso, se envió un formulario de kiosco, la aplicación demostró que se ejecutó. Este es un evento de aplicación nombrado, y llega al registro de eventos del proyecto donde el agente lo observa con el CLI incluido events list o events follow. Un código, sin cuerpo de mensaje.

log no es un sustituto. Un diagnóstico no es un evento de aplicación, y un agente que lea el registro de eventos no lo verá.

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

Los métodos emit() y emitConfirmed() del SDK añaden registros application.event cuyo recurso es la pantalla. Léalos con --type application.event y, opcionalmente, --screen-id. Los campos details.primitive_id y details.code devueltos identifican la primitiva emisora y la acción con nombre. --app-id selecciona eventos del recurso de aplicación, sus versiones y sus entradas K/V, por lo que excluye estos eventos de pantalla.

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

Devuelve

void

Úselo cuando la aplicación debe saber que el evento llegó: se realizó un pedido en el kiosco, se envió un formulario, una visita terminó. Envía el mismo evento de aplicación nombrado que emit, y su promesa se resuelve solo cuando el Player confirma que el backend aceptó el evento.

Rechaza con el problema del backend cuando se rechaza el evento, y con ack_timeout después de 10 segundos sin respuesta. No reintente automáticamente tras un tiempo de espera: el backend puede ya haber aceptado el evento. Un recibo prueba que el evento está en el registro de eventos del proyecto, no que algo haya actuado aún.

Los recibos funcionan en todos los Player que ejecutan aplicaciones.

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

Devuelve

Promise<void>

Úselo para diagnósticos: el debug, info, warn y error son textos que el Player y el runtime recopilan mientras la aplicación está en pantalla. El runtime inyectado registra a través de este método. El registro está limitado: 32 líneas por cliente y un máximo de 2048 bytes por mensaje. Registre lo que desearía mientras depura, no una línea por cuadro.

No use log cuando quiera decir emit. Los agentes no tratan las líneas de registro como eventos de aplicación, así que todo lo que el agente necesita procesar debe ir en un código emit.

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

Devuelve

void

Suscríbase cuando el diseño pueda cambiar bajo usted en lugar de leer context una vez. El manejador recibe { viewport, primitive }, los mismos dos objetos que context lleva, y la llamada devuelve la función que termina la suscripción.

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

stopResize();

Devuelve

función de cancelación de suscripción

Suscríbase cuando las capacidades concedidas puedan cambiar en lugar de decidir una vez al inicio. Lea screenrig.capabilities dentro del manejador para los booleanos actuales y habilite u oculte los controles afectados; la llamada devuelve la función que termina la suscripción.

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

Devuelve

función de cancelación de suscripción

Desmonte los escuchas cuando la aplicación termine con el tiempo de ejecución. Una aplicación que se ejecuta durante todo su turno y permite que el Player reemplace el documento no necesita llamarlo.

Devuelve

void

La tienda de clave/valor de la aplicación, para el estado en vivo de la aplicación que sobrevive a una activación. Cinco métodos propios: get, list, set, delete y onChange. Vea la tienda de clave/valor abajo.

Tipo

espacio de nombres

Leer estado en vivo de la aplicación. Espere la promesa.

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

Requiere

capabilities["kv.read"]

Devuelve

promesa

Leer estado en vivo de la aplicación cuando aún no conoce las claves: esto lista las claves que la aplicación ha almacenado. Espere la promesa.

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

Requiere

capabilities["kv.read"]

Devuelve

promesa

Escribir estado de aplicación en vivo. value es una cadena o un Uint8Array; options es opcional.

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

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

Requiere

capabilities["kv.write"]

Devuelve

promesa

Escribir estado de aplicación en vivo eliminando una entrada. expectedRevision es opcional: omítalo para eliminar la entrada actual, o proporciónelo para rechazar cambios concurrentes.

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

Requiere

capabilities["kv.write"]

Devuelve

promesa

Actualice el estado de la aplicación en vivo en el momento en que cambie en lugar de consultarlo periódicamente. El manejador se ejecuta cada vez que cambia cualquier clave de esta aplicación, quienquiera que la haya escrito: el agente con kv set, un sistema externo a través de un webhook clave/valor, o esta aplicación en cualquier pantalla. Recibe qué clave cambió, no el valor, así que lea el nuevo valor con kv.get. La llamada devuelve la función que termina la suscripción.

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

Suscríbase antes de la primera lectura, para que no se pierda un cambio que ocurra mientras lee; un manejador registrado antes de la activación comienza una vez que la página está activa. Llame a stopChanges() para finalizar la suscripción.

Un cambio llega a cada pantalla cuya lista de reproducción coloca esta aplicación en segundos. Varias escrituras rápidas a una clave pueden llegar como un cambio que lleva la revisión más reciente, así que trate un cambio como "lea esta clave de nuevo", no como un conteo de escrituras. Un cambio es una señal, no un historial: lea lo que necesite cuando la aplicación inicie, luego siga los cambios.

Requiere

capabilities["kv.read"]; sin esto el controlador nunca se ejecuta

Devuelve

función de cancelación de suscripción

Atenuar, oscurecer o activar la pantalla. brightness va de 0 a 1 (0 es lo más bajo que llega la retroiluminación, no apagado); on: false oscurece la pantalla y on: true la vuelve a encender. Omita un miembro para dejarlo como está. Los toques siguen llegando a la aplicación mientras la pantalla está oscura, así que un toque puede activarla. Un horario de pantalla que mantiene la pantalla oscura prevalece sobre la aplicación, y el Player restaura la pantalla cuando la página deja de mostrarse.

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

Se resuelve con

{ on, brightness }, la pantalla después de la llamada (brightness es null cuando el Player no puede leerlo); set({}) solo lee, y brightness conserva su valor mientras la pantalla está oscura

Requiere

capabilities["device.display"]

El estado actual de la pantalla, como { on, brightness }.

Requiere

capabilities["device.display"]

Se llama con { on, brightness } cada vez que cambia la pantalla, ya sea que la haya cambiado esta aplicación, un horario de pantalla o un operador.

Devuelve

función de cancelación de suscripción

Requiere

capabilities["device.display"]

Se llama cuando el dispositivo ve a alguien moverse frente a la pantalla, como máximo una vez por segundo. El Player lee la cámara del dispositivo y no conserva ninguna imagen: no se almacena, registra ni envía ninguna imagen. La cámara funciona solo mientras haya un manejador registrado.

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

Devuelve

función de cancelación de suscripción

Requiere

capabilities["device.presence"]

Se llama con "volume_up" o "volume_down" en cada pulsación de una tecla de volumen física, incluidas las repeticiones. Mientras haya un manejador registrado, las teclas pertenecen a la aplicación y el volumen del dispositivo no cambia.

Devuelve

función de cancelación de suscripción

Requiere

capabilities["device.keys"]

Se llama con la luz ambiental en lux: la primera lectura tras registrar el manejador y después cada vez que la luz cambia al menos un 10 % o en 1 lux, como máximo una vez por segundo. El dispositivo necesita un sensor de luz.

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

Devuelve

función de cancelación de suscripción

Requiere

capabilities["device.light"]

Se llama con true o false cada vez que el dispositivo obtiene o pierde la conectividad a internet validada por el sistema, y de inmediato con el estado actual cuando se registra el primer manejador.

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

Devuelve

función de cancelación de suscripción

Requiere

capabilities["device.network"]

Emita un pulso háptico. ms es un número entero de milisegundos de 1 a 200 y por defecto es 12. La promesa se resuelve sin valor cuando el Player ha iniciado la vibración, y se rechaza con invalid_request, sin enviar nada, para cualquier otro ms.

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

Se resuelve con

sin valor

Requiere

capabilities["device.haptics"]