Crie um aplicativo que foi feito para uma tela

Se o runtime injetado está anexado. Todo documento começa inert e muda para active quando o handshake e o contexto do Player chegam; uma página que ainda não está na tela permanece inert. Aguarde active com screenrig.waitUntilActive(); não trate inert no carregamento como "fora do screenRIG". Em failed, ou quando window.screenrig está ausente, renderize seu próprio conteúdo e pule a superfície abaixo, assim a mesma build também roda fora do screenRIG. Enquanto inert, ready(), log(), emit(), emitConfirmed(), nextPage(), skip() e a leitura e escrita do kv lançam ou rejeitam com código inert; kv.onChange pode ser registrado a qualquer momento.

Tipo

"inert" | "active" | "failed"

Onde este documento está sendo executado.

context é descrição, não material de solicitação. Nada nele deve ser assinado, encaminhado ou enviado de volta para screenRIG; os métodos abaixo carregam o que o runtime precisa.

Os params de lançamento não fazem parte de context: uma playlist pode dar a um aplicativo params (veja Tokens de tela em endereços de iframe e params de aplicativo), e o Player anexa cada um ao endereço da página como parâmetro de query depois de ticket. Leia-os em location.search, por exemplo new URLSearchParams(location.search).get("kiosk"). São dicas, não credenciais, e qualquer pessoa que consiga abrir a página pode enviar qualquer valor, então trate-os como entrada não confiável; context.screen_id continua sendo a forma de saber qual tela está reproduzindo. Os Players Qt, Android, Apple e Windows carregam um aplicativo do seu pacote local, que não tem endereço de lançamento, e não lhe passam parâmetros.

Dez booleanos que indicam quais métodos restritos farão algo para esta ativação. As chaves são pontuadas, então leia-as com notação de colchetes.

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

Assine com onCapabilities em vez de ler as flags uma vez na inicialização.

Tipo

objeto de booleanos

Chame primeiro, antes de qualquer outro método, e renderize sua interface enquanto espera. Resolve quando o Player ativar esta página, ou imediatamente se o tempo de execução já estiver active, e não declara o aplicativo como renderizado. Rejeita com activation_timeout após timeoutMs (padrão 10000, no máximo 300000); uma página aguardando sua vez pode simplesmente esperar novamente. Inicie o som depois que resolver, porque o Player carrega um aplicativo antes de a página dele aparecer: uma tela cujo navegador permite a reprodução automática inicia o som na hora, e em uma cujo navegador a recusa, play() é rejeitado com NotAllowedError; capture o erro e reproduza sem som.

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 uma chamada SDK de um manipulador de eventos, timer ou catch, e enfileire a entrada que chegar antes. Um log() de um manipulador que roda enquanto inert também lança, o que pode terminar a inicialização antes de qualquer evento ser enviado.

Retorna

Promise<void>

Chame após waitUntilActive() resolver e antes de depender de context, kv ou nextPage, uma vez que o aplicativo tenha o que precisa para estar na tela. Se chamado durante inert, lança erro.

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

Retorna

Promise<void>

Chame apenas em uma página de avanço de aplicativo onde este primitivo é o controlador, quando o aplicativo terminou sua vez. É único: uma ativação gera um avanço.

window.screenrig.nextPage();

O método é para uma página cujo advance.mode é application, onde este primitivo é o 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
    }
  ]
}

Exatamente um primitivo nessa página contém controller: true, e deve ser um primitivo de aplicação. max_ms no objeto de avanço da página delimita a vez.

Exige

capabilities["page.advance"]

Retorna

Promise<void>

Chame-o em vez de ready() quando o aplicativo não tiver nada para mostrar agora. A tela segue de imediato para a próxima com a transição normal da página, e esta exibição não conta nenhuma reprodução. É uma decisão de início: chame-o até dez segundos depois da ativação e 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();
}

