Free-form Learning Material SDK
@eliceio/cdk 1.x is the browser SDK that content running inside an EliceLXP free-form learning material (Custom HTML) uses to communicate with LXP and the learning material server. It provides answer submission and grading, saving settings from the edit screen, files, a key-value store, AI calls, and navigation between lecture pages.
The SDK for external learning materials is a separate SDK from the one described here.
ecdk and the screen kit
Material authors usually do not call the SDK directly. When you create a project with the ecdk CLI and an AI tool (Helpy Code · Claude Code), the SDK and the screen kit are already wired up, and ecdk handles preview, validation, build, and upload. Start with the documents below.
This document is a reference for developers who call the SDK directly or who want to add behavior that the kit does not provide in an ecdk project.
Runtime environment
Content runs in a sandbox="allow-scripts allow-same-origin" iframe on the learning page and the edit page, and each piece of content uses its own origin (a subdomain of the content domain). If you list the entry file for each screen in metadata.json at the top level of the zip, LXP opens the right file for each situation. Projects created by ecdk generate this file for you.
{
"kind": "material",
"screens": {
"learn": { "enabled": true, "entry": "index.html" },
"instructor": { "enabled": true, "entry": "instructor.html" },
"edit": { "enabled": false }
}
}
LXP passes a short-lived token that works for a single material only, together with the learning material server address, in the fragment of the iframe URL (…/index.html#token=…&baseUrl=…). init() reads these values and removes the token from the address bar. LXP login information never reaches the content. For the URL format of each screen, see Screens and viewers.
The sandbox and security policies impose the following restrictions.
- Popups (
window.open),alert·confirm·prompt, and navigating the top-level page are not available. - The browser blocks
<form>submission, so not even thesubmitevent fires. Make submit and save buttonstype="button"and callsdk.submit()·sdk.saveSettings()onclick. To submit with the Enter key, handle it yourself in the input'skeydown. - localStorage · sessionStorage · indexedDB · cookies are available separately per content, but they stay only in that browser and device and are not learning records. Send values that must be kept through
sdk.submit()·sdk.saveSettings()· the key-value store. - If the content server's
Content-Security-Policy: sandboxheader lacksallow-same-origin, the origin becomesnull, browser storage throws exceptions, and requests that load the content's own files withfetch·<script type="module" src>are blocked by CORS.ecdk buildinlines module scripts and JSON into the HTML so that the screen loads either way. - Load content files with relative paths (
./app.js). - You may also put every screen in a single file and branch on
sdk.screen.
Installation
Install from npm.
npm install @eliceio/cdk
import { EliceCDK } from '@eliceio/cdk';
Initialization
init() reads the token from the URL fragment, removes it from the address bar, and then fetches the material information and viewer information. Use other features after init() has finished.
const sdk = new EliceCDK();
await sdk.init();
sdk.initialized; // true
sdk.metadata; // { materialId: '0193f2aa-…', lecturePageId: 53054656, courseId: 726660 }
sdk.locale; // 'ko'
sdk.isDraft; // 편집 화면의 미리보기 · 저 장 전 업로드면 true
The constructor takes two options.
| Option | Description |
|---|---|
baseUrl | Learning material server address. If omitted, the baseUrl in the fragment is used, and if that is missing too, https://api-material.elice.io. A fragment value that is not a valid http(s) URL is ignored |
onSessionExpired | Called once when the session ends. See Token refresh and session expiry |
You can also pass the fragment and path directly with init({ hash, pathname }). If you don't, they are read from window.location.
init() fails in the following cases. For the exact codes, see Error handling.
- If the fragment contains none of
token·preview·edit, or a value is invalid, it throws anAggregateError.errorscontainsEliceCDKErrors with theinvalid_paramcode. - If the token cannot be read it throws
invalid_token, if the material id cannot be found it throwsinvalid_param, and if the server rejects the request it throws the matchingEliceCDKError.
Loading status
The SDK reports whether the content has opened to the page that embeds it (the learning page or the edit page) with status messages. LXP uses this signal to show its own loading and failure screens, so the content does not need to build its own "Cannot open the material" screen.
{ 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 } }
| When | payload |
|---|---|
init() starts | { state: 'loading' } |
init() succeeds | { state: 'ready' } |
init() fails (sent before init() throws) | { state: 'failed', reason, code } |
| The token expires before a new token arrives | { state: 'failed', reason: 'auth', code } |
reason:auth(the token is invalid or the session has ended),network(no response because the browser is offline),config(everything else: no response while online (CORS, wrong API address), server errors, missing material id or fragment, and so on).code: the error code from the server if it sent one, otherwise the SDK error code. For logging.materialId:nulluntil the SDK knows the material id.failedis sent only wheninit()fails and when the token expires before a new token arrives. Failures of calls afterinit()(submit,history,saveSettings, and so on) are handled by the content.- If the content was opened directly and there is no embedding page, nothing is sent.
LXP waits for this signal. Content that never calls init() sends neither ready nor failed, so LXP may only be able to treat it as a timeout instead of showing the appropriate screen.
Minimal example
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('잠시 후 다시 제출해 주세요.');
}
}
});
When a student gets a perfect score, LXP shows the celebration (rabbit · sound) when the server score changes. The content only calls submit() and does not build its own celebration screen or code that notifies LXP.
Local development
ecdk dev opens a preview that mimics the learning material server, so you can switch between the student, tutor, and educator screens and the edit screen without uploading to LXP. The mock server does not call AI (mlapi).
Documents
| Document | Contents |
|---|---|
| Screens and viewers | screen · viewer · scope · isDraft, URLs per screen |
| Material information and saving settings | material, settings, saveSettings() on the edit screen, grading settings and learning completion settings |
| Answer submission and history | submit(), history(), result |
| Files | assets.post() · assets.get(), PDF · PPTX · images |
| Key-value store | kvstore.get() · post() · delete() |
| AI calls | mlapi.fetch(), streams (SSE) |
| Video player | videoPlayerUrl, loadScript() |
| Lecture page navigation | navigation |
| Token refresh and session expiry | Receiving new tokens, onSessionExpired, dispose() |
| Error handling | EliceCDKError and error codes |
The package also contains a usage guide with the same content (node_modules/@eliceio/cdk/docs/usage.ko.md) and type definitions. You can see the version history on the npm package page.
Contact
Please contact your organization's account manager or the Elice customer center.