SDK 초기화 및 데이터 저장(key-value)

SDK에서 지원되는 메소드를 정의합니다.

1. 메서드

init (SDK 초기화)

⚠️ SDK에서 제공하는 모든 기능은 init 메서드를 통해 초기화가 완료된 이후에 사용할 수 있습니다. 반드시 해당 함수의 실행이 완료된 이후 SDK 기능을 사용해주세요.

Vanilla JS example

<script defer>
    document.addEventListener('DOMContentLoaded', function() {
        // EliceContents SDK 초기화
        var eliceContents = new EliceContents();
        var rootEl = document.getElementById('root') || document.body;

        eliceContents.init().then(function() {
            // SDK 초기화 완료
            renderApp();
        }).catch(function() {
            // SDK 초기화 실패
            console.error('SDK 초기화 실패');
        });

        function renderApp() {
            // App 컴포넌트 내용
            var appContent = '<div>Hello, world!</div>';

            // root 요소에 App 컴포넌트 내용 추가
            rootEl.innerHTML = appContent;
        }
    });
</script>

React example

// main.tsx

import { EliceContents } from '@eliceio/content-sdk';

const eliceContents = new EliceContents();
const rootEl = document.getElementById('root') ?? document.body;
const root = createRoot(rootEl);

eliceContents
    .init()
    .then(() => {
        // SDK 초기화 완료
        return root.render(
            <React.StrictMode>
                <App />
            </React.StrictMode>
        );
    })
    .catch(() => {
        // SDK 초기화 실패
    });

설치된 SDK에서 제공하는 init() 함수를 사용하여 SDK를 초기화합니다.

해당 함수는 기본적으로 window.location.search를 통해 URL에 포함된 쿼리스트링을 파싱하여 엘리스 플랫폼과 연동하기 위한 정보인 materialId, extToken을 추출합니다.

// src/constants.ts

import { EliceContents } from '@eliceio/content-sdk';

export const eliceContents = new EliceContents();

eliceContents.init(); // 쿼리스트링에서 추출하여 초기화합니다.

window.location.search에서 연동하기 위한 정보를 제공하기 어려울 경우, init() 함수에 search 인자를 통해 직접 정보를 제공할 수 있습니다.
```
eliceContents.init({
    search: queryString.stringify({
        materialId: 100,
        extToken: '...',
    }),
});
```
baseUrl은 기본적으로 엘리스 플랫폼 production 환경에 설정되어 있습니다. 테스트 환경에서 사용하려면 baseUrl을 인자로 설정해주세요.
```
eliceContents.init({
    baseUrl: 'https://dev-v4-external-contents-api.dev.elicer.io',
});
```

sendScore (엘리스 플랫폼으로 점수 전달)

콘텐츠를 사용자가 모두 완료하였을 때, 점수를 엘리스 플랫폼으로 전달하도록 구성합니다.

콘텐츠가 왼료되는 시점에 @eliceio/content-sdk에서 제공하는 sendScore() 함수를 호출합니다. 함수에는 score라는 인자 값이 필요로 하며, 일반적으로 콘텐츠를 완료하였을 때에는 100을 보내도록 합니다.
```
import { eliceContents } from 'src/constants';

eliceContents.sendScore({ score: 100 }); // 100점을 엘리스 플랫폼으로 전달
```
상기 설명과 같이 콘텐츠를 엘리스 수업 자료로 설정하였다면, 수업 자료의 점수가 그림과 같이 100점이 되는지 확인합니다.

postKeyValue (엘리스 플랫폼에 실습 변경사항 저장)

학생의 콘텐츠 변경사항을 엘리스 플랫폼에 저장하기 위해서는 @eliceio/content-sdk에서 제공하는 postKeyValue() 함수를 사용합니다. 해당 함수는 key와 value를 저장하는 역할을 합니다.

import { eliceContents } from 'src/constants';

await eliceContents.postKeyValue({
    key: 'quiz01.answer', // key는 항상 camelCase로 작성되어야 히며,
                        // 영문자 및 숫자로만 작성되어야 합니다. (`[a-zA-Z0-9]+]`)
    value: '엘리스' // value의 가능한 타입은 string, number, boolean, object, array 이며,
                // object의 key는 항상 camelCase로 작성되어야 합니다.
});

⚠️ 실습 변경사항은 각 사용자 및 수업 자료마다 별도로 저장되며, 타 유저 혹은 수업 자료에는 영향을 주지 않습니다.

⚠️ key 및 value 작성 규칙
key는 항상 camelCase로 작성되어야 히며, 영문자 및 숫자로만 작성되어야 합니다. ([a-zA-Z0-9]+])
value의 가능한 타입은 string, number, boolean, object, array 이며, object의 key는 항상 camelCase로 작성되어야 합니다.

getKeyValue (엘리스 플랫폼에 실습 변경사항 조회)

학생의 콘텐츠 변경사항을 불러올 떄에는 @eliceio/content-sdk에서 제공하는 getKeyValue() 함수를 사용합니다. 해당 함수는 key에 해당하는 value를 불러옵니다.

import { eliceContents } from 'src/constants';

const value = await eliceContents.getKeyValue({
    key: 'quiz01.answer',
});

console.log(value); // "엘리스"

// 혹은 다음과 같이 키의 일부만 입력하여 해당 키의 하위 키들을 모두 불러올 수 있습니다.
// 구분자는 항상 '.'(dot)으로 작성되어야 합니다.

const value = await getKeyValue({
    key: 'quiz01',
});

console.log(value); // { answer: "엘리스" }

delete (key-value 삭제)

이 메서드는 Key-Value 저장소에서 키-값 쌍을 삭제하는 데 사용됩니다.

파라미터

이름 타입 설명

이름	타입	설명
`key`	`string`	kvstore에서 삭제할 데이터의 고유한 키를 의미합니다.

key

string

kvstore에서 삭제할 데이터의 고유한 키를 의미합니다.

JavaScript 예제

import { eliceContents } from 'src/constants';

const deleteButton = document.createElement('button');

const handleDelete = async () => {
    await eliceContents.kvstore.delete('quiz01.answer');
    const value = await eliceContents.kvstore.get('quiz01.answer');
    console.log(value); // null
};

deleteButton.addEventListener('click', handleDelete);
deleteButton.click();

React 예제

import { eliceContents } from 'src/constants';
import { useState } from 'react';

const App = () => {
    const [value, setValue] = useState(null);

    const handleDelete = async () => {
        await eliceContents.kvstore.delete('quiz01.answer');
        const value = await eliceContents.kvstore.get('quiz01.answer');
        setValue(value);
    };

    return (
        <div>
            <button onClick={handleDelete}>Delete</button>
            {value === null ? 'Deleted' : value}
        </div>
    );
};

2. 속성

account (계정 정보)

⚠️ account.accountId 속성은 v1.0.0 버전부터 삭제될 예정입니다. 대신 account.uid를 사용해주세요.

엘리스 플랫폼에 접속된 계정의 정보를 불러올 수 있습니다. 해당 정보는 account 속성을 통해 불러올 수 있습니다. 계정 정보에는 accountId(계정 ID), fullname(이름), uid(통합 ID)가 포함되어 있습니다.

import { eliceContents } from 'src/constants';

console.log(eliceContents.account); // { accountId: '550e8400-e29b-41d4-a716-446655440000', fullname: 'elice', uid: 123 }

metadata (학습자료 메타데이터)

엘리스 플랫폼에 등록된 학습자료의 메타데이터를 불러올 수 있습니다. 해당 정보는 metadata 속성을 통해 불러올 수 있습니다. 메타데이터 정보에는 materialId(자료 ID) 가 포함되어 있습니다.

import { eliceContents } from 'src/constants';

console.log(eliceContents.metadata);  // { materialId: 456 }

Last updated 2 months ago