HTMLパネルのページを作る

HTMLパネルで表示するページを作り、ルームに表示するまでの手順を説明します。

手順の概要

ページを表示するルームのオリジンを確認します。
ページにagentスクリプトを組み込みます。
ページとページが読み込むファイルを、sandboxで表示できるように配信します。
ルームのCSPで、ページのオリジンを許可します。
SpokeでHTML Panel Elementを配置し、ルームで確認します。

ルームのオリジンを確認する

agentには、ページを表示してよいルームのオリジンを指定します。オリジンは、ルームを開いたときにブラウザーのアドレスバーに表示されるURLのうち、https://からドメイン（ポート番号がある場合はポート番号）までの部分です。たとえば、ルームのURLがhttps://example.metatell.app/AbCdEfGの場合、オリジンはhttps://example.metatell.appです。

ルームのURLがリダイレクトされる場合は、リダイレクトされた後のURLのオリジンを使います。本番環境と検証環境など、複数の環境のルームで同じページを表示する場合は、すべての環境のオリジンを確認します。

agentスクリプトを組み込む

ページの<head>の先頭に、次の<script>タグを追加します。 data-host-originには、確認したルームのオリジンを指定します。

<!doctype html>
<html lang="ja">
  <head>
    <script
      type="module"
      src="https://cdn.jsdelivr.net/npm/@urth/[email protected]/lib/agent-script.js"
      data-host-origin="https://example.metatell.app"
    ></script>
    <meta charset="utf-8" />
    <title>パネルのページ</title>
  </head>
  <body>
    ...
  </body>
</html>

agentは、ページ自身のスクリプトより前に実行する必要があります。ページのほかの<script>タグより前に置いてください。

複数のオリジンを指定する場合は、空白で区切ります。

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@urth/[email protected]/lib/agent-script.js"
  data-host-origin="https://example.metatell.app https://staging.example.metatell.app"
></script>

data-host-originには、オリジンを正確に書いてください。末尾に/やパスを付けるなど、オリジンでない値が1つでも含まれていると、agentは起動しません。

警告

data-host-originには、信頼できるルームの決まったオリジンだけを指定してください。 agentは、ページの見た目を指定したオリジンへ送ります。ページのURLのパラメーターなど、外部から変えられる値をそのまま指定しないでください。

バンドルに組み込む場合

ページをビルドツールでバンドルする場合は、npmパッケージからagentを読み込むこともできます。

npm install @urth/three-html-panel

ページのエントリーポイントの先頭で、ほかのコードより前にstartAgent()を呼び出します。

import { startAgent } from "@urth/three-html-panel/agent";

startAgent({ hostOrigin: ["https://example.metatell.app"] });

CDNを使わない場合は、node_modules/@urth/three-html-panel/lib/agent-script.jsを自分のサーバーから配信します。 <script>タグのsrcには、そのファイルのURLを指定します。

ページを配信する

metatellのルームは、パネルのページをいつもsandboxの<iframe>で開きます。 iframeのsandbox属性はallow-scripts allow-forms allow-popupsで、allow-same-originは付きません。そのため、ページは不透明なオリジン（null）で動きます。ページと、ページが読み込むファイルを、次のように配信してください。

HTTPSで配信する

ページはHTTPSで配信します。 HTTPのページは表示されません。

ページにsandboxのCSPを付ける

ページのHTMLのレスポンスに、次のヘッダーを付けることをおすすめします。

Content-Security-Policy: sandbox allow-scripts allow-forms allow-popups

このヘッダーがあると、ページのURLを直接開いた場合も、ルームで表示した場合と同じsandboxの中で動きます。

ページが読み込むファイルにCORSのヘッダーを付ける

ページの中から読み込むファイルへのリクエストは、オリジンnullから送られます。画像、スタイルシート、Webフォント、動画などのファイルには、次のヘッダーを付けてください。

Access-Control-Allow-Origin: *

このヘッダーがない画像はパネルに描かれません。動画は、ポスター画像だけが表示されます。

ページから自分のAPIを呼び出す場合も、APIのレスポンスにCORSのヘッダーが必要です。

状態はサーバーで管理する

sandboxの中のページでは、CookieとlocalStorageを利用できません。ページの状態を保持する必要がある場合は、ページのサーバーで管理してください。

参加者は、それぞれ別々にページを開きます。投票の集計など、参加者の間で共有する状態も、ページのサーバーで管理します。

