スクリーンに属するアプリを構築

注入されたランタイムが接続されているか。すべてのドキュメントはinertで開始し、Playerのハンドシェイクとコンテキストが到着するとactiveに変わります。まだ画面上にないページはinertのままです。activeをscreenrig.waitUntilActive()で待ちます。読み込み時のinertは「screenRIG外」と見なさないでください。failedまたはwindow.screenrigがない場合は独自コンテンツをレンダリングし、下のサーフェスをスキップします。同じビルドがscreenRIG外でも動作します。inert、ready()、log()、emit()、emitConfirmed()、nextPage()、skip()およびkvの読み書きはコードinertで例外または拒否されます。kv.onChangeはいつでも登録可能です。

タイプ

"inert" | "active" | "failed"

このドキュメントが実行されている場所。

context は説明用であり、リクエスト用の情報ではありません。内容は署名や転送、screenRIG への返信を意図していません。必要な情報は下記のメソッドでランタイムに渡されます。

起動パラメーターは context には含まれません。プレイリストはアプリケーションに params（iframe アドレスとアプリケーションの params のスクリーントークンを参照）を与えることができ、Player は各パラメーターを ticket の後ろに、ページのアドレスのクエリパラメーターとして付加します。location.search から読み取ってください。例: new URLSearchParams(location.search).get("kiosk")。これらはヒントであって認証情報ではなく、ページを開ける人は任意の値を送れるため、信頼できない入力として扱ってください。どのスクリーンが再生中かは context.screen_id で知ります。Qt、Android、Apple、Windows の Player はローカルパッケージからアプリケーションを読み込み、そこには起動アドレスがなく、パラメーターも渡されません。

このアクティベーションで有効なメソッドが何かを示す10個のブール値です。キーはドット区切りなのでブラケット表記で読み取ってください。

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

起動時にフラグを一度読む代わりに、onCapabilitiesで購読してください。

タイプ

ブール値のオブジェクト

最初に呼び出し、他のメソッドの前に UI をレンダリングしながら待機します。 プレーヤーがこのページをアクティブにすると解決されます。すでにランタイムが active の場合は即時解決し、アプリのレンダリング完了は宣言しません。timeoutMs（デフォルト 10000、最大 300000）後に activation_timeout で拒否されます。順番待ちのページは再度待機可能です。音声は解決後に開始してください。Player はページが表示される前にアプリケーションを読み込むためです。ブラウザが自動再生を許可する画面ではすぐに開始され、拒否する画面では play() が NotAllowedError で拒否されるので、エラーを捕捉してミュートで再生してください。

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

イベントハンドラー、タイマー、catchからSDK呼び出しの前にreadyState === "active"をチェックし、早く到着した入力をキューに入れます。inert中に実行されるハンドラーからのlog()は例外を投げ、起動前にイベント送信を終了させることがあります。

返します

Promise<void>

waitUntilActive() 解決後、context、kv、nextPage に依存する前に呼び出します。アプリが画面に必要なものを持った時点で呼び出されます。inert の間に呼び出すと例外を投げます。

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

返します

Promise<void>

このプリミティブがコントローラーのアプリ進行ページでのみ呼び出します。アプリがターンを終えた時に呼び出します。一度きりで、アクティベーションは一回の進行を得ます。

window.screenrig.nextPage();

このメソッドはadvance.modeがapplicationのページ用で、このプリミティブがコントローラーです：

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

そのページの正確に1つのプリミティブが controller: true を持ち、かつそれはアプリケーションプリミティブでなければなりません。ページの max_ms はターンの境界を示します。

必要

capabilities["page.advance"]

返します

Promise<void>

アプリケーションが今は表示するものがないときは、ready()の代わりに呼び出します。画面はページの通常のトランジションですぐに次へ進み、この表示は再生として数えられません。開始時の判断です。アクティベーションから10秒以内、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();
}

