SDK Initialization and Data Storage (key-value)

1. Methods

init (SDK Initialization)

⚠️ All features provided by the SDK can only be used after the init method has completed initialization. Please ensure that the execution of this function is completed before using any SDK functionality.

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!';

      // Append 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
    });

Use the init() function provided by the installed SDK to initialize the SDK.

1. This function generally parses the query string included in window.location.search to extract the materialId and extToken, which are necessary information for integration with the Elice platform.

   // src/constants.ts
   
   import { EliceContents } from '@eliceio/content-sdk';
   
   export const eliceContents = new EliceContents();
   
   eliceContents.init(); // Initializes by extracting from the query string.

2. If it is difficult to provide required information from window.location.search, you can manually provide the information through the search parameter in the init() function.

   eliceContents.init({
     search: queryString.stringify({
       materialId: 100,
       extToken: '...',
     }),
   });

3. The baseUrl is set by default for the production environment of the Elice platform. To use it in a testing environment, please set the baseUrl as an argument.

   eliceContents.init({
     baseUrl: 'https://dev-v4-external-contents-api.dev.elicer.io',
   });

sendScore (Send Score to Elice Platform)

To send scores to the Elice platform when the user has completed the content, you configure the system to call the sendScore() function provided by @eliceio/content-sdk.

1. Call the sendScore() function at the moment the content is completed, with a parameter named score, typically sending 100 when the content is completed.

   import { eliceContents } from 'src/constants';
   
   eliceContents.sendScore({ score: 100 }); // Send a score of 100 to the Elice platform

2. As explained above, if the content was configured as an Elice educational material, confirm that the score of the educational material is shown as 100 points.

postKeyValue (Save Practice Changes to Elice Platform)

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

import { eliceContents } from 'src/constants';

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

⚠️ Practice changes are saved separately for each user and educational material, so they do not affect other users or educational materials.

⚠️ Key and value writing rules

• Keys must always be written in camelCase, and may only contain alphanumeric characters. ([a-zA-Z0-9]+)
• The possible types for value are string, number, boolean, object, array, and the keys of an object must always be written in camelCase.

getKeyValue (Retrieve Practice Changes from Elice Platform)

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

import { eliceContents } from 'src/constants';

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

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

// You can also enter just part of the key to fetch all sub-keys related to that key.
// The delimiter 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 key-value pairs from the key-value store.

Parameters

Name	Type	Description
key	string	Represents the unique key of the data to be deleted from the 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.

Below are the properties that can be used to retrieve information about accounts logged into the Elice platform. The account information includes the following properties:

Name	Type	Description
uid	number	The unique identifier for the account.
fullname	string	The name of the account holder.
isTutorAccount	boolean	Indicates whether the account is a tutor account.

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 fetch the metadata of learning materials registered on the Elice platform. This information can be retrieved through the metadata property, which includes the materialId (Material ID).

import { eliceContents } from 'src/constants';

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

isTutoringMode (Tutoring Mode)

⚠️ The isTutoringMode property will be deprecated starting from version v1.0.0. Please use eliceContents.tutoring.isEnabled instead.

The isTutoringMode property is used to check if the current user is in tutoring mode. If the user is in tutoring mode, the value is true; otherwise, it is false. Tutoring mode is activated only when a tutor accesses external content of another student via the Elice platform.

import { eliceContents } from 'src/constants';

console.log(eliceContents.isTutoringMode); // false or true

locale (Locale)

The locale property indicates the current user's set language and is of type string. It follows the IETF language subtag format, with the default language being en. The languages currently supported by the Elice platform are as follows:

Language	Code
Korean	ko
English	en
Japanese	ja
Thai	th