コンテンツにスキップ
Prevu3D

Embedセッション

embedセッションは、RealityTwinを自社のページ内でレンダリングできるようにする短命の許可です。バックエンドがRealityConnect APIを通じてセッションを作成し、ブラウザで安全に扱える値をフロントエンドに転送し、フロントエンドがそれらをSDKに渡します。このページは、その2つのエンドポイント、返されるすべてのフィールド、そして自分で組み立てる必要がある唯一の値であるiframe URLのリファレンスです。

2つのセッションエンドポイント

Section titled “2つのセッションエンドポイント”

どちらの操作もツインコンテキスト上にあり、インタラクティブなAPIリファレンスで実験的として公開されています。

メソッドパスボディ
GET{api_url}/v1/twin/{contextId}/embed/create-sessionなし
POST{api_url}/v1/twin/{contextId}/embed/refresh-session{ "refreshToken": "<base64 refresh token>" }

{api_url}はリージョンのAPIベースで、すでに/realityconnect-apiで終わっています。したがって、完全な呼び出しは次のようになります：

GET https://api-ue1.prevu3d.com/realityconnect-api/v1/twin/{contextId}/embed/create-session
Authorization: Bearer {access_token}

{contextId}は、埋め込みたいツインのIDです。RealityPlanはここではサポートされていません。

必要なスコープ

Section titled “必要なスコープ”

どちらの操作も、同一のアクセストークンに2つのスコープが必要です：

スコープ理由
read:twinセッションの対象となるツインを読み取るため
embed:twinそのツインのembedセッションを発行するため

どちらか一方しか持たないトークンには、Insufficient OAuth scopesを伴う403 Forbiddenが返ります。開始する前に、OAuthアプリケーションに両方を追加してください。Client Credentialsフローガイドを参照してください。

また、embedセッションはAPIの他の部分よりも厳しい専用のレート制限枠を使用します。ページのレンダリングごとではなく、閲覧セッションごとにセッションを作成してください。

create-sessionのレスポンス

Section titled “create-sessionのレスポンス”
{
  "iframeUrl": "https://embed.prevu3d.com/reality-twin",
  "token": "eyJhbGciOiJFUzUxMi...",
  "refreshToken": "ZXhhbXBsZS1yZWZyZXNoLXRva2Vu",
  "expiresAt": "2026-09-04T13:55:00.000Z",
  "apiUrl": "https://api-ue1.prevu3d.com/reality-twin"
}
フィールド内容SDK構成
iframeUrlembedビューアのベースURL。使用する前に完成させてください — iframe URLの構築を参照。iframeUrl（embedルートを付加したもの）
token署名付きのセッションJWT。SDKに必須で、埋め込まれたツインはこれで認証します。platformJWT
refreshTokenこのセッションと対になるBase64のシークレット。バックエンドに保持してください。—
expiresAtセッションを更新すべき期限のISO 8601形式のタイムスタンプ。token自体が受理されなくなる数分前になります。—
apiUrl埋め込まれたツインが通信するリージョンのRealityTwinバックエンド（…/reality-twin）。上で呼び出した{api_url}ではありません — セッションのエンドポイントはこのURL上には存在しません。backendUrl

refresh-sessionは、iframeUrlとapiUrlを除いた同じ形状を返します。この2つの取得は一度で済みます。iframeUrlは環境ごとに一定で、apiUrlは組織のリージョンごとに一定です。

iframe URLの構築

Section titled “iframe URLの構築”

iframeUrlはベースURLであり、完成したsrcではありません。1つの環境内では、すべてのツインで同じ定数です — 本番環境ではhttps://embed.prevu3d.com/reality-twinです。これにembedルートを付加してください：

const src = `${session.iframeUrl}/embed`;
// https://embed.prevu3d.com/reality-twin/embed

ツインのIDはURLに含める必要はありません。セッショントークンがすでにツインを識別しており、ビューアはそこからツインを読み取ります。

2つはスラッシュ1つだけで連結してください。iframeUrlは末尾にスラッシュを持たないため、`${iframeUrl}/embed`が正しい形です。

完成したURLをSDKに渡します：

RealityConnectEmbed.init({
  iframeUrl: `${session.iframeUrl}/embed`,
  backendUrl: session.apiUrl,
  platformJWT: session.token,
  elementId: 'twin-container',
});

トークンはURLに含めない

Section titled “トークンはURLに含めない”

セッションJWTは、SDKのINIT_CONFIGによるpostMessageハンドシェイクを通じて、platformJWT構成値としてiframeに渡されます。クエリパラメータとしてiframeのURLに付加しないでください — 埋め込まれたツインはクエリパラメータを読み取りませんし、有効な認証情報をURLに入れると、ブラウザ履歴、リファラーヘッダー、サーバーログに露出します。

同じ理由から、embedページはSDKのiframe内で実行されることを前提としています。完成したURLをブラウザのタブに単独で貼り付けても、トークンとバックエンドURLを渡すものが存在しないため、ツインは読み込まれません。

セッションを維持する

Section titled “セッションを維持する”

セッションは短命です。expiresAtより前に、保存しておいたrefreshTokenを使ってバックエンドからrefresh-sessionを呼び出し、新しいrefreshTokenを永続化し、新しいtokenをtwin.updateAccessToken(newAccessToken)で実行中のSDKに渡してください — iframeを再作成する必要はありません。完全なパターンについてはセットアップのステップ4を参照してください。

次のステップ

Section titled “次のステップ”