自社システムへの埋め込み方

バックエンドが短命トークンを発行し、フロントは OralEmbed.mount。完了は API を正とする。

oraldeveloper

対象：連携開発者 · 適用：DodoSpeak Oral

目標：練習 / 課題 / 記録 / 試験を自社ページへ固定手順で埋め込む。

準備は使い始める前に準備すること。2 経路の対照は 2つの正式な埋め込み。成績と記録は試験成績の取得と記録の見方。実例は公式サイトでトライアル開設後にスピーキング接続台へログイン（既定は 管理者。先に組織情報で埋め込み方式と名簿を整える）、開発者に切り替えて埋め込み方。

固定手順

テナントを開通し テナントキー を受け取る（バックエンドのみ）。
学習者が自社ページを開くとき、自社バックエンド が POST /api/v2/oral/embed-sessions し、短命の埋め込みトークンを得る。
フロントがそのトークンを OralEmbed.mount に渡し、表面（practice / assignment / report / exam）を指定する。
発話または試験のあと、自社バックエンドが Oral API（または Webhook）で完了と使用量を確認する。

ブラウザが持つのは短命トークンだけ。テナントキーは持たない。

画面の場所（対照）

接続台 → 開発者に切替 → サイドバー 埋め込み方：3 ステップ（キーをコピー、サイト登録、発行してマウント）。これは見本であり、サイト全体を複製する必要はない。

フロントのマウント（例）

<div id="oral"></div>
<script src="https://（埋め込みスクリプトのホスト）/oral-embed.js"></script>
<script>
  OralEmbed.mount("#oral", {
    token: window.__ORAL_EMBED_TOKEN__,
    surface: "practice",
    locale: "ja",
    onCompleted: function () {
      /* 自社バックエンドで完了を確認 */
    }
  });
</script>

token は自社バックエンドが渡す。スクリプト URL と API ベースは開通資料に従う。

表面とプラン

4 表面は一覧に残す。プランが足りないときは API が拒否する（権限なしなど）。プランでボタンを隠さない。

表面	用途	目安のプラン
練習 `practice`	発話練習	Lite
課題 `assignment`	公開済み課題	Class
記録 `report`	結果を見る（SaaS 学生の「記録」に揃える）	Assess
試験 `exam`	正式試験	Exam

詳細はプラン・権限と使用量。

成功の確認

埋め込み UI が出て、マイク許可後に発話できる。
自社バックエンドが対応するセッション / 完了記録を読める。
プラン未満の表面は API が拒否し、UI から消えない。

よくある失敗