怎麼嵌進你們的系統

受眾：整合開發者 · 適用：DodoSpeak Oral

目標：按固定路徑把練習 / 任務 / 記錄 / 考試嵌進你們的頁面；先選接入方式，再掛載。

準備事項見 要用起來先準備什麼。兩種接入對照見 兩種正式接入：頁面掛件與登入換票。成績與記錄見 如何取得考試成績與查看記錄。想對著真實樣例抄：在官網開通試用後登入 口語接入台（預設 管理者，先在 設定 裡選嵌入方式、維護名冊），再切到開發者，進 如何嵌。

先選接入方式

兩種都是正式接入：同一套嵌入頁、同一套開口 / 評分 / 考試引擎；按人能力與計費單價相同。差別在認人整合誰來做，以及寫回你們 LMS 是否順手。

選型細表與「掛件必須多做的工作」見 兩種正式接入。不要說「掛件是試用、更便宜或不能按人」。

路徑 A：頁面掛件

1. 在 口語接入台「如何嵌」領取 可發佈鑰匙，登記網站 Origin。
2. 在接入台 匯入名冊，生成並分發 學員碼（或啟用學員 OTP / PIN）。
3. 頁面引入嵌入腳本，用掛件方式掛載（樣例在接入台「如何嵌 · 頁面掛件」）。
4. 學生開啟頁面後 先掃碼 / 輸碼，再練、交任務、考試或看記錄。
5. 機構密鑰 / 店鑰匙（如 olk_test_）不要寫進頁面。
6. 完成態若要對賬：後端仍可再問 Oral API；寫回你們 LMS 時按名冊學號欄位映射，或改用登入換票更省事。

未完成學員認人時掛件不能開口——這是預期。

路徑 B：登入換票（固定路徑）

1. 開通機構，拿到 機構密鑰（只放後端）。試用可在官網開通口語接入台；正式密鑰以商務開通為準。
2. 學生登入你們系統後，你們的後端 POST /api/v2/oral/embed-sessions，換回短時 嵌入令牌（須帶 external_user_id 等）。
3. 前端把令牌交給 OralEmbed.mount，指定表面（practice / assignment / report / exam）。
4. 學生開口練或考；結束後你們後端再調 Oral API（或收 Webhook）核對完成態、成績與用量。

瀏覽器裡只有短時嵌入令牌，沒有機構密鑰。

介面在哪（對照用）

接入台切到開發者 → 側欄 如何嵌：先選 頁面掛件 | 登入換票，再按步做。那是樣板，不是要你們照搬整站。

前端掛載（登入換票示意）

頁面準備一個容器，引入嵌入腳本後：

<div id="oral"></div>
<script src="https://（嵌入脚本地址）/oral-embed.js"></script>
<script>
  OralEmbed.mount("#oral", {
    token: window.__ORAL_EMBED_TOKEN__,
    surface: "practice",
    locale: "zh-CN",
    /* 可选：主题 token，见下方「个性化」 */
    onCompleted: function () {
      /* 再调自家后端核对完成态 */
    }
  });
</script>

token 必須由你們後端下發。腳本地址與 API 基址以開通材料為準。頁面掛件樣例以接入台「如何嵌」複製區為準（可發佈鑰匙 + 學員認人，不傳店鑰匙）。

個性化（主題 token）

嵌入頁可按你們產品外觀微調，不是換整站皮膚。

表面與套餐

四個表面都會出現在能力清單裡；套餐不夠時接口拒絕（常見為無權限），不要靠藏按鈕假裝沒有。

套餐細節見 套餐、權利與用量。成績與記錄見 如何取得考試成績與查看記錄。

如何確認成功

• 頁面出現嵌入的口語介面；掛件路徑須先完成學員認人，麥克風授權後能開口。
• 換票路徑：結束後，你們後端能按 外部用戶 id 查到對應會話 / 成績。
• 掛件路徑：結束後，能按 名冊學員 在 Oral 側看到對應記錄；寫回 LMS 按你們映射方案核對。
• 用低於套餐的表面請求時，API 拒絕，而不是前端「沒這個按鈕」。

常見失敗

相關閱讀

• 兩種正式接入：頁面掛件與登入換票
• 如何取得考試成績與查看記錄
• 開發者：如何嵌
• 管理者：設定樞紐、帳單與名冊
• FAQ：DodoSpeak Oral
• 術語表 · Oral