メインコンテンツまでスキップ

自由構成学習資料 SDK

@eliceio/cdk 1.xは、EliceLXPの自由構成学習資料(Custom HTML)の中で実行されるコンテンツが、LXP・学習資料サーバーとやり取りするときに使うブラウザSDKです。解答の提出と採点、編集画面での設定保存、ファイル・キー値ストア・AI呼び出し、授業ページ間の移動を提供します。

外部学習資源用のSDKは、本書とは別のSDKです。

ecdkと画面キット​

資料を作成する方は、通常SDKを直接呼び出しません。ecdk CLIとAIツール(Helpy Code・Claude Code)でプロジェクトを作成すると、SDKと画面キットがすでに接続されており、プレビュー・検査・ビルド・アップロードまでecdkが担当します。まず以下の文書をご覧ください。

本書は、SDKを直接呼び出す開発者や、ecdkプロジェクトでキットが行わない動作を追加したい開発者向けのリファレンスです。

実行環境​

コンテンツは学習ページと編集ページでsandbox="allow-scripts allow-same-origin"のiframeとして実行され、コンテンツごとに異なるオリジン(コンテンツドメインのサブドメイン)を使います。zipの最上位にあるmetadata.jsonに画面ごとのエントリーファイルを書くと、LXPが状況に合ったファイルを表示します。ecdkで作成したプロジェクトはこのファイルも一緒に作成します。

{
"kind": "material",
"screens": {
"learn": { "enabled": true, "entry": "index.html" },
"instructor": { "enabled": true, "entry": "instructor.html" },
"edit": { "enabled": false }
}
}