ページのコントローラー、またはページ上で唯一のアプリケーションがこの権限を持ちます。画像や動画のないページが対象です。権限がないとcapability_denied、ready()の呼び出し後はskip_after_ready、この機能を持たないPlayerではnot_supportedで拒否されます。Playerがページを保持する場合（オペレーターが保持している、ディスプレイが消灯している、再生できる他のページがない、または他のすべてのページもスキップ済み）はforbiddenで拒否されます。その場合は代替表示を描画し、ready()を呼び出してください。すべてがスキップするタイルのプレイリストは、巡回せず最後の1つを全時間表示します。任意のreason（最大64文字）は、プロジェクトのPlayerログにplayer.application_skippedとして記録されます。skip()はapp packとapp uploadが注入するランタイムに含まれるため、リリースを再パックしてメソッドを追加してください。

必要

capabilities["page.skip"]

返します

Promise<void>

エージェントが何かが起きたことを知る必要があるときに使う：ページがステップを完了した、キオスクフォームが送信された、アプリが実行を証明した。これは名前付きアプリケーションイベントで、プロジェクトのイベントログに記録され、バンドルされたCLIの events list または events follow でエージェントが監視します。コードのみでメッセージ本文なし。

logは代替ではありません。診断はアプリケーションイベントではなく、イベントログを読むエージェントはそれを見ません。

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

SDKのemit()とemitConfirmed()は、スクリーンをリソースとするapplication.eventレコードを追加します。--type application.eventで読み取り、必要に応じて--screen-idを追加します。返されるdetails.primitive_idとdetails.codeは、送信元のプリミティブと名前付きアクションを識別します。--app-idはアプリケーションリソース、リリース、K/Vのイベントを選択するため、これらのスクリーンイベントは含みません。

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

返します

void

アプリケーションがイベントの受信を確認する必要があるときに使う：キオスク注文が行われた、フォームが送信された、訪問が終了した。emit と同じ名前付きアプリケーションイベントを送信し、Playerがバックエンドの受理を確認してから約束が解決されます。

イベントが拒否された場合はバックエンドの問題で拒否し、10秒間応答がなければack_timeoutで拒否します。タイムアウト後の自動再試行はしないでください：バックエンドはすでにイベントを受け入れている可能性があります。レシートはイベントがプロジェクトイベントログにあることを証明し、何かがそれに作用したことを示すものではありません。

レシートはアプリケーションを実行するすべてのプレーヤーで機能します。

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

返します

Promise<void>

診断に使う：debug、info、warn、error は、アプリがスクリーン上にある間にPlayerとランタイムが収集するテキストです。注入されたランタイムログもこの方法で記録されます。ログは制限あり：クライアントごとに32行、各メッセージは最大2048バイト。デバッグ時に必要な内容を記録し、フレームごとに1行は避けてください。

emit を意味するときに log に手を伸ばさないでください。エージェントはログ行をアプリケーションイベントとして扱わないため、エージェントが処理すべきものはすべて emit コード内に入ります。

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

返します

void

レイアウトが変わる場合に購読してください。一度だけcontextを読む代わりに。ハンドラーは{ viewport, primitive }を受け取り、contextが持つ同じ2つのオブジェクトを受け取ります。呼び出しは購読を終了する関数を返します。

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

stopResize();

返します

購読解除関数

付与された機能が変わる場合に購読してください。起動時に一度決める代わりに。現在の真偽値はハンドラー内のscreenrig.capabilitiesで読み、影響を受けるコントロールを有効化または非表示にします。呼び出しは購読を終了する関数を返します。

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

返します

購読解除関数

アプリケーションがランタイムを使い終わったらリスナーを解除します。アプリケーションが全ターン実行し、Player がドキュメントを置き換える場合は呼び出す必要はありません。

返します

void

アプリケーションのキー/バリューストアは、1回の起動を超えて持続するライブアプリケーション状態用です。5つの独自メソッド：get、list、set、delete、onChange。以下の キー/バリューストア を参照してください。

タイプ

namespace

ライブアプリケーションの状態を読む。 プロミスを待ちます。

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

必要

capabilities["kv.read"]

返します

promise

まだキーがわからないときにライブアプリケーションの状態を読む：これはアプリケーションが保存しているキーの一覧です。プロミスを待ちます。

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

必要

capabilities["kv.read"]

返します

promise

ライブアプリケーション状態を書き込む。 value は文字列か Uint8Array。options は任意です。

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

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

