Perxona Widget SDK

<sv-agent> 是一個 web component，把完整可用的 AI avatar 放進任何網頁。本指南涵蓋整個整合介面：設定屬性、生命週期事件，以及語音與自訂渲染的 JavaScript 方法。

以下所有名稱都經過對現行 widget build 的驗證。與後台相關的部分（取得 Agent Profile ID、產生嵌入程式碼），見 avatar 指南中「分享」對話框 → 嵌入程式碼卡片的說明。

事前準備

API key 或 session token —— 兩者擇一，必要。 - API key 直接驗證你的 widget。以組織為單位發放；你同時要登記會載入 widget 的網域，僅列入允許清單的網域會被接受。 - session token 是由你自行簽發的 JWT，適合想自行控制效期與輪替的團隊。見下方Session token。
Agent Profile ID —— 識別要載入哪個 avatar 與設定的 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>

不要用自己的 CSS 去調整 sv-agent（定位／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`	完整 widget 含聊天介面；只渲染 3D avatar（介面自建）；或只有對話視窗。
`presentationMode`	`bubble`／`embedded`	浮動聊天泡泡按鈕，或嵌入頁面版面中。
`cameraAngle`	`fullBody`／`halfBody`	3D avatar 的預設取景。
`initFov`	JSON，如 `'{"distance": 1, "horizontal": 0, "vertical": 0}'`	相機距離與位移。
`appearanceMode`	`light`／`dark`	widget 配色。
`userBubbleColor`	CSS 色碼	聊天泡泡的主色。
`bubbleSetting`	JSON，如 `'{"icon": {"src": "…"}}'`	泡泡按鈕細節，例如自訂圖示。
`showHeader`	`true`（預設）／`false`	是否顯示 widget 頂欄。

行為：

屬性	值	說明
`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）。可用來在 avatar 播放影片時暫停你網頁自己的影片。

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

語音控制方法

widget 就緒後可用；皆為元素上的方法。

方法	回傳	說明
`startRecording()`	`Promise<boolean>`	開始語音辨識。麥克風被拒或語音服務不可用時 resolve `false`。
`stopRecording()`	`void`	立即停止目前的辨識工作階段；任何時候呼叫都安全。
`getRecognitionStatus()`	`'idle'`／`'preparing'`／`'recognizing'`／`'unknown'`	目前的辨識狀態。
`isRecording()`	`boolean`	是否正在聆聽。
`getMicrophoneVolume()`	`number`	目前麥克風音量，可做音量表。不可用時回 `0`。

用 `agentReply` 自訂渲染

在 3DPresentation 模式下，對話介面由你自建，用 agentReply 讓 avatar 渲染文字與動作：

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 都在 avatar 的「分享」對話框 → 嵌入程式碼卡片。
多媒體顯示器播的附件在知識庫設定。
嵌入 widget 產生的對話（含 customerRefId）出現在對話紀錄。