Perxona Widget SDK

<sv-agent> は、動作する AIアバターを任意のウェブページに組み込める web component です。このガイドでは統合サーフェス全体 —— 設定属性、ライフサイクルイベント、音声とカスタムレンダリングの JavaScript メソッド —— を扱います。

以下の名称はすべて現行の widget ビルドに対して検証済みです。管理画面側の操作（Agent Profile ID の取得、埋め込みコードの生成）は、アバターガイドの「共有」ダイアログ → コードを取得カードの説明を参照してください。

事前準備

API key または session token —— どちらか一方が必須。 - API key は widget を直接認証します。組織単位で発行され、widget を読み込むホスト名も登録します。許可リストにあるホストのみ受け付けられます。 - session token は自社で署名する JWT で、有効期限とローテーションを自社管理したいチーム向けです。下記のSession tokenを参照。
Agent Profile ID —— 読み込むアバターと設定を識別する ULID。管理画面の埋め込みコード画面からコピーできます。

クイックスタート

CDN から SDK を読み込み、コンポーネントを配置します：

<script
  type="module"
  src="https://cdn.perxona.ai/prod/latest/widget/entry/index.js"
></script>

<sv-agent
  apiKey="<YOUR_API_KEY>"
  agentProfileId="<YOUR_AGENT_PROFILE_ID>"
  conversationMode="inputText"
  displayMode="fullPresentation"
></sv-agent>

sv-agent に独自の CSS（position／transform／サイズの上書き）を当てないでください —— widget は自身でレイアウトを管理しており、外部 CSS はレイアウトを壊します。

読み込み後に JavaScript で設定を変えることもできます：

const widget = document.querySelector('sv-agent');
widget.updateWidgetSetting({
  presentationMode: 'bubble',
  conversationMode: 'inputText',
  cameraAngle: 'fullBody',
});

属性リファレンス

認証と識別：

属性	説明
`apiKey`	Perxona API key。秘匿してください。`apiKey` と `sessionToken` が両方あるときは `apiKey` が優先されます。
`sessionToken`	自社管理の JWT。API key の代替（Session token参照）。
`agentProfileId`	読み込む Agent Profile の ULID。必須。
`customerRefId`	任意の自由形式 ID。セッションを自社のユーザーレコードに紐付けます —— セッションをまたぐ記憶はこれで有効になり、管理画面の会話履歴でその訪問者を特定できます。

レイアウトと外観：

属性	値	説明
`displayMode`	`fullPresentation`（既定）／`3DPresentation`／`2DPresentation`	チャット UI 込みの完全版；3Dアバターのみ（UI は自作）；会話ウィンドウのみ。
`presentationMode`	`bubble`／`embedded`	フローティングのチャットバブル、またはページ内埋め込み。
`cameraAngle`	`fullBody`／`halfBody`	3Dアバターの既定の構図。
`initFov`	JSON（例 `'{"distance": 1, "horizontal": 0, "vertical": 0}'`）	カメラの距離とオフセット。
`appearanceMode`	`light`／`dark`	widget の配色。
`userBubbleColor`	CSS カラー	チャットバブルのアクセント色。
`bubbleSetting`	JSON（例 `'{"icon": {"src": "…"}}'`）	バブルの詳細設定（カスタムアイコンなど）。
`showHeader`	`true`（既定）／`false`	ヘッダーバーの表示。

動作：

属性	値	説明
`readyToShowPolicy`	`showWhenAssetsLoading`（既定）／`showWhenAssetsReady`	読み込み表示付きで即表示するか、アセットのダウンロード完了後に表示するか。
`conversationMode`	`inputText`（既定）／`microphone`	テキスト入力か音声対話か。
`muted`	`true`／`false`（既定）	音声出力をミュートした状態で起動。
`enableUserActivationCheck`	`true`（既定）／`false`	実際のユーザー操作を待ってから音声再生を有効化（ブラウザの自動再生制限）。自動再生を既に緩和した管理環境（ネイティブ WebView など）でのみ `false` に —— iOS `WKWebView`：`mediaTypesRequiringUserActionForPlayback = []`；Android WebView：`setMediaPlaybackRequiresUserGesture(false)`。
`supportedFeatures`	JSON（例 `'{"multimedia": true}'`）	任意機能のトグル。`multimedia`（既定オン）はナレッジベースのメディア添付を widget 内に表示。

イベント

sv-agent 要素の addEventListener で監視します。

life-status —— 接続ライフサイクル。event.detail.status は disconnected／agent-preparation／downloading-assets／connection-start／connection-done／ready のいずれか。

asset-download-status —— ダウンロード進捗。Payload：status（常に downloading-assets）、asset（avatar／motion／scene）、progress（0–100）。

conversation-status —— 会話ライフサイクル。event.detail.status は idle／user-inputting／user-input-done／awaiting-response／awaiting-response-done／rendering-response／timeout のいずれか。該当時は input にユーザーのテキストが入ります。

agent-response-message —— メッセージストリーム。Payload：event（user-input／agent-answer／agent-end）、message、messageId（質問と回答の対応付け）、任意の ssmlMessage、createdAt。

chat-attachment —— マルチメディア表示が添付を提示したとき発火。Payload は attachments[] で、type（MIME：video/mp4、image/png、image/jpeg、application/pdf）と source（URL）を含みます。アバターが動画を再生している間、ページ側の動画を一時停止するといった用途に。

widget.addEventListener('life-status', (e) => {
  if (e.detail.status === 'ready') console.log('avatar ready');
});

音声コントロールメソッド

widget の準備完了後に利用可能。いずれも要素のメソッドです。

メソッド	戻り値	説明
`startRecording()`	`Promise<boolean>`	音声認識を開始。マイク拒否や音声サービス不可のときは `false` を返します。
`stopRecording()`	`void`	現在の認識セッションを即時停止。いつ呼んでも安全。
`getRecognitionStatus()`	`'idle'`／`'preparing'`／`'recognizing'`／`'unknown'`	現在の認識状態。
`isRecording()`	`boolean`	認識が聴取中かどうか。
`getMicrophoneVolume()`	`number`	現在のマイク音量（レベルメーター用）。取得不可時は `0`。

`agentReply` によるカスタムレンダリング

3DPresentation モードでは会話 UI を自作し、agentReply でアバターにテキストとモーションを演じさせます：

widget.agentReply({ event: 'user_input', message: 'Hi!' });
widget.agentReply({ event: 'agent_answer', message: 'Hello! How can I help?', motion_id: 'greeting' });
widget.agentReply({ event: 'agent_end' });

event の値：user_input（質問と回答プレースホルダを追加）、agent_answer（返答を描画し TTS で読み上げ）、agent_end（このやり取りを終了）。motion_id でアニメーションを指定：idle／talking／listening／greeting／error、またはストーリーボードのカスタムモーション。

Session token

Session token は組織のシークレットで署名する HS256 JWT で、標準の iat と exp を持ちます —— 各埋め込みセッションの有効期間を自社で決められます：

{ "iat": 1516239022, "exp": 1758004103 }

sessionToken 属性か updateWidgetSetting で設定します。session token を使うときは apiKey 属性を外してください —— 両方あると apiKey が優先されます。

管理画面との対応

埋め込みスニペット、キー管理、Agent Profile ID はアバターの「共有」ダイアログ → コードを取得カードにあります。
マルチメディア表示が再生する添付はナレッジベースで設定します。
埋め込み widget の会話（customerRefId を含む）は会話履歴に表示されます。