必要

capabilities["kv.write"]

返します

promise

ライブアプリケーション状態を書き込むにはエントリを削除します。expectedRevision は任意です：省略すると現在のエントリを削除し、指定すると同時変更を拒否します。

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

必要

capabilities["kv.write"]

返します

promise

ライブアプリケーション状態の変更時に即時更新し、ポーリングはしません。ハンドラーはこのアプリの任意のキーが変更されるたびに実行されます。作成者は kv set のエージェント、key/value webhook 経由の外部システム、または任意のスクリーン上のこのアプリです。変更されたキーのみ受け取り、値は受け取らないため、新しい値は kv.get で読みます。呼び出しは購読終了関数を返します。

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

最初の読み取り前に購読してください。そうしないと、読み取り中に発生した変更を見逃します。アクティベーション前に登録されたハンドラーはページがアクティブになると開始します。購読を終了するにはstopChanges()を呼び出してください。

変更は、このアプリケーションをプレイリストに配置しているすべてのスクリーンに数秒で届きます。1つのキーへの複数の素早い書き込みは、最新リビジョンを持つ1つの変更として届くことがあるため、変更は「このキーを再読込する」ものと考え、書き込み回数として扱わないでください。変更はシグナルであり履歴ではありません。アプリ起動時に必要なものを読み込み、その後は変更を追従してください。

必要

capabilities["kv.read"]；これがないとハンドラーは実行されません。

返します

購読解除関数

ディスプレイの明るさを下げる、暗くする、または復帰させる。brightness は 0 から 1 の値です（0 はバックライトの最低値で、消灯ではありません）。on: false は画面を暗くし、on: true は再び点灯します。省略したメンバーは現状のままです。画面が暗い間もタップはアプリケーションに届くため、タップで復帰させることができます。画面を暗いまま保持するディスプレイスケジュールはアプリケーションより優先され、ページが画面から離れると Player はディスプレイを元に戻します。

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

解決値

{ on, brightness }。呼び出し後のディスプレイの状態です（Player が読み取れない場合、brightness は null になります）。set({}) は読み取りのみを行い、画面が暗い間も brightness は値を保持します

必要

capabilities["device.display"]

現在のディスプレイの状態（{ on, brightness }）。

必要

capabilities["device.display"]

ディスプレイが変化するたびに { on, brightness } を渡して呼び出されます。変更したのがこのアプリケーション、ディスプレイスケジュール、オペレーターのいずれでも同様です。

返します

購読解除関数

必要

capabilities["device.display"]

デバイスが画面の前で誰かが動くのを検知したときに、最大で1秒に1回呼び出されます。Player はデバイスのカメラを読み取りますが、画像は保持しません。画像は保存、記録、送信されません。カメラはハンドラーが登録されている間だけ動作します。

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

返します

購読解除関数

必要

capabilities["device.presence"]

ハードウェアのボリュームキーが押されるたび（リピートを含む）に、"volume_up" または "volume_down" を渡して呼び出されます。ハンドラーが登録されている間、キーはアプリケーションのものとなり、デバイスの音量は変わりません。

返します

購読解除関数

必要

capabilities["device.keys"]

周囲の明るさをルクスで渡して呼び出されます。ハンドラーの登録後の最初の読み取り値で呼び出され、その後は光が 10% 以上、または 1 ルクスにわたって変化するたびに、最大で 1 秒に 1 回呼び出されます。デバイスには光センサーが必要です。

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

返します

購読解除関数

必要

capabilities["device.light"]

システムが検証済みのインターネット接続をデバイスが得たとき、または失ったときは常に true または false を渡して呼び出され、最初のハンドラーが登録されたときには現在の状態ですぐに呼び出されます。

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

返します

購読解除関数

必要

capabilities["device.network"]

触覚ティックを 1 回再生します。 ms は 1 から 200 までのミリ秒単位の整数で、デフォルトは 12 です。Player が振動を開始すると、プロミスは値なしで解決されます。それ以外の ms では、何も送信せずに invalid_request で拒否されます。

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

解決値

値なし

必要

capabilities["device.haptics"]