怎么嵌进你们的系统

受众：对接开发者 · 适用：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