ルームのCSPでページのオリジンを許可する

ページのオリジンがルームのオリジンと異なる場合は、ルームのCSPのframe-srcにページのオリジンを追加します。追加しないと、ブラウザーがiframeの読み込みをブロックし、パネルは表示されません。

CSPを変更できるのは、組織ロールが管理者の場合です。設定方法は、Content Security Policy（CSP）の設定を参照してください。

ルームで確認する

シーンの制作者に、ページのURLを伝えます。URLはhttps://で始まる絶対URLです。
シーンの制作者が、SpokeでHTML Panel Elementを配置し、シーンを公開します。
ルームに入室し、パネルにページが表示されることを確認します。
パネルの上でクリック、スクロール、文字入力ができることを確認します。

ページの大きさ

HTML Panel ElementのWidth (px)とHeight (px)が、ページをレイアウトする画面の大きさになります。ページは、この大きさのブラウザーの画面で表示されたときと同じようにレイアウトされます。シーン制作者と、ページをデザインする大きさを決めておいてください。

パネルの描画は、幅と高さが大きいほど重くなります。大きな値を設定するより、小さめの画面に合わせて文字やボタンを大きくデザインしてください。描画が軽くなり、3D空間でも読みやすくなります。 DOMの要素が少ないほど、見た目のコピーも速くなります。

リンク

ページ内のリンクのうち、ページと同じオリジンのリンクはパネルの中で開きます。リンク先のページにもagentが必要です。ほかのオリジンのリンクは、ブラウザーの新しいタブで開きます。ルームと同じオリジンへのリンクは、ページと同じオリジンであっても新しいタブで開きます。

パネルの中で開いたページが15秒以内に接続しない場合、パネルは元のページに戻ります。 PDFやagentのないページへのリンクがこれにあたります。このとき、ルームの開発者ツールのコンソールにhtml-panel:で始まるメッセージが出ます。

キーボードとフォーカス

sandboxの中のページは、キーボードのフォーカスを自分から取れません。入力欄が文字入力を受け取るのは、参加者がパネルを押した直後だけです。参加者が押した入力欄のほか、ボタンを押した直後にページのスクリプトがフォーカスを当てた入力欄も、文字入力を受け取ります。 VRでは、パネルの入力欄に文字を入力できません。ページが読み込まれたときに入力欄へ自動でフォーカスを当てる処理は、パネルでは動作しません。

表示できないもの

agentはページのDOMとCSSをコピーして描くため、次のものは表示できません。

ページ内に埋め込んだ、ほかのオリジンのiframe（動画プレーヤー、地図、広告、ソーシャルログインのボタンなど）
ブラウザーが描くネイティブのUI（日付の選択画面、動画のコントロールなど）。<select>の選択肢の一覧は表示されます
CORSのヘッダーがない、ほかのオリジンの画像、スタイルシート、Webフォント
backdrop-filter

CSSのトランジションは、アニメーションせずに終わりの状態で表示されます。詳しい制限は、@urth/three-html-panelのREADMEを参照してください。

表示されない場合

確認すること	対処
ページのURL	`https://`で始まる絶対URLかを確認します。
agentの組み込み	ページのURLをブラウザーで直接開き、開発者ツールのコンソールに`[three-html-panel]`で始まる警告が出ていないかを確認します。
`data-host-origin`	ルームのオリジンと完全に一致しているかを確認します。開発環境など、別の環境のオリジンを指定していないかも確認します。
ルームのCSP	ルームの開発者ツールのコンソールに、`frame-src`によるブロックのエラーが出ていないかを確認します。
ルームのコンソール	ルームの開発者ツールのコンソールに、`html-panel:`で始まるメッセージが出ていないかを確認します。agentが一定時間内に接続しない場合も、ここに表示されます。
画像やフォント	表示されない画像やフォントのレスポンスに、`Access-Control-Allow-Origin`ヘッダーが付いているかを確認します。

手順の概要​

ルームのオリジンを確認する​

agentスクリプトを組み込む​

バンドルに組み込む場合​

ページを配信する​

HTTPSで配信する​

ページにsandboxのCSPを付ける​

ページが読み込むファイルにCORSのヘッダーを付ける​

状態はサーバーで管理する​

ルームのCSPでページのオリジンを許可する​

ルームで確認する​

ページの大きさ​

リンク​

キーボードとフォーカス​

表示できないもの​

表示されない場合​