Skip to main content

Quick Start

This guide will help you create your first SCORM API instance and understand the basic usage patterns.

Creating a SCORM 1.2 API Instance​

Here's the simplest way to create and use a SCORM 1.2 API:

Browser (with script tag)​

// Create API with basic settings
const settings = {
  autocommit: true,
  lmsCommitUrl: 'https://your-lms.com/api/scorm/commit'
};

// Create and attach to window for SCORM content discovery
window.API = new Scorm12API(settings);

// The SCORM content can now find and use the API
// It will call: window.API.LMSInitialize("")

ES Module​

import { Scorm12API } from 'scorm-again/scorm12';

const settings = {
  autocommit: true,
  lmsCommitUrl: 'https://your-lms.com/api/scorm/commit'
};

// Attach to window for SCORM content to discover
window.API = new Scorm12API(settings);

Creating a SCORM 2004 API Instance​

SCORM 2004 follows a similar pattern:

Browser (with script tag)​

// Create API with basic settings
const settings = {
  autocommit: true,
  lmsCommitUrl: 'https://your-lms.com/api/scorm/commit'
};

// Create and attach to window for SCORM content discovery
window.API_1484_11 = new Scorm2004API(settings);

// The SCORM content can now find and use the API
// It will call: window.API_1484_11.Initialize("")

ES Module​

import { Scorm2004API } from 'scorm-again/scorm2004';

const settings = {
  autocommit: true,
  lmsCommitUrl: 'https://your-lms.com/api/scorm/commit'
};

// Attach to window for SCORM content to discover
window.API_1484_11 = new Scorm2004API(settings);

Essential Settings​

Here are the most important settings to get started:

autocommit​

When true, the API automatically saves data to the LMS after a configurable delay (default 60 seconds). This reduces the risk of data loss if the learner closes the browser window.

const settings = {
  autocommit: true,
  autocommitSeconds: 60  // Save after 60 seconds of inactivity
};

lmsCommitUrl​

The URL endpoint where SCORM data should be sent when committing. If not provided, the API will log all calls to the console but won't persist data.

const settings = {
  lmsCommitUrl: 'https://your-lms.com/api/scorm/commit'
};

logLevel​

Control how verbose the logging should be:

const settings = {
  logLevel: 'DEBUG'  // Options: 'DEBUG', 'INFO', 'WARN', 'ERROR', 'NONE'
};

Or use numeric values:

const settings = {
  logLevel: 1  // 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR, 5=NONE
};

Complete Basic Example​

Here's a complete example that demonstrates the typical setup:

import { Scorm2004API } from 'scorm-again/scorm2004';

// Configure the API
const settings = {
  autocommit: true,
  autocommitSeconds: 60,
  lmsCommitUrl: 'https://your-lms.com/api/scorm/commit',
  logLevel: 'INFO'
};

// Create and attach to window
const api = new Scorm2004API(settings);
window.API_1484_11 = api;

// Listen for events (optional but recommended)
api.on('Initialize', () => {
  console.log('SCORM content initialized');
});

api.on('SetValue.cmi.completion_status', (cmiElement, value) => {
  console.log('Completion status changed to:', value);
});

api.on('Terminate', () => {
  console.log('SCORM session terminated');
});

// The SCORM content will now be able to communicate with the LMS

Loading Initial Data​

Before the SCORM content initializes, you can pre-load data from your LMS:

Setting Individual Values​

// Set learner information
window.API_1484_11.cmi.learner_id = "12345";
window.API_1484_11.cmi.learner_name = "John Doe";

// Set previous progress
window.API_1484_11.cmi.completion_status = "incomplete";
window.API_1484_11.cmi.suspend_data = "bookmark=page5";

Loading from JSON​

const initialData = {
  learner_id: "12345",
  learner_name: "John Doe",
  completion_status: "incomplete",
  suspend_data: "bookmark=page5",
  score: {
    scaled: 0.75
  }
};

window.API_1484_11.loadFromJSON(initialData);

Loading from Flattened JSON​

const flattenedData = {
  "cmi.learner_id": "12345",
  "cmi.learner_name": "John Doe",
  "cmi.completion_status": "incomplete",
  "cmi.suspend_data": "bookmark=page5",
  "cmi.score.scaled": "0.75"
};

window.API_1484_11.loadFromFlattenedJSON(flattenedData);

API Discovery Pattern​

important

SCORM content expects to find the API on the window object. This is part of the SCORM specification's API Discovery Algorithm.

For SCORM 1.2, content looks for window.API:

window.API = new Scorm12API(settings);

For SCORM 2004, content looks for window.API_1484_11:

window.API_1484_11 = new Scorm2004API(settings);

If your SCORM player runs in a different frame or window hierarchy, you may need to implement the full API discovery algorithm. See the SCORM API Discovery Algorithms documentation for details.

Accessing CMI Data​

You can directly access the CMI data stored by the API:

SCORM 1.2​

const studentName = window.API.cmi.core.student_name;
const lessonStatus = window.API.cmi.core.lesson_status;
const score = window.API.cmi.core.score.raw;

SCORM 2004​

const learnerName = window.API_1484_11.cmi.learner_name;
const completionStatus = window.API_1484_11.cmi.completion_status;
const scoreScaled = window.API_1484_11.cmi.score.scaled;

TypeScript Example​

For TypeScript projects, you get full type support:

import { Scorm2004API, Settings } from 'scorm-again';

// Settings are fully typed
const settings: Settings = {
  autocommit: true,
  autocommitSeconds: 60,
  lmsCommitUrl: 'https://your-lms.com/api/scorm/commit',
  logLevel: 'INFO'
};

const api = new Scorm2004API(settings);
window.API_1484_11 = api;

// Event handlers are typed
api.on('SetValue.cmi.completion_status', (cmiElement: string, value: string) => {
  console.log(`${cmiElement} set to ${value}`);
});

Data Commit Formats​

scorm-again supports three different formats for sending data to your LMS:

JSON Format (default)​

const settings = {
  dataCommitFormat: 'json'  // Default
};
// Sends: { "cmi": { "learner_id": "123", "completion_status": "completed" } }

Flattened Format​

const settings = {
  dataCommitFormat: 'flattened'
};
// Sends: { "cmi.learner_id": "123", "cmi.completion_status": "completed" }

Query Parameters Format​

const settings = {
  dataCommitFormat: 'params'
};
// Sends: ?cmi.learner_id=123&cmi.completion_status=completed

Next Steps​

Now that you understand the basics, you can:

For a complete list of settings and their descriptions, see the Settings Reference.