SDKの初期化とデータ保存（key-value）

1. メソッド

init（SDKの初期化）

⚠️ SDKで提供されるすべての機能は、initメソッドを通じて初期化が完了した後に使用できます。この関数の実行が完了した後にSDK機能を使用してください。

バニラJSの例

<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の例

// 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に含まれるクエリストリングを解析し、Eliceプラットフォームと連携するための情報である 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は基本的にEliceプラットフォームのproduction環境に設定されています。テスト環境で使用する場合はbaseUrlを引数として設定してください。
```
eliceContents.init({
  baseUrl: 'https://dev-v4-external-contents-api.dev.elicer.io',
});
```

sendScore（Eliceプラットフォームへスコアを送信）

コンテンツがユーザーによってすべて完了した時、スコアをEliceプラットフォームに送信するように構成します。

コンテンツが完了する時点で、@eliceio/content-sdk が提供する sendScore() 関数を呼び出します。関数には score という引数が必要で、通常はコンテンツを完了した際には 100 を送信するようにします。
```
import { eliceContents } from 'src/constants';

eliceContents.sendScore({ score: 100 }); // 100点をEliceプラットフォームに送信
```
上記の説明のようにコンテンツをElice授業資料として設定している場合、授業資料のスコアが図のように100点になるか確認します。

postKeyValue（Eliceプラットフォームに実習変更内容を保存）

学生のコンテンツ変更内容をEliceプラットフォームに保存するには、@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（Eliceプラットフォームに実習変更内容を取得）

学生のコンテンツ変更内容を呼び出す時には、@eliceio/content-sdk が提供する getKeyValue() 関数を使用します。この関数は key に該当する value を呼び出します。

import { eliceContents } from 'src/constants';

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

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

// または次のようにキーの一部のみ入力してそのキーのサブキーをすべて取得できます。
// 区切り文字は常に '.'(ドット)で記述しなければなりません。

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}

    );
};

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 (学習資料メタデータ)

Elice プラットフォームに登録されている学習資料のメタデータを取得できます。この情報は 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 は現在のユーザーの設定言語を示し、型は文字列です。IETF 言語サブタグ形式に従い、デフォルト言語は en です。現在、Elice プラットフォームがサポートしている言語は以下の通りです。

言語	コード
韓国語	`ko`
英語	`en`
日本語	`ja`
タイ語	`th`

1. メソッド​

init（SDKの初期化）​

sendScore（Eliceプラットフォームへスコアを送信）​

postKeyValue（Eliceプラットフォームに実習変更内容を保存）​

getKeyValue（Eliceプラットフォームに実習変更内容を取得）​

delete（key-value削除）​

2. プロパティ​

account (アカウント情報)​

metadata (学習資料メタデータ)​

isTutoringMode (チュータリングモード)​

locale (ロケール)​