Skip to main content

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 the submit event fires. Make submit and save buttons type="button" and call sdk.submit() · sdk.saveSettings() on click. To submit with the Enter key, handle it yourself in the input's keydown.
  • 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: sandbox header lacks allow-same-origin, the origin becomes null, browser storage throws exceptions, and requests that load the content's own files with fetch · <script type="module" src> are blocked by CORS. ecdk build inlines 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.

OptionDescription
baseUrlLearning 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
onSessionExpiredCalled 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 an AggregateError. errors contains EliceCDKErrors with the invalid_param code.
  • If the token cannot be read it throws invalid_token, if the material id cannot be found it throws invalid_param, and if the server rejects the request it throws the matching EliceCDKError.

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 } }
Whenpayload
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: null until the SDK knows the material id.
  • failed is sent only when init() fails and when the token expires before a new token arrives. Failures of calls after init() (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.
Always call init()

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('잠시 후 다시 제출해 주세요.');
}
}
});
LXP shows the perfect-score celebration

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​

DocumentContents
Screens and viewersscreen · viewer · scope · isDraft, URLs per screen
Material information and saving settingsmaterial, settings, saveSettings() on the edit screen, grading settings and learning completion settings
Answer submission and historysubmit(), history(), result
Filesassets.post() · assets.get(), PDF · PPTX · images
Key-value storekvstore.get() · post() · delete()
AI callsmlapi.fetch(), streams (SSE)
Video playervideoPlayerUrl, loadScript()
Lecture page navigationnavigation
Token refresh and session expiryReceiving new tokens, onSessionExpired, dispose()
Error handlingEliceCDKError 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.