# External Learning Materials SDK

This document provides guidelines for developing external learning materials with Elice.

For any other inquiries, please contact Elice.

## SDK Installation and Initialization
Please install the External Learning Materials JavaScript SDK as an npm package. This package is usable in web environments.

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

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

## Methods

### init (SDK Initialization)
Initialize the SDK using the `init()` function provided by the installed SDK.

1. By default, this function parses the query string included in the URL via `window.location.search` to extract `materialId` and `extToken`, which are necessary for integrating with the Elice platform.
    ```ts
    // src/constants.ts
    
    import { EliceContents } from '@eliceio/content-sdk';

    export const eliceContents = new EliceContents();

    eliceContents.init(); // Initialized by extracting from the query string.
    ```

2. If providing information directly from `window.location.search` is difficult, you can supply the information directly to the `init()` function via the `search` parameter.
    ```ts
    eliceContents.init({
        search: queryString.stringify({
            materialId: 100,
            extToken: '...',
        }),
    });
    ```

3. By default, `baseUrl` is set to the production environment of the Elice platform. If you want to use it in a testing environment, please set the `baseUrl` parameter.
    ```ts
    eliceContents.init({
        baseUrl: 'https://dev-v4-external-contents-api.dev.elicer.io',
    });
    ```

### sendScore (Sending Score to the Elice Platform)

When a user completes the content, configure it to send the score to the Elice platform.

1. At the point when the content is completed, call the `sendScore()` function provided by `@eliceio/content-sdk`. The function requires an argument called `score`, and typically, when the content is completed, you would send `100`.
    ```ts
    import { eliceContents } from 'src/constants';

    eliceContents.sendScore({ score: 100 }); // Sending 100 points to the Elice platform
    ```
1. If the content is configured as an Elice course material as described above, check whether the score of the course material becomes 100.

### postKeyValue (Saving Practice Changes to the Elice Platform)

To save a student's content changes to the Elice platform, you can use the `postKeyValue()` function provided by `@eliceio/content-sdk`. This function is responsible for storing a `key` and its corresponding `value`.

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

await eliceContents.postKeyValue({
    key: 'quiz01.answer', // Keys should always be written in camelCase
                          // and consist only of alphanumeric characters. (`[a-zA-Z0-9]+]`)
    value: 'Elice' // Possible types for value are string, number, boolean, object, array,
                  // where object keys should always be in camelCase.
});
```

> **⚠️ Practice changes are stored separately for each user and course material and do not affect other users or course materials.**

> **⚠️ Key and value writing rules:**
>   - **Keys** should always be written in **camelCase** and consist only of **alphanumeric characters**. (`[a-zA-Z0-9]+]`)
>   - Possible types for **value** are *string, number, boolean, object, array*, where **object keys should always be in camelCase**.

### getKeyValue (Retrieving Practice Changes from the Elice Platform)

To retrieve a student's content changes, you can use the `getKeyValue()` function provided by `@eliceio/content-sdk`. This function retrieves the `value` corresponding to a given `key`.

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

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

console.log(value); // "Elice"

// Alternatively, you can input only a part of the key to retrieve all its subkeys.
// The separator should always be a dot (.).

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

console.log(value); // { answer: "Elice" }
```

## Properties

### account (Account Information)

You can retrieve information about the account logged into the Elice platform. This information can be accessed through the `account` property. Account information includes `accountId` (Account ID) and `fullname` (Name).

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

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

### metadata (Material Metadata)

You can retrieve metadata about the learning materials registered on the Elice platform. This information can be accessed through the `metadata` property. Metadata information includes `materialId` (Material ID).

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

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