セットアップ

このガイドでは、RealityTwinを埋め込むために必要な2つの統合を説明します。すなわち、（バックエンドから）RealityConnect APIに対してembedセッションを作成することと、（フロントエンドで）そのセッションをSDKに渡すことです。SDK自体に固有のすべて（インストールの詳細、初期化、コマンドとobservableの完全なサーフェス、エラーコード、実行可能なプレイグラウンド）は、信頼できる情報源である@prevu3d/realityconnect-embedパッケージのREADMEに記載されています。

前提条件

始める前に、以下を用意してください。

組織のセキュリティ設定でRealityConnect Embedが有効化されたEnterpriseプラン。
Client Credentialsフローを使用するRealityConnect APIのOAuthアプリケーション。まだ設定していない場合は、先にClient Credentialsフローガイドに従ってください。
埋め込みたいツインのID。
SDKをインストールするアカウントに対する、プライベートなprevu3d/realityconnect-embed GitHubリポジトリへの読み取りアクセス。アクセスは要求に応じて顧客ごとに手動で付与されます。アクセスが必要なGitHubユーザー名を添えて**カスタマーサクセスマネージャー（CSM）**に連絡すると、Prevu3Dがそれらをリポジトリに追加します。GitHub Packagesのパッケージの可視性はリポジトリの可視性に従うため、read:packagesのPATだけでは不十分で、リポジトリへのアクセスも必要です。

全体の連携

大まかに言うと、embedセッションは次のように流れます。

バックエンドがRealityConnect APIに対して認証し、特定のツインに対してcreate-sessionを呼び出します。APIはトークンとURLを返します。
バックエンドは、ブラウザで安全に扱える値（セッショントークン、iframeのベースURL、リージョナルAPI URL）をフロントエンドに転送します。
フロントエンドはこれらの値をSDKに渡し、SDKはiframeを挿入してツインとの双方向チャネルを開きます。
現在のトークンが期限切れになる前に、バックエンドはrefresh-sessionを呼び出し、新しい値をフロントエンドに返します。

OAuthのクライアントシークレットは決してブラウザに到達してはなりません。使用するのはバックエンドのみです。

ステップ1：embedセッションを作成する（バックエンド）

embedセッションの管理はRealityConnect APIを再利用します。Client Credentialsフローガイドに記載されているとおりにClient Credentialsフローで認証し、ツインに対して2つのembedセッション操作を呼び出します。

操作	目的
`GET {api_url}/v1/twin/{contextId}/embed/create-session`	セッションを開始します。`iframeUrl`、`token`、`refreshToken`、`expiresAt`、`apiUrl`を返します。ボディはありません。
`POST {api_url}/v1/twin/{contextId}/embed/refresh-session`	（ボディで送信した）`refreshToken`を、新しい`token`と`refreshToken`と交換します。

いずれの呼び出しも、Client Credentialsフローで取得したbearerアクセストークンをAuthorizationヘッダーで使用し、いずれもそのトークンにread:twinおよびembed:twinのスコープが必要です。この2つの操作の完全なリファレンスはEmbedセッションにあり、インタラクティブなAPIリファレンスではそれらのスキーマが公開されています。

ステップ2：SDKをインストールする（フロントエンド）

GitHubアカウントにアクセスが付与されたら（前提条件を参照）、プライベートなGitHub Packagesのnpmレジストリから@prevu3d/realityconnect-embedとしてSDKをインストールします。SDKのREADMEには、一度きりの.npmrcとPersonal Access Tokenの設定が最初から最後まで記載されています。

ステップ3：セッションをSDKに渡す

バックエンドからフロントエンドへcreate-sessionレスポンスのフィールドを転送し、SDKの構成にマッピングします。

`create-session`のフィールド	SDK構成	備考
`iframeUrl`	`iframeUrl`	ベースURLです。embedルートは自分で付加してください：`${iframeUrl}/embed`。ツインのIDはURLに含めません — セッショントークンがツインを識別します。iframe URLの構築を参照。
`apiUrl`	`backendUrl`	embedが通信するリージョンのRealityTwinバックエンド。ステップ1で呼び出した`{api_url}`ではありません。
`token`	`platformJWT`	embedが認証に使用する署名付きセッショントークン。URLパラメータとしてではなく、SDKによってiframeに渡されます。

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

そこから先は、SDKのREADMEに従ってパッケージをインストールし、ビューアを初期化し、ツインを操作してください。

ステップ4：セッションを維持する

embedセッションは短命です。create-sessionが返すtokenは、報告されるexpiresAtのおおよその時点で期限切れになります。その期間を超えてツインを稼働させ続けるには、バックエンドからセッションを更新し、新しいアクセストークンを実行中のSDKに渡してください — iframeを再作成する必要はありません。

一般的なパターン：

バックエンドで、現在のユーザーのツイン用に保存されたrefreshTokenを読み取り、refresh-sessionを呼び出し、新しいrefreshTokenを永続化し、新しいtoken（およびその他のセッションフィールド）をブラウザに返すエンドポイントを公開します。
フロントエンドで、現在のトークンが期限切れになる少し前に更新をスケジュールします。
新しいセッションが届いたら、twin.updateAccessToken(newAccessToken)を呼び出して、新しいアクセストークンを実行中のSDKに渡します：
```
await twin.updateAccessToken(newAccessToken);
```
ツインは次のバックエンドリクエストで新しいJWTを引き継ぎます — 開いているサブスクリプション、カメラ状態、読み込まれたワークフローはすべて維持されます。この呼び出しは受理時にtrue、拒否時にfalseで解決します（onError経由でも通知されます）。onReadyが発火する前に呼び出すと、RealityConnectEmbedError('TWIN_NOT_READY')がスローされます。

正確なスケジューリング戦略（期限切れ前の固定タイマー、ユーザーの操作時、タブの可視性変更時など）はアプリケーション次第です。

留意すべき点

ページがインターフェースを所有する。 embedは素のビューアです。独自のコントロールを構築し、SDKコマンドに接続してください。embedに含まれるものと含まれないものについてははじめにを参照してください。
認証情報はサーバー側に保持する。 セッションの要求と更新はバックエンドからのみ行ってください。
セッションは期限切れになる。 統合の一部としてトークンの更新を計画してください。
Enterpriseとセキュリティ設定。 embedは、組織で有効化されている場合にのみ読み込まれます。

SDKリファレンス

@prevu3d/realityconnect-embedパッケージは、SDKを扱うための完全なリファレンスです。そのREADMEでは以下を確認できます。

プライベートなGitHub Packagesレジストリ向けの.npmrcとPersonal Access Tokenの完全な設定
RealityConnectEmbed.init(config)の構成リファレンス
各namespaceのアクションと状態observable（ナビゲーション、オブジェクト、POI、POV、ユーティリティ）
共有可能なリンクのためのカメラビューエンコードフロー
文書化されたすべてのエラーコードと、それらが発生する条件
ライブツインに向けてコマンドサーフェスを探索できる、実行可能なプレイグラウンド

次のステップ

Embedセッション：セッションエンドポイント、レスポンスの全フィールド、iframe URLの組み立て方。
はじめに：機能の概要。
Client Credentialsフロー：このガイドの土台となる認証。
インタラクティブなAPIリファレンス：RealityConnect APIの完全なカタログ。
GitHubのライブ例：コピーして使える動作するVue.js統合。
@prevu3d/realityconnect-embed：ソースリポジトリ