자유 구성 학습자료 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는 이 신호로 자체 로딩 · 실패 화면을 보여 주므로, 콘텐츠가 "