SCORM 2004 API Reference
The Scorm2004API class implements the SCORM 2004 4th Edition Run-Time Environment (RTE) specification. This class provides all eight required API methods, sequencing support, global objectives, and utility methods for data management and event handling.
Constructor
new Scorm2004API(settings?: Settings)
Creates a new SCORM 2004 API instance.
Parameters:
settings(optional):Settingsobject to configure API behavior
Example:
import { Scorm2004API } from 'scorm-again/scorm2004';
const api = new Scorm2004API({
autocommit: true,
lmsCommitUrl: 'https://your-lms.com/api/scorm/commit',
logLevel: 'INFO'
});
// Attach to window for SCORM content discovery
window.API_1484_11 = api;With Sequencing:
const api = new Scorm2004API({
autocommit: true,
lmsCommitUrl: 'https://your-lms.com/commit',
sequencing: {
activityTree: {
id: 'root',
title: 'Course',
children: [
{ id: 'module1', title: 'Module 1' },
{ id: 'module2', title: 'Module 2' }
]
}
}
});Core SCORM Methods
These are the eight required API methods defined in the SCORM 2004 specification.
Initialize(param: string): string
Begins a communication session with the LMS.
Parameters:
param: Must be an empty string ("") per SCORM 2004 specification
Returns:
"true"on success"false"on failure
SCORM Specification: Per SCORM 2004 RTE Section 3.1.2.1:
- Parameter must be empty string
- Returns "true" on success, "false" on failure
- Sets error 103 if already initialized
- Sets error 104 if already terminated
- Sets error 101 if parameter is not an empty string
- Initializes the CMI data model for the current attempt
Example:
const result = window.API_1484_11.Initialize("");
if (result === "true") {
console.log("API initialized successfully");
}See Also:
Terminate(param: string): string
Ends the communication session and persists data to the LMS.
Parameters:
param: Must be an empty string ("") per SCORM 2004 specification
Returns:
"true"on success"false"on failure
SCORM Specification: Per SCORM 2004 RTE Section 3.1.2.2:
- Parameter must be empty string
- Commits all data to persistent storage
- Sets error 112 if not initialized
- Sets error 113 if already terminated
- Sets error 101 if parameter is not an empty string
- Processes navigation requests set via
adl.nav.request
Example:
const result = window.API_1484_11.Terminate("");
if (result === "true") {
console.log("Session ended successfully");
}Navigation Processing:
The Terminate method processes any pending navigation request set via adl.nav.request:
// Set navigation request
window.API_1484_11.SetValue("adl.nav.request", "continue");
// Terminate will process the "continue" request
window.API_1484_11.Terminate("");
// Fires "SequenceNext" eventSee Also:
GetValue(element: string): string
Retrieves a value from the CMI data model.
Parameters:
element: The CMI element path (e.g.,"cmi.completion_status")
Returns:
- The value of the element as a string
- Empty string if element has no value or an error occurred
SCORM Specification: Per SCORM 2004 RTE Section 3.1.2.3:
- Returns the value of the specified CMI element
- Returns empty string if element has no value
- Sets error 122 if not initialized
- Sets error 123 if already terminated
- Sets error 401 if element is not implemented (invalid element)
- Sets error 405 if element is write-only
- Sets error 403 if element is not initialized
Example:
const learnerId = window.API_1484_11.GetValue("cmi.learner_id");
const score = window.API_1484_11.GetValue("cmi.score.scaled");
const status = window.API_1484_11.GetValue("cmi.completion_status");Common Elements:
cmi.learner_id- Learner identifiercmi.learner_name- Learner namecmi.completion_status- Completion status (completed, incomplete, unknown)cmi.success_status- Success status (passed, failed, unknown)cmi.score.scaled- Scaled score (-1.0 to 1.0)cmi.location- Bookmark locationcmi.suspend_data- Suspended state datacmi.progress_measure- Progress measure (0.0 to 1.0)
Automatic Evaluation:
Some elements are automatically evaluated based on other values:
// If completion_threshold and progress_measure are set,
// completion_status is automatically calculated
api.SetValue("cmi.completion_threshold", "0.8");
api.SetValue("cmi.progress_measure", "0.9");
const status = api.GetValue("cmi.completion_status"); // Returns "completed"
// If scaled_passing_score and score.scaled are set,
// success_status is automatically calculated
api.SetValue("cmi.scaled_passing_score", "0.7");
api.SetValue("cmi.score.scaled", "0.85");
const success = api.GetValue("cmi.success_status"); // Returns "passed"SetValue(element: string, value: any): string
Sets a value in the CMI data model.
Parameters:
element: The CMI element path (e.g.,"cmi.completion_status")value: The value to set
Returns:
"true"on success"false"on failure
SCORM Specification: Per SCORM 2004 RTE Section 3.1.2.4:
- Sets the value of the specified CMI element
- Sets error 132 if not initialized
- Sets error 133 if terminated
- Sets error 401 if element is not implemented (invalid element)
- Sets error 403 if element is read-only
- Sets error 406 if incorrect data type
- Triggers autocommit if enabled
Example:
window.API_1484_11.SetValue("cmi.completion_status", "completed");
window.API_1484_11.SetValue("cmi.success_status", "passed");
window.API_1484_11.SetValue("cmi.score.scaled", "0.85");
window.API_1484_11.SetValue("cmi.location", "page5");
window.API_1484_11.SetValue("cmi.suspend_data", JSON.stringify({ page: 5 }));Setting Objectives:
// Add an objective
window.API_1484_11.SetValue("cmi.objectives.0.id", "obj_1");
window.API_1484_11.SetValue("cmi.objectives.0.success_status", "passed");
window.API_1484_11.SetValue("cmi.objectives.0.score.scaled", "0.9");
window.API_1484_11.SetValue("cmi.objectives.0.completion_status", "completed");See Also:
Commit(param: string): string
Requests immediate persistence of data to the LMS.
Parameters:
param: Must be an empty string ("") per SCORM 2004 specification
Returns:
"true"on success"false"on failure
SCORM Specification: Per SCORM 2004 RTE Section 3.1.2.5:
- Parameter must be empty string
- Requests immediate persistence of all data since last commit
- Sets error 142 if not initialized
- Sets error 143 if terminated
- Sets error 391 if commit failed
- Does not terminate the communication session
Example:
window.API_1484_11.SetValue("cmi.score.scaled", "0.85");
const result = window.API_1484_11.Commit("");
if (result === "true") {
console.log("Data saved successfully");
}Note: If autocommit is enabled in settings, explicit commits may not be necessary.
GetLastError(): string
Returns the error code from the last API call.
Returns:
- Error code as a string (e.g.,
"0","103","401") "0"if no error occurred
SCORM Specification: Per SCORM 2004 RTE Section 3.1.2.6:
- Returns the error code from the last API call
- Returns "0" if no error occurred
- Can be called at any time (even before Initialize)
- Does not change the current error state
- Should be called after each API call to check for errors
Example:
window.API_1484_11.SetValue("cmi.completion_status", "invalid_value");
const errorCode = window.API_1484_11.GetLastError();
if (errorCode !== "0") {
console.log("Error occurred:", errorCode);
}See Also:
GetErrorString(errorCode: string | number): string
Returns a short description for an error code.
Parameters:
errorCode: The error code to get the description for
Returns:
- Short error description (maximum 255 characters per SCORM spec)
- Empty string if error code is not recognized
SCORM Specification: Per SCORM 2004 RTE Section 3.1.2.7:
- Returns a textual description for the specified error code
- Can be called at any time (even before Initialize)
- Does not change the current error state
- Used to provide user-friendly error messages
Example:
const errorCode = window.API_1484_11.GetLastError();
if (errorCode !== "0") {
const errorString = window.API_1484_11.GetErrorString(errorCode);
console.log(`Error ${errorCode}: ${errorString}`);
}GetDiagnostic(errorCode: string | number): string
Returns detailed diagnostic information for an error.
Parameters:
errorCode: The error code to get diagnostic information for (pass empty string for last error)
Returns:
- Detailed diagnostic information (maximum 255 characters per SCORM spec)
- Empty string if no diagnostic information is available
SCORM Specification: Per SCORM 2004 RTE Section 3.1.2.8:
- Returns detailed diagnostic information for the specified error code
- Implementation-specific; can include additional context or debugging info
- Can be called at any time (even before Initialize)
- Does not change the current error state
- Used for debugging and troubleshooting
Example:
const errorCode = window.API_1484_11.GetLastError();
if (errorCode !== "0") {
const diagnostic = window.API_1484_11.GetDiagnostic(errorCode);
console.log(`Diagnostic: ${diagnostic}`);
}Sequencing Methods
SCORM 2004 includes advanced sequencing and navigation capabilities. Navigation requests are set via adl.nav.request and processed during Terminate().
getActivityTrackingData(activityId: string)
Returns a snapshot of an activity's tracking data, or null if the activity does not exist. Pass the root activity ID to read course-level tracking.
| Field | Type | Meaning |
|---|---|---|
completionStatus | string | Activity completion status |
successStatus | string | Activity success status |
progressMeasure | number | null | Activity's runtime progress measure; does not expose cluster completion rollup |
attemptCompletionAmount | number | Attempt completion amount, including weighted completion rollup for clusters |
attemptCompletionAmountStatus | boolean | Whether the completion amount is known; ignore the amount when false |
score | number | null | Normalized objective measure, or null when unknown |
const course = api.getActivityTrackingData("course");
const percent = course?.attemptCompletionAmountStatus
? Math.round(course.attemptCompletionAmount * 100)
: null;A known amount of 0 is different from unknown progress. Existing progressMeasure and score values retain their meanings. By default, content reports transfer to the activity tree at the end of the attempt, such as during Terminate(); this accessor does not trigger rollup.
processNavigationRequest(request: string, targetActivityId?: string): boolean
Processes an LMS navigation request immediately and returns whether it succeeded. Sequencing must be configured. The LMS uses this method for requests such as start, resumeAll, and suspendAll; SCOs use SetValue("adl.nav.request", ...) and Terminate().
// After a SCO has terminated with cmi.exit = "suspend", suspend the sequencing session.
if (api.processNavigationRequest("suspendAll")) {
const snapshot = api.serializeSequencingState();
// Persist snapshot for the next launch.
}serializeSequencingState(): string exports the sequencing snapshot. deserializeSequencingState(snapshot: string): boolean restores it without starting delivery or converting an interrupted session to a suspended session. SCO-local CMI data must be saved and restored separately. See Closing and Resuming a Player for shutdown and recovery ordering.
Navigation Requests
Set navigation requests using SetValue("adl.nav.request", request):
Available Requests:
"continue"- Move to the next activity (firesSequenceNextevent)"previous"- Move to the previous activity (firesSequencePreviousevent)"{target=activity_id}choice"- Navigate to a specific activity (firesSequenceChoiceevent)"{target=activity_id}jump"- Jump to a specific activity (firesSequenceJumpevent)"exit"- Exit the current activity (firesSequenceExitevent)"exitAll"- Exit all activities and end the session (firesSequenceExitAllevent)"abandon"- Abandon the current activity (firesSequenceAbandonevent)"abandonAll"- Abandon all activities (firesSequenceAbandonAllevent)"suspendAll"- Suspend all activities"_none_"- No navigation request
Example:
// Navigate to next activity
window.API_1484_11.SetValue("adl.nav.request", "continue");
window.API_1484_11.Terminate(""); // Processes the navigation request
// Navigate to specific activity
window.API_1484_11.SetValue("adl.nav.request", "{target=lesson_2}choice");
window.API_1484_11.Terminate("");
// Exit all activities
window.API_1484_11.SetValue("adl.nav.request", "exitAll");
window.API_1484_11.Terminate("");Checking Navigation Validity
Before setting a navigation request, you can check if it's valid:
// Check if choice to specific activity is valid
const isValid = window.API_1484_11.GetValue(
"adl.nav.request_valid.choice.{target=lesson_2}"
);
if (isValid === "true") {
window.API_1484_11.SetValue("adl.nav.request", "{target=lesson_2}choice");
window.API_1484_11.Terminate("");
}Sequencing Events
When navigation requests are processed, corresponding events are fired:
SequenceNext- Move to next activitySequencePrevious- Move to previous activitySequenceChoice- Navigate to chosen activity (target ID passed as parameter)SequenceJump- Jump to activity (target ID passed as parameter)SequenceExit- Exit current activitySequenceExitAll- Exit all activitiesSequenceAbandon- Abandon current activitySequenceAbandonAll- Abandon all activitiesSequenceRetry- Retry current activitySequenceRetryAll- Retry from root activityActivityDelivered- Activity ready for delivery (activity passed as parameter)SequencingComplete- Sequencing process completed (result passed as parameter)SequencingError- Sequencing error occurred (error passed as parameter)
Example:
// Listen for navigation events
api.on("SequenceNext", () => {
console.log("Moving to next activity");
// LMS should load the next SCO
});
api.on("SequenceChoice", (event, target) => {
console.log(`Navigating to activity: ${target}`);
// LMS should load the specified SCO
});
api.on("ActivityDelivered", (event, activity) => {
console.log("Deliver activity:", activity.id);
// LMS should launch the SCO
});Important: The LMS is responsible for actually launching/switching SCOs based on these navigation events. The API handles all sequencing logic but does not control the actual content delivery.
See Also:
Utility Methods
These methods provide additional functionality for data management and API control.
loadFromJSON(json: object): void
Loads CMI data from a hierarchical JSON object.
Parameters:
json: A JavaScript object containing CMI data in hierarchical format
Example:
api.loadFromJSON({
learner_id: "12345",
learner_name: "John Doe",
completion_status: "incomplete",
score: {
scaled: 0.85,
min: 0,
max: 100,
raw: 85
},
objectives: [
{
id: "obj1",
success_status: "passed",
score: { scaled: 0.9 }
}
]
});See Also:
loadFromFlattenedJSON(json: object): void
Loads CMI data from a flattened JSON object.
Parameters:
json: An object with keys representing CMI element paths
Example:
api.loadFromFlattenedJSON({
"cmi.learner_id": "12345",
"cmi.learner_name": "John Doe",
"cmi.completion_status": "incomplete",
"cmi.score.scaled": "0.85",
"cmi.objectives.0.id": "obj1",
"cmi.objectives.0.success_status": "passed"
});getCurrentTotalTime(): string
Calculates and returns the current total time in ISO 8601 duration format.
Returns:
- Total time string in SCORM 2004 format (ISO 8601, e.g., "PT1H23M45S")
Example:
const totalTime = api.getCurrentTotalTime();
console.log("Total time:", totalTime); // "PT1H23M45S"Note: This combines the initial total_time with the current session_time.
reset(settings?: Settings, options?: ResetOptions): void
Resets the API to its initial state, optionally applying new settings.
Parameters:
settings(optional): New settings to merge with existing settingsoptions(optional): Behavior for this reset call only; not stored in API settings
| Option | Default | Effect when true |
|---|---|---|
preserveListeners | false | Retain listeners registered with on() |
resetTotalTime | false | Set cmi.total_time to PT0S after resetting CMI |
Example:
// Reset to default state
api.reset();
// Reset with new settings
api.reset({
logLevel: 'DEBUG',
autocommit: false
});
// Switch SCOs while retaining the player's event handlers.
api.reset(undefined, { preserveListeners: true, resetTotalTime: true });
// Load this SCO's own saved total if it has prior runtime data.
api.loadFromJSON({ cmi: { total_time: savedScoData?.totalTime ?? 'PT0S' } });Without options, reset() clears on() listeners and retains total time, as in previous releases. When preserving listeners, do not register them again after every reset. The host still owns saving and loading runtime data separately for each SCO.
Important for Sequenced Courses:
When using sequencing, reset() clears SCO-specific data but preserves:
- Global objectives
- Sequencing state (current activity, activity tree)
- Navigation state
For a complete reset including sequencing state, you need to create a new API instance.
Warning: This clears SCO-specific CMI data and resets to uninitialized state.
Event Methods
These methods allow you to attach listeners to API events.
on(event: string, callback: Function): void
Attaches an event listener to a specific SCORM event.
Parameters:
event: Event name (e.g.,"Initialize","SetValue","Commit")callback: Function to call when the event occurs
Available Events:
Initialize- Called when API is initializedTerminate- Called when API is terminatedGetValue- Called when a value is retrievedSetValue- Called when a value is setCommit- Called when data is committedGetLastError- Called when error code is requestedGetErrorString- Called when error string is requestedGetDiagnostic- Called when diagnostic is requested- Sequencing events (see Sequencing Methods)
Example:
// Listen for initialization
api.on("Initialize", () => {
console.log("SCORM API initialized");
});
// Listen for specific CMI element changes
api.on("SetValue.cmi.completion_status", (element, value) => {
console.log(`Completion status changed to: ${value}`);
});
// Listen for any SetValue call using wildcard
api.on("SetValue.cmi.*", (element, value) => {
console.log(`${element} set to ${value}`);
});
// Listen for commits
api.on("Commit", () => {
console.log("Data committed to LMS");
});
// Listen for navigation events
api.on("SequenceNext", () => {
console.log("Navigating to next activity");
});See Also:
off(event: string, callback: Function): void
Removes a specific event listener.
Parameters:
event: Event namecallback: The callback function to remove (must be the same reference used inon())
Example:
const myCallback = () => console.log("Initialized");
api.on("Initialize", myCallback);
// Later, remove the listener
api.off("Initialize", myCallback);clear(event: string): void
Removes all listeners for a specific event.
Parameters:
event: Event name
Example:
// Remove all Initialize listeners
api.clear("Initialize");Properties
cmi
The CMI data model object containing all SCORM 2004 data elements.
Type: CMI
Example:
// Direct property access
console.log(api.cmi.learner_name);
console.log(api.cmi.completion_status);
// Modify properties directly (use SetValue instead for proper SCORM compliance)
api.cmi.score.scaled = "0.85";Structure:
cmi: {
_version: string;
comments_from_learner: Array<Comment>;
comments_from_lms: Array<Comment>;
completion_status: string;
completion_threshold: string;
credit: string;
entry: string;
exit: string;
interactions: Array<Interaction>;
launch_data: string;
learner_id: string;
learner_name: string;
learner_preference: {
audio_level: string;
language: string;
delivery_speed: string;
audio_captioning: string;
};
location: string;
max_time_allowed: string;
mode: string;
objectives: Array<Objective>;
progress_measure: string;
scaled_passing_score: string;
score: {
scaled: string;
raw: string;
min: string;
max: string;
};
session_time: string;
success_status: string;
suspend_data: string;
time_limit_action: string;
total_time: string;
}See Also:
adl
The ADL data object containing SCORM 2004 extensions.
Type: ADL
Example:
// Access ADL data
console.log(api.adl.nav.request);
// Set navigation request
api.SetValue("adl.nav.request", "continue");
api.Terminate("");Structure:
adl: {
nav: {
request: string; // Navigation request (write-only)
request_valid: {
continue: string;
previous: string;
choice: Object; // Dynamic validation for choice targets
jump: Object; // Dynamic validation for jump targets
};
};
data: Array<{
id: string;
store: string;
}>;
}Error Codes
SCORM 2004 defines the following error codes:
| Code | Name | Description |
|---|---|---|
| 0 | No Error | No error occurred, the previous API call was successful |
| 101 | General Exception | No specific error code exists to describe the error |
| 102 | General Initialization Failure | Call to Initialize failed for an unknown reason |
| 103 | Already Initialized | Call to Initialize failed because Initialize was already called |
| 104 | Content Instance Terminated | Call to Initialize failed because Terminate was already called |
| 111 | General Termination Failure | Call to Terminate failed for an unknown reason |
| 112 | Termination Before Initialization | Call to Terminate failed because it was made before Initialize |
| 113 | Termination After Termination | Call to Terminate failed because Terminate was already called |
| 122 | Retrieve Data Before Initialization | Call to GetValue failed because it was made before Initialize |
| 123 | Retrieve Data After Termination | Call to GetValue failed because it was made after Terminate |
| 132 | Store Data Before Initialization | Call to SetValue failed because it was made before Initialize |
| 133 | Store Data After Termination | Call to SetValue failed because it was made after Terminate |
| 142 | Commit Before Initialization | Call to Commit failed because it was made before Initialize |
| 143 | Commit After Termination | Call to Commit failed because it was made after Terminate |
| 201 | General Argument Error | An invalid argument was passed to an API method |
| 301 | General Get Failure | Indicates a failed GetValue call where no other specific error code is applicable |
| 351 | General Set Failure | Indicates a failed SetValue call where no other specific error code is applicable |
| 391 | General Commit Failure | Indicates a failed Commit call where no other specific error code is applicable |
| 401 | Undefined Data Model Element | The data model element name passed to GetValue or SetValue is not valid |
| 402 | Unimplemented Data Model Element | The data model element is valid but not implemented by this LMS |
| 403 | Data Model Element Value Not Initialized | Attempt to read a data model element that has not been initialized |
| 404 | Data Model Element Is Read Only | SetValue was called with a read-only data model element |
| 405 | Data Model Element Is Write Only | GetValue was called on a write-only data model element |
| 406 | Data Model Element Type Mismatch | SetValue was called with a value inconsistent with the element's data format |
| 407 | Data Model Element Value Out Of Range | The numeric value supplied is outside the allowed range |
| 408 | Data Model Dependency Not Established | A prerequisite element was not set before the dependent element |
Example Usage:
const result = api.SetValue("cmi.completion_status", "completed");
if (result === "false") {
const errorCode = api.GetLastError();
const errorString = api.GetErrorString(errorCode);
const diagnostic = api.GetDiagnostic(errorCode);
console.error(`Error ${errorCode}: ${errorString}`);
console.error(`Details: ${diagnostic}`);
}Global Objectives
SCORM 2004 supports global objectives that persist across SCO transitions and can be shared between activities via objective mappings.
Configuration:
const api = new Scorm2004API({
renderCommonCommitFields: true,
// Only host-defined rows exposed directly to CMI belong here.
globalObjectiveIds: ['host_defined_objective'],
sequencing: {
// ... sequencing configuration with mapInfo
}
});LMS Integration:
The activity tree's objective mapInfo entries define manifest global-objective mappings; do not duplicate their target IDs in globalObjectiveIds. Structured commits include the synchronized globalObjectives snapshot. Persist it per registration and restore it with restoreGlobalObjectiveSnapshot() before initial delivery.
See Also:
TypeScript Types
import { Scorm2004API, Settings } from 'scorm-again';
const settings: Settings = {
autocommit: true,
lmsCommitUrl: 'https://your-lms.com/commit',
logLevel: 'INFO'
};
const api: Scorm2004API = new Scorm2004API(settings);Related Documentation
- SCORM 2004 Guide - Complete SCORM 2004 data model
- Settings Reference - All available configuration options
- Event Listeners - Event system documentation
- Sequencing - SCORM 2004 sequencing and navigation
- LMS Integration - LMS integration guide
- Multi-SCO Support - Multi-SCO navigation utilities
Host navigation preview
Use previewNavigationRequest("continue" | "previous") to detect a blocked player navigation before terminating the current SCO. It evaluates current reported progress on isolated sequencing state, without changing the live attempt or adl.nav.request_valid semantics. Unsupported predictions return unknown.