O controlador da página, ou o aplicativo que está sozinho na página, tem a capacidade, em uma página sem imagem nem vídeo. O método rejeita com capability_denied sem ela, com skip_after_ready depois que ready() foi chamado e com not_supported em um Player que não o tem. Rejeita com forbidden quando o Player mantém a página: o operador a segura, a tela está apagada, nenhuma outra página pode tocar ou todas as outras páginas também foram puladas. Renderize então seu conteúdo alternativo e chame ready(). Uma playlist de blocos que pulam todos mostra o último durante todo o seu tempo em vez de girar em ciclo. O reason opcional (no máximo 64 caracteres) aparece no log do Player do projeto como player.application_skipped. skip() vem no runtime que app pack e app upload injetam, então reempacote uma versão para dar o método a ela.

Exige

capabilities["page.skip"]

Retorna

Promise<void>

Use quando o agente deve ver que algo aconteceu: uma página terminou uma etapa, um formulário de quiosque foi enviado, a aplicação comprovou que rodou. Este é um evento nomeado da aplicação, que aparece no log de eventos do projeto onde o agente o acompanha com o CLI incluído events list ou events follow. Um código, sem corpo de mensagem.

log não é um substituto. Um diagnóstico não é um evento de aplicativo, e um agente lendo o log de eventos não o verá.

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

Os métodos emit() e emitConfirmed() do SDK adicionam registros application.event cujo recurso é a tela. Leia-os com --type application.event, adicionando --screen-id opcionalmente. Os campos retornados details.primitive_id e details.code identificam a primitiva emissora e a ação nomeada. --app-id seleciona eventos do recurso de aplicação, de suas versões e de suas entradas K/V, portanto exclui esses eventos de tela.

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

Retorna

void

Use quando a aplicação deve saber que o evento chegou: um pedido de quiosque foi feito, um formulário enviado, uma visita finalizada. Envia o mesmo evento nomeado da aplicação que emit, e sua promessa é resolvida somente quando o Player confirma que o backend aceitou o evento.

Rejeita com o problema do backend quando o evento é recusado, e com ack_timeout após 10 segundos sem resposta. Não tente novamente automaticamente após um timeout: o backend pode já ter aceitado o evento. Um recibo prova que o evento está no log de eventos do projeto, não que algo já tenha agido sobre ele.

Recibos funcionam em todo Player que executa aplicativos.

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

Retorna

Promise<void>

Use para diagnósticos: o debug, info, warn e error são textos que o Player e o runtime coletam enquanto a aplicação está na tela. O runtime injetado registra por este método. O registro é limitado: 32 linhas por cliente e no máximo 2048 bytes por mensagem. Registre o que você gostaria durante a depuração, não uma linha por quadro.

Não use log quando quiser dizer emit. Agentes não tratam linhas de log como eventos de aplicação, então tudo que o agente precisa agir deve estar em um código emit.

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

Retorna

void

Assine quando o layout pode mudar sob você em vez de ler context uma vez. O manipulador recebe { viewport, primitive }, os mesmos dois objetos que context carrega, e a chamada retorna a função que encerra a assinatura.

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

stopResize();

Retorna

função unsubscribe

Assine quando as capacidades concedidas podem mudar em vez de decidir uma vez na inicialização. Leia screenrig.capabilities dentro do manipulador para os booleanos atuais e habilite ou oculte os controles afetados; a chamada retorna a função que encerra a assinatura.

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

Retorna

função unsubscribe

Desmonte os ouvintes quando o aplicativo terminar com o runtime. Um aplicativo que roda por toda sua vez e deixa o Player substituir o documento não precisa chamar isso.

Retorna

void

A loja de chave/valor do aplicativo, para estado vivo do aplicativo que sobrevive a uma ativação. Cinco métodos próprios: get, list, set, delete e onChange. Veja a loja de chave/valor abaixo.

Tipo

namespace

Ler estado ao vivo do aplicativo. Aguarde a promessa.

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

Exige

capabilities["kv.read"]

Retorna

promessa

Ler estado ao vivo do aplicativo quando você ainda não conhece as chaves: isso lista as chaves que o aplicativo armazenou. Aguarde a promessa.

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

Exige

capabilities["kv.read"]

Retorna

promessa

Escreva o estado da aplicação ao vivo. value é uma string ou um Uint8Array; options é opcional.

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

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

Exige

capabilities["kv.write"]

Retorna

promessa

Escreva o estado da aplicação ao vivo removendo uma entrada. expectedRevision é opcional: omita para excluir a entrada atual ou forneça para rejeitar alterações concorrentes.

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

Exige

capabilities["kv.write"]

Retorna

promessa

Atualize o estado da aplicação ao vivo no momento da mudança em vez de consultá-lo periodicamente. O manipulador é executado sempre que qualquer chave desta aplicação muda, quem quer que a tenha escrito: o agente com kv set, um sistema externo por meio de um webhook de chave/valor, ou esta aplicação em qualquer tela. Ele recebe qual chave mudou, não o valor, então leia o novo valor com kv.get. A chamada retorna a função que encerra a inscrição.

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

Assine antes da primeira leitura, para que uma alteração que ocorra enquanto você lê não seja perdida; um manipulador registrado antes da ativação inicia assim que a página estiver ativa. Chame stopChanges() para encerrar a assinatura.

Uma mudança alcança toda tela cuja playlist coloca este aplicativo em segundos. Várias escritas rápidas para uma chave podem chegar como uma mudança carregando a revisão mais nova, então trate uma mudança como "leia esta chave novamente", não como uma contagem de escritas. Uma mudança é um sinal, não um histórico: leia o que precisar quando o aplicativo iniciar, então siga as mudanças.

Exige

capabilities["kv.read"]; sem ele o manipulador nunca é executado

Retorna

função unsubscribe

Reduzir o brilho, escurecer ou acordar a tela. brightness vai de 0 a 1 (0 é o mais baixo que a luz de fundo chega, não desligada); on: false escurece a tela e on: true a acende de novo. Omita um membro para deixá-lo como está. Os toques continuam chegando ao aplicativo enquanto a tela está escura, então um toque pode acordá-la. Uma programação de exibição que mantém a tela escura prevalece sobre o aplicativo, e o Player restaura a tela quando a página deixa de ser exibida.

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

Resolve com

{ on, brightness }, a tela depois da chamada (brightness é null quando o Player não consegue lê-lo); set({}) apenas lê, e brightness mantém seu valor enquanto a tela está escura

Exige

capabilities["device.display"]

O estado atual da tela, como { on, brightness }.

Exige

capabilities["device.display"]

Chamado com { on, brightness } sempre que a tela muda, seja por este aplicativo, por uma programação de exibição ou por um operador.

Retorna

função unsubscribe

Exige

capabilities["device.display"]

Chamado quando o dispositivo vê alguém se mover diante da tela, no máximo uma vez por segundo. O Player lê a câmera do dispositivo e não guarda nenhuma imagem: nenhuma imagem é armazenada, registrada em log ou enviada. A câmera só funciona enquanto houver um manipulador registrado.

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

Retorna

função unsubscribe

Exige

capabilities["device.presence"]

Chamado com "volume_up" ou "volume_down" a cada pressionamento de uma tecla física de volume, incluindo repetições. Enquanto houver um manipulador registrado, as teclas pertencem ao aplicativo e o volume do dispositivo permanece como está.

Retorna

função unsubscribe

Exige

capabilities["device.keys"]

Chamado com a luz ambiente em lux: a primeira leitura depois que o manipulador é registrado, depois sempre que a luz muda em pelo menos 10% ou em 1 lux, no máximo uma vez por segundo. O dispositivo precisa de um sensor de luz.

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

Retorna

função unsubscribe

Exige

capabilities["device.light"]

Chamado com true ou false sempre que o dispositivo ganha ou perde conectividade com a internet validada pelo sistema, e imediatamente com o estado atual quando o primeiro manipulador é registrado.

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

Retorna

função unsubscribe

Exige

capabilities["device.network"]

Emita um pulso háptico. ms é um número inteiro de milissegundos de 1 a 200 e o padrão é 12. A promessa é resolvida sem valor assim que o Player inicia a vibração, e é rejeitada com invalid_request, sem enviar nada, para qualquer outro ms.

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

Resolve com

sem valor

Exige

capabilities["device.haptics"]