SDK 初期化とデータ保存（キーと値）

1. メソッド

init (SDKの初期化)

⚠️ SDKの機能を使用するためには、必ずinitメソッドの実行が完了している必要があります。必ずinitメソッドが完了した後にSDKの機能を使用してください。

Vanilla 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!</div>';

            // 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を解析して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プラットフォームの本番環境に設定されています。テスト環境で使用する場合は、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 }); // スコアを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: 'Elice' // 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); // "Elice"

// または、以下のようにキーの一部だけを入力して、そのキーのサブキー全てを取得することもできます。
// 区切り文字は常に'.'（ドット）で記述する必要があります。

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

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

delete (キーと値の削除)

このメソッドは、Key-Valueストアからキーと値のペアを削除するために使用されます。

パラメータ

名前タイプ説明

名前	タイプ	説明
`key`	`string`	削除するデータのユニークなキーを表します。

key

string

削除するデータのユニークなキーを表します。

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を使用してください。

Eliceプラットフォームにログインしているアカウントの情報を取得することができます。この情報は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 (学習資料のメタデータ)

Eliceプラットフォームに登録されている学習資料のメタデータを取得することができます。この情報はmetadataプロパティを通じて取得することができます。メタデータにはmaterialId(資料ID)が含まれています。

import { eliceContents } from 'src/constants';

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

Last updated 2 months ago