본문으로 건너뛰기

자유 구성 학습자료 SDK

@eliceio/cdk 1.x는 엘리스LXP의 자유 구성 학습자료(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 주소의 fragment로 자료 하나에만 쓸 수 있는 짧은 토큰과 학습자료 서버 주소를 넘깁니다(…/index.html#token=…&baseUrl=…). init()이 이 값을 읽고 주소창에서 토큰을 지웁니다. LXP 로그인 정보는 콘텐츠에 들어오지 않습니다. 화면별 주소 형식은 화면과 보는 사람을 봅니다.

sandbox와 보안 정책 때문에 아래 제약이 있습니다.

  • 팝업(window.open), alert · confirm · prompt, 상위 페이지 이동은 쓸 수 없습니다.
  • <form> 제출은 브라우저가 막아 submit 이벤트조차 오지 않습니다. 제출 · 저장 버튼을 type="button"으로 두고 click에서 sdk.submit() · sdk.saveSettings()를 부릅니다. Enter 키로 제출하려면 입력란의 keydown에서 직접 처리합니다.
  • localStorage · sessionStorage · indexedDB · 쿠키는 콘텐츠마다 따로 쓸 수 있지만 그 브라우저 · 기기에만 남고 학습 기록이 아닙니다. 남겨야 할 값은 sdk.submit() · sdk.saveSettings() · 키-값 저장소로 보냅니다.
  • 콘텐츠 서버의 Content-Security-Policy: sandbox 헤더에 allow-same-origin이 없으면 출처가 null이 되어 브라우저 저장소가 예외를 내고, 콘텐츠 자기 파일을 fetch · <script type="module" src>로 받는 요청이 CORS로 막힙니다. ecdk build는 어느 쪽이든 화면이 뜨도록 모듈 스크립트와 JSON을 HTML 안에 넣습니다.
  • 콘텐츠 파일은 상대경로(./app.js)로 불러옵니다.
  • 파일 하나에 모든 화면을 넣고 sdk.screen으로 나눠도 됩니다.

설치​

npm에서 설치합니다.

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

초기화​

init()은 주소의 fragment에서 토큰을 읽고, 주소창에서 토큰을 지운 뒤, 자료 정보와 보는 사람 정보를 받아 옵니다. 다른 기능은 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

생성자 옵션은 두 가지입니다.

옵션설명
baseUrl학습자료 서버 주소. 없으면 fragment의 baseUrl, 그것도 없으면 https://api-material.elice.io를 씁니다. fragment 값이 올바른 http(s) 주소가 아니면 무시합니다
onSessionExpired세션이 끝났을 때 한 번 불립니다. 토큰 갱신과 세션 만료를 봅니다

init({ hash, pathname })으로 fragment와 경로를 직접 넘길 수도 있습니다. 넘기지 않으면 window.location에서 읽습니다.

init()이 실패하는 경우는 다음과 같습니다. 자세한 코드는 오류 처리를 봅니다.

  • fragment에 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 · fragment 없음 등).
  • 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, 화면별 주소
자료 정보와 설정 저장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 패키지 페이지에서 버전 기록을 볼 수 있습니다.

문의​

도입 기관 담당 매니저 또는 엘리스 고객센터로 문의해 주세요.