Helpers

A selection of useful helpers.

getLaunchParameters

This gets the launch parameters supplied in the URL. Can be used before initializing.

Example

import Cmi5, { LaunchParameters } from "@xapi/cmi5";

const cmi5 = new Cmi5();

const launchParameters: LaunchParameters = cmi5.getLaunchParameters();

Returns

This returns a LaunchParameters object.

getLaunchData

This gets the launch data from the LMS. Can not be used before initializing the AU.

Example

import Cmi5, { LaunchData } from "@xapi/cmi5";

const cmi5 = new Cmi5();

cmi5.initialize().then(() => {
  const launchData: LaunchData = cmi5.getLaunchData();
});

Returns

This returns a LaunchData object.

getAuthToken

This gets the session's authToken. Useful for storing in non-volatile storage local to the user (e.g. SessionStorage) to preserve the state between page refreshes. Pass this value and initializedDate to initialize to restore the previous session.

Example

// Storing the auth token
const cmi5 = new Cmi5();

cmi5.initialize().then(() => {
  const authToken = cmi5.getAuthToken();
  sessionStorage.set("cmi5-auth-token", authToken);
});

// Restoring the auth token in a new Cmi5 instance
const cmi5 = new Cmi5();
const authToken = sessionStorage.get("cmi5-auth-token");

cmi5.initialize({
  authToken,
  initializedDate: ...
});

Returns

This returns a string or null if the Cmi5 instance has not been initialized.

getInitializedDate

This gets the session's initializedDate. Useful for storing in non-volatile storage local to the user (e.g. SessionStorage) to preserve the state between page refreshes. Pass this value and authToken to initialize to restore the previous session.

Example

// Storing the auth token
const cmi5 = new Cmi5();

cmi5.initialize().then(() => {
  const initializedDate = cmi5.getInitializedDate();
  sessionStorage.set("cmi5-initialized-date", initializedDate);
});

// Restoring the initialized date in a new Cmi5 instance
const cmi5 = new Cmi5();
const initializedDate = new Date(sessionStorage.get("cmi5-initialized-date"));

cmi5.initialize({
  initializedDate,
  authToken: ...
});

Returns

This returns a Date or null if the Cmi5 instance has not been initialized.

getLearnerPreferences

This gets the learner preferences from the LMS. Can not be used before initializing the AU.

Example

import Cmi5, { LearnerPreferences } from "@xapi/cmi5";

const cmi5 = new Cmi5();

cmi5.initialize().then(() => {
  const learnerPreferences: LearnerPreferences = cmi5.getLearnerPreferences();
});

Cmi5.isCmiAvailable

This returns true if the environment has all the necessary parameters for initialisation.

Example

import Cmi5 from "@xapi/cmi5";

const isCmiAvailable: boolean = Cmi5.isCmiAvailable();

Returns

This returns a Boolean.

isAuthenticated

This returns true if the instance constructed successfully.

Example

import Cmi5 from "@xapi/cmi5";

const cmi5 = new Cmi5();

cmi5.initialize().then(() => {
  const isAuthenticated: boolean = cmi5.isAuthenticated();
});

Returns

This returns a Boolean.

Cmi5.instance

Creates a new Cmi5 singleton instance, or if already called returns the same singleton Cmi5 instance.

Example

import Cmi5 from "@xapi/cmi5";

const cmi5instance: Cmi5 = Cmi5.instance;

Returns

This returns a global Cmi5 singleton instance.

Cmi5.clearInstance

Clears the Cmi5 singleton instance.

Example

import Cmi5 from "@xapi/cmi5";

const cmi5instance: Cmi5 = Cmi5.instance;

Cmi5.clearInstance();

moveOn

Automatically satisfies the AU based upon the Launch Data from the LMS. It will send the "cmi5 defined" statements for:

• Pass or fail if a score is provided and the mastery score is configured

• complete statement

• terminate statement (unless disabled in the options parameter)

Example

import Cmi5 from "@xapi/cmi5";

const cmi5 = new Cmi5();

// initialize etc

cmi5.moveOn();

Parameters

Parameter	Type	Required	Description
options	MoveOnOptions	false	The additional options object.

This returns a Promise containing an array with the resulting statementIds if successful.

Cmi5.xapi

Returns the internal xAPI.js Wrapper library instance. Useful for accessing any xAPI Resources using the Cmi5 authentication. Can only be accessed after successfully calling the initialize method.

Example

import Cmi5 from "@xapi/cmi5";
import XAPI from "@xapi/xapi"; // For types as a developer dependency, not required but may be useful!

const cmi5: Cmi5 = new Cmi5();
await cmi5.initialize();

const xapi: XAPI = cmi5.xapi;
xapi.getStatement(...);

Returns

This returns the internal XAPI instance, authenticated with the LRS endpoint and authentication token.