SDK Initialization and Data Storage (Key-Value)

1. Methods

init (SDK Initialization)

⚠️ All functions provided by the SDK can only be used after the initialization is completed through the init method. Please make sure to use SDK features after the execution of this function is completed.

Vanilla JS example

<script defer>
    document.addEventListener('DOMContentLoaded', function() {
        // Initialize EliceContents SDK
        var eliceContents = new EliceContents();
        var rootEl = document.getElementById('root') || document.body;

        eliceContents.init().then(function() {
            // SDK initialization completed
            renderApp();
        }).catch(function() {
            // SDK initialization failed
            console.error('SDK initialization failed');
        });

        function renderApp() {
            // App component content
            var appContent = '<div>Hello, world!</div>';

            // Add App component content to the root element
            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 initialization completed
        return root.render(
            <React.StrictMode>
                <App />
            </React.StrictMode>
        );
    })
    .catch(() => {
        // SDK initialization failed
    });

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

By default, this function parses the query string included in the URL through window.location.search to extract the materialId and extToken information necessary to integrate with the Elice platform.

// src/constants.ts

import { EliceContents } from '@eliceio/content-sdk';

export const eliceContents = new EliceContents();

eliceContents.init(); // Extract from the query string and initialize

If it is difficult to provide information for integration from window.location.search, you can directly provide the information through the search parameter in the init() function.
```
eliceContents.init({
    search: queryString.stringify({
        materialId: 100,
        extToken: '...',
    }),
});
```
By default, baseUrl is set to the Elice platform's production environment. If you want to use it in a test environment, please set the baseUrl as an argument.
```
eliceContents.init({
    baseUrl: 'https://dev-v4-external-contents-api.dev.elicer.io',
});
```

sendScore (Send Score to the Elice Platform)

Configure to send the score to the Elice platform when the user completes the content.

Call the sendScore() function provided by @eliceio/content-sdk when the content is completed. The function requires the score argument, and typically, a score of 100 is sent when the content is completed.
```
import { eliceContents } from 'src/constants';

eliceContents.sendScore({ score: 100 }); // Send 100 points to the Elice platform
```
If the content is set as Elice class material, check if the score of the material becomes 100 as shown in the figure.

postKeyValue (Save Practice Changes to the Elice Platform)

To save a student's content changes on the Elice platform, use the postKeyValue() function provided by @eliceio/content-sdk. This function saves the key and value.

import { eliceContents } from 'src/constants';

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

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

⚠️ Key and value writing rules
The key must always be written in camelCase and consist of alphanumeric characters ([a-zA-Z0-9]+]).
The possible types for the value are string, number, boolean, object, array. The keys of an object must always be written in camelCase.

getKeyValue (Retrieve Practice Changes from the Elice Platform)

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

import { eliceContents } from 'src/constants';

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

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

// Alternatively, you can enter only a part of the key to retrieve all the subkeys of the key.
// The separator must always be '.'(dot).

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

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

delete (Delete key-value)

This method is used to delete a key-value pair from the Key-Value store.

Parameters

Name Type Description

Name	Type	Description
`key`	`string`	The unique key of the data to be deleted from kvstore.

key

string

The unique key of the data to be deleted from kvstore.

JavaScript Example

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 Example

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. Properties

account (Account Information)

⚠️ The account.accountId property will be deprecated starting from version v1.0.0. Please use account.uid instead.

You can retrieve the information of the account currently logged into the Elice platform. The account information can be retrieved through the account property, which includes accountId (Account ID), fullname (Name), and uid (Unified ID).

import { eliceContents } from 'src/constants';

console.log(eliceContents.account); // { accountId: '550e8400-e29b-41d4-a716-446655440000', fullname: 'elice', uid: 123 }

metadata (Learning Material Metadata)

You can retrieve the metadata of the learning material registered on the Elice platform. The information is retrieved through the metadata property, which includes the materialId (Material ID).

import { eliceContents } from 'src/constants';

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

Last updated 2 months ago