콘텐츠 (Contents)

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!';

      // 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에서 삭제할 데이터의 고유한 키를 의미합니다.

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}

    );
};

displayAutoLanguageOptions (언어 옵션 표시)

콘텐츠에서 언어 옵션을 표시하려면 @eliceio/content-sdk에서 제공하는 displayAutoLanguageOptions() 함수를 사용할 수 있습니다. 현재 지원되는 언어는 다음과 같습니다:

한국어
영어
일본어
태국어

예제

import { eliceContents } from 'src/constants';

eliceContents.init().then(() => {
  eliceContents.displayAutoLanguageOptions().then(() => {
    console.log('언어 옵션이 표시되었습니다');
  });
});

2. 속성

account (계정 정보)

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

다음은 Elice 플랫폼에 로그인한 계정의 정보를 조회할 수 있는 속성입니다. 계정 정보에는 다음과 같은 속성이 포함됩니다:

이름	유형	설명
`uid`	`number`	계정의 고유 식별자입니다.
`fullname`	`string`	계정의 이름입니다.
`isTutorAccount`	`boolean`	계정이 튜터 계정인지 여부입니다.

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 }

isTutoringMode (튜터링 모드)

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

isTutoringMode 속성은 현재 사용자가 튜터링 모드인지 확인하는데 사용됩니다. 사용자가 튜터링 모드에 있는 경우 값은 true이며, 그렇지 않으면 false를 반환합니다. 튜터링 모드는 Elice 플랫폼을 통해 튜터가 다른 학생의 외부 콘텐츠에 접근할 때만 활성화됩니다.

import { eliceContents } from 'src/constants';

console.log(eliceContents.isTutoringMode); // false 또는 true

locale (Locale)

locale는 현재 사용자의 설정된 언어를 의미하며 타입은 문자열입니다. IETF 언어 하위 태그로 기본 언어는 en입니다. 현재 Elice 플랫폼에서 지원하는 언어는 다음과 같습니다.

언어	코드
한국어	`ko`
영어	`en`
일본어	`ja`
태국어	`th`

1. 메서드​

init (SDK 초기화)​

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

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

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

delete (key-value 삭제)​

displayAutoLanguageOptions (언어 옵션 표시)​

예제​

2. 속성​

account (계정 정보)​

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

isTutoringMode (튜터링 모드)​

locale (Locale)​