# 외부 학습 자료 SDK

본 문서는 엘리스의 외부 학습 자료를 개발의 가이드라인을 제공합니다.

이외의 다른 질문에 대해서는 엘리스로 연락 주시기 바랍니다.

## SDK 설치 및 초기화
외부 학습 자료 Javascript SDK를 npm 패키지로 설치해주세요. 해당 패키지는 웹 환경에서 사용 가능합니다.

```shell
# npm
npm install @eliceio/content-sdk --save

# yarn
yarn install @eliceio/content-sdk
```

## 메서드

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

1. 해당 함수는 기본적으로 `window.location.search`를 통해 URL에 포함된 쿼리스트링을 파싱하여 엘리스 플랫폼과 연동하기 위한 정보인 `materialId`, `extToken`을 추출합니다.
    ```ts
    // src/constants.ts
    
    import { EliceContents } from '@eliceio/content-sdk';

    export const eliceContents = new EliceContents();

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

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

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

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

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

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

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

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

```ts
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`를 불러옵니다.

```ts
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: "엘리스" }
```

## 속성

### account (계정 정보)

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

```ts
import { eliceContents } from 'src/constants';

console.log(eliceContents.account);  // { accountId: 123, fullname: 'elice' }
```

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

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

```ts
import { eliceContents } from 'src/constants';

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