LXPはiframe URLのフラグメントで、1つの資料にのみ使える短期トークンと学習資料サーバーのアドレスを渡します(…/index.html#token=…&baseUrl=…)。init()がこの値を読み取り、アドレスバーからトークンを削除します。LXPのログイン情報はコンテンツに渡されません。画面ごとのURL形式は画面と閲覧者をご覧ください。

sandboxとセキュリティポリシーのため、以下の制約があります。

  • ポップアップ(window.open)、alert・confirm・prompt、上位ページの遷移は使用できません。
  • <form>の送信はブラウザがブロックするため、submitイベントさえ発生しません。提出・保存ボタンをtype="button"にし、clickでsdk.submit()・sdk.saveSettings()を呼び出します。Enterキーで提出するには、入力欄のkeydownで直接処理します。
  • localStorage・sessionStorage・indexedDB・Cookieはコンテンツごとに個別に使えますが、そのブラウザ・端末にのみ残り、学習記録にはなりません。残す必要がある値はsdk.submit()・sdk.saveSettings()・キー値ストアで送ります。
  • コンテンツサーバーのContent-Security-Policy: sandboxヘッダーにallow-same-originがないと、オリジンがnullになってブラウザストレージが例外を出し、コンテンツ自身のファイルをfetch・<script type="module" src>で取得するリクエストがCORSでブロックされます。ecdk buildはどちらの場合でも画面が表示されるよう、モジュールスクリプトとJSONをHTMLの中に埋め込みます。
  • コンテンツのファイルは相対パス(./app.js)で読み込みます。
  • 1つのファイルにすべての画面を入れ、sdk.screenで分けても構いません。

インストール​

npmからインストールします。

npm install @eliceio/cdk
import { EliceCDK } from '@eliceio/cdk';

初期化​

init()はURLのフラグメントからトークンを読み取り、アドレスバーからトークンを削除した後、資料情報と閲覧者情報を取得します。その他の機能はinit()が完了した後に使います。

const sdk = new EliceCDK();
await sdk.init();

sdk.initialized; // true
sdk.metadata; // { materialId: '0193f2aa-…', lecturePageId: 53054656, courseId: 726660 }
sdk.locale; // 'ko'
sdk.isDraft; // 편집 화면의 미리보기 · 저장 전 업로드면 true

コンストラクタのオプションは2つです。

オプション説明
baseUrl学習資料サーバーのアドレス。省略するとフラグメントのbaseUrl、それもなければhttps://api-material.elice.ioを使います。フラグメントの値が正しいhttp(s)アドレスでなければ無視します
onSessionExpiredセッションが終了したときに1回呼ばれます。トークンの更新とセッションの期限切れをご覧ください

init({ hash, pathname })でフラグメントとパスを直接渡すこともできます。渡さない場合はwindow.locationから読み取ります。

init()が失敗するケースは以下のとおりです。詳しいコードはエラー処理をご覧ください。

  • フラグメントにtoken・preview・editのいずれもない、または値が正しくない場合はAggregateErrorを投げます。errorsにinvalid_paramコードのEliceCDKErrorが入っています。
  • トークンを読み取れなければinvalid_token、資料IDが見つからなければinvalid_param、サーバーが拒否すればそれに応じたEliceCDKErrorを投げます。

読み込み状態​

SDKは、コンテンツが開いたかどうかを、表示元のページ(学習ページ・編集ページ)にstatusメッセージで通知します。LXPはこの信号で独自の読み込み・失敗画面を表示するため、コンテンツが「資料を開けません」画面を別途作る必要はありません。

{ source: 'eliceio-content-sdk', type: 'status', materialId, payload: { state: 'loading' } }
{ source: 'eliceio-content-sdk', type: 'status', materialId, payload: { state: 'ready' } }
{ source: 'eliceio-content-sdk', type: 'status', materialId, payload: { state: 'failed', reason, code } }
タイミングpayload
init()開始{ state: 'loading' }
init()成功{ state: 'ready' }
init()失敗(init()がエラーを投げる前に送信){ state: 'failed', reason, code }
新しいトークンが届く前にトークンが期限切れになったとき{ state: 'failed', reason: 'auth', code }
  • reason:auth(トークンが不正、またはセッションが終了)、network(ブラウザがオフラインで応答がない)、config(その他すべて:オンラインなのに応答がない(CORS、誤ったAPIアドレス)、サーバーエラー、資料ID・フラグメントがないなど)。
  • code:サーバーがエラーコードを返せばそのコード、なければSDKのエラーコード。ログ用です。
  • materialId:SDKが資料IDを知る前はnull。
  • failedはinit()の失敗と、新しいトークンが届く前のトークン期限切れのときだけ送信します。init()後の呼び出し(submit、history、saveSettingsなど)の失敗はコンテンツが処理します。
  • コンテンツを直接開いて表示元のページがない場合は、何も送信しません。
init()は必ず呼び出してください

LXPはこの信号を待っています。init()を呼び出さないコンテンツはreadyもfailedも送信しないため、LXPは適切な画面の代わりにタイムアウトとしてしか処理できない場合があります。

最小の例​

import { EliceCDK, EliceCDKError } from '@eliceio/cdk';

const sdk = new EliceCDK({
onSessionExpired: () => {
showMessage('학습 시간이 길어졌어요. 페이지를 새로고침해 주세요.');
},
});
await sdk.init();

const button = document.getElementById('submit'); // <button id="submit" type="button">
button.disabled = sdk.viewer === 'tutor'; // 튜터는 제출할 수 없음

button.addEventListener('click', async () => {
try {
const { isCorrect, score } = await sdk.submit({ q1: 'B' });
showMessage(isCorrect ? `정답 (${score}점)` : '제출했어요.');
} catch (err) {
if (err.code === EliceCDKError.code.RateLimited) {
showMessage('잠시 후 다시 제출해 주세요.');
}
}
});
満点のお祝いはLXPが表示します

学生が満点を取ったときのお祝い(ウサギ・サウンド)は、サーバーの点数が変わるとLXPが表示します。コンテンツはsubmit()を呼び出すだけで、お祝い画面やLXPに通知するコードを別途作りません。

ローカル開発​

ecdk devは学習資料サーバーを模倣するプレビューを開き、LXPにアップロードせずに学生・チューター・教育者の画面と編集画面を切り替えながら確認できるようにします。模擬サーバーはAI(mlapi)を呼び出しません。

文書一覧​

文書内容
画面と閲覧者screen・viewer・scope・isDraft、画面ごとのURL
資料情報と設定の保存material、settings、編集画面のsaveSettings()、採点設定と学習完了設定
解答の提出と記録submit()、history()、result
ファイルassets.post()・assets.get()、PDF・PPTX・画像
キー値ストアkvstore.get()・post()・delete()
AI呼び出しmlapi.fetch()、ストリーム(SSE)
動画プレーヤーvideoPlayerUrl、loadScript()
授業ページの移動navigation
トークンの更新とセッションの期限切れ新しいトークンの受け取り、onSessionExpired、dispose()
エラー処理EliceCDKErrorとエラーコード

パッケージにも同じ内容の使用ガイド(node_modules/@eliceio/cdk/docs/usage.ko.md)と型定義が含まれています。npmパッケージページでバージョン履歴を確認できます。

お問い合わせ​

導入機関の担当マネージャー、またはエリスのカスタマーセンターにお問い合わせください。