API Events Reference

This reference documents all events available in scorm-again APIs, their payloads, and usage patterns.

Event System Overview

Registering Listeners

Use the on() method to register event listeners:

// Basic event listener
api.on("Initialize", function() {
  console.log("SCO initialized");
});

// With callback receiving data
api.on("SetValue", function(element, value) {
  console.log(`${element} set to ${value}`);
});

Removing Listeners

Use the off() method to remove event listeners:

const myCallback = function(element, value) {
  console.log(`${element} = ${value}`);
};

// Register
api.on("SetValue", myCallback);

// Later, remove
api.off("SetValue", myCallback);

Event Naming Conventions

Events follow the API method names:

SCORM 1.2: LMSInitialize, LMSFinish, LMSGetValue, LMSSetValue, LMSCommit
SCORM 2004: Initialize, Terminate, GetValue, SetValue, Commit

Listener Patterns

Standard Listeners

Listen to any API method call:

api.on("SetValue", function(element, value) {
  // Fires on ANY SetValue call
});

Wildcard Listeners

Match multiple events using dot notation:

// Listen to all SetValue calls for score elements
api.on("SetValue.cmi.score.*", function(element, value) {
  console.log(`Score updated: ${element} = ${value}`);
});

// Listen to all SetValue calls
api.on("SetValue.*", function(element, value) {
  // Fires on every SetValue
});

Element-Specific Listeners

Listen to specific CMI elements:

// SCORM 1.2: Listen only to lesson_status changes
api.on("LMSSetValue.cmi.core.lesson_status", function(element, value) {
  console.log(`Status changed to: ${value}`);
});

// SCORM 2004: Listen only to completion_status changes
api.on("SetValue.cmi.completion_status", function(element, value) {
  updateProgressUI(value);
});

Core API Events

SCORM 1.2 Events

Event	Fires When	Callback Signature
`LMSInitialize`	SCO calls LMSInitialize()	`function()`
`LMSFinish`	SCO calls LMSFinish()	`function()`
`LMSGetValue`	SCO calls LMSGetValue()	`function(element)`
`LMSSetValue`	SCO calls LMSSetValue()	`function(element, value)`
`LMSCommit`	SCO calls LMSCommit()	`function()`
`LMSGetLastError`	SCO calls LMSGetLastError()	`function()`
`LMSGetErrorString`	SCO calls LMSGetErrorString()	`function(errorCode)`
`LMSGetDiagnostic`	SCO calls LMSGetDiagnostic()	`function(errorCode)`

SCORM 2004 Events

Event	Fires When	Callback Signature
`Initialize`	SCO calls Initialize()	`function()`
`Terminate`	SCO calls Terminate()	`function()`
`GetValue`	SCO calls GetValue()	`function(element)`
`SetValue`	SCO calls SetValue()	`function(element, value)`
`Commit`	SCO calls Commit()	`function()`
`GetLastError`	SCO calls GetLastError()	`function()`
`GetErrorString`	SCO calls GetErrorString()	`function(errorCode)`
`GetDiagnostic`	SCO calls GetDiagnostic()	`function(errorCode)`

Commit Events

BeforeTerminate

Fires immediately before termination processing begins. Use for cleanup or final data sync.

api.on("BeforeTerminate", function() {
  // Perform cleanup before termination
  saveAdditionalAnalytics();
});

CommitSuccess

Fires when a commit to the LMS succeeds. Fired by the asynchronous HTTP service (useAsynchronousCommits: true) when the background request resolves; the default synchronous service returns results directly to the SCO instead of firing commit events.

Callbacks receive a CommitEventContext object:

api.on("CommitSuccess", function (context) {
  console.log(context.url);               // commit URL (including any terminate marker)
  console.log(context.trigger);           // "manual" | "autocommit" | "terminate" | "offline-replay"
  console.log(context.isTerminateCommit); // true for the terminate-time commit
  console.log(context.sequence);          // monotonic capture-order sequence number
});

CommitError

Fires when a commit to the LMS fails. The error code remains the first callback argument (unchanged from previous versions); the context object is appended as a second argument:

api.on("CommitError", function (errorCode, context) {
  console.warn("Commit failed", errorCode, context.url, context.trigger);
});

Draining commits before teardown

Player pages can wait for in-flight commits instead of listening for individual events:

// Number of commits currently in flight (always 0 with the default synchronous service)
api.pendingCommitCount;

// Resolves when all in-flight commits settle, or when the timeout elapses
// (best-effort — check pendingCommitCount afterward to detect a timeout)
await api.whenCommitsSettled({ timeoutMs: 4000 });

Offline Events

These events fire when offline support is enabled (enableOfflineSupport: true).

OfflineDataSynced

Fires when queued offline data successfully syncs to the server.

api.on("OfflineDataSynced", function() {
  showNotification("Data synchronized successfully");
});

OfflineDataSyncFailed

Fires when offline data sync fails after all retry attempts.

api.on("OfflineDataSyncFailed", function() {
  showNotification("Sync failed - data saved locally", "warning");
});

SequenceNext

Fires when SCORM 2004 content requests navigation to the next activity.

api.on("SequenceNext", function() {
  // Handle navigation to next SCO
  loadNextActivity();
});

SequencePrevious

Fires when SCORM 2004 content requests navigation to the previous activity.

api.on("SequencePrevious", function() {
  // Handle navigation to previous SCO
  loadPreviousActivity();
});

Sequencing Events (SCORM 2004 Only)

These events are configured via settings.sequencing.eventListeners and provide detailed insight into the sequencing engine.

Configuration

const api = new Scorm2004API({
  sequencing: {
    eventListeners: {
      onActivityDelivery: function(activity) {
        console.log("Deliver activity:", activity.id);
      },
      onSequencingError: function(error, context) {
        console.error("Sequencing error:", error, context);
      }
    }
  }
});

Sequencing Event Reference

Event	Fires When	Payload
`onSequencingStart`	Sequencing session begins	`activity` object
`onSequencingEnd`	Sequencing session ends	None
`onActivityDelivery`	Activity ready for delivery	`activity` object
`onActivityUnload`	Activity being unloaded	`activity` object
`onNavigationRequest`	Navigation request received	`request: string, target?: string`
`onRollupComplete`	Rollup calculation finished	`activity` object
`onSequencingError`	Sequencing error occurred	`error: string, context?: string`
`onSequencingSessionEnd`	Session ending	`{ reason, exception?, navigationRequest? }`
`onAutoCompletion`	Auto-completion triggered	`{ activity: string, completionStatus: string }`
`onAutoSatisfaction`	Auto-satisfaction triggered	`{ activity: string, satisfiedStatus: boolean }`
`onPostConditionExitParent`	Exit parent post-condition	`{ activity: string }`
`onPostConditionExitAll`	Exit all post-condition	`{ activity: string }`
`onTerminationRequestProcessing`	Processing termination	`{ request, hasSequencingRequest, currentActivity }`
`onNavigationRequestProcessing`	Processing navigation	`{ request, targetActivityId }`
`onPostConditionEvaluated`	Post-condition evaluated	`{ activity, result, iteration }`
`onMultiLevelExitAction`	Multi-level exit	`{ activity: string }`
`onSuspendedActivityCleanup`	Cleaning suspended activity	`{ activity: string }`
`onSuspendError`	Suspend operation failed	`{ activity, error }`
`onActivitySuspended`	Activity suspended	`{ activity: string }`
`onDeliveryRequestProcessing`	Processing delivery	`{ request, target }`
`onNavigationValidityUpdate`	Navigation validity changed	`{ continue, previous, choice, jump, hideLmsUi, auxiliaryResources }`
`onLimitConditionCheck`	Limit condition checked	`activity, result: boolean`
`onStateInconsistency`	State inconsistency detected	`{ activity, issue }`
`onGlobalObjectiveMapInitialized`	Global objectives initialized	`{ count: number }`
`onGlobalObjectiveMapError`	Global objective error	`{ error: string }`
`onGlobalObjectiveUpdated`	Global objective updated	`{ objectiveId, field, value }`
`onGlobalObjectiveUpdateError`	Global objective update failed	`{ objectiveId, error }`
`onSequencingDebug`	Debug information	`event: string, data?: any`

Detailed Sequencing Event Examples

onActivityDelivery

The most commonly used sequencing event. Fires when an activity should be delivered to the learner.

onActivityDelivery: function(activity) {
  // activity contains:
  // - id: Activity identifier from manifest
  // - title: Activity title
  // - resourceIdentifier: Resource to launch
  // - parameters: Launch parameters

  const launchUrl = buildLaunchUrl(activity.resourceIdentifier, activity.parameters);
  loadContentFrame(launchUrl);
}

onNavigationValidityUpdate

Fires when available navigation options change. Use to update navigation UI.

onNavigationValidityUpdate: function(data) {
  // data.continue / data.previous: booleans
  // data.choice / data.jump: target ID -> "true" or "false"
  // data.hideLmsUi / data.auxiliaryResources: effective UI data

  updateNavButtons({
    nextEnabled: data.continue,
    prevEnabled: data.previous,
    choiceTargets: Object.keys(data.choice).filter(id => data.choice[id] === "true")
  });
}

onSequencingSessionEnd

Fires when the sequencing session is ending. Use for cleanup or final state persistence.

onSequencingSessionEnd: function(data) {
  // data.reason: Why session ended ("complete", "suspend", "exit", "abandon")
  // data.exception: Sequencing exception code if any
  // data.navigationRequest: The navigation request that triggered end

  if (data.reason === "complete") {
    showCompletionScreen();
  } else if (data.reason === "suspend") {
    showResumePrompt();
  }
}

Multiple Listener Registration

You can register the same callback for multiple events:

function logApiCall(element, value) {
  analytics.track("scorm_api_call", { element, value });
}

// Register for multiple events
api.on("SetValue", logApiCall);
api.on("GetValue", logApiCall);
api.on("Commit", logApiCall);

Cleanup Patterns

Always clean up listeners when the content unloads to prevent memory leaks:

const listeners = {
  onSetValue: function(element, value) { /* ... */ },
  onTerminate: function() { /* ... */ }
};

// Register
api.on("SetValue", listeners.onSetValue);
api.on("Terminate", listeners.onTerminate);

// Cleanup on unload
window.addEventListener("unload", function() {
  api.off("SetValue", listeners.onSetValue);
  api.off("Terminate", listeners.onTerminate);
});

LMS Integration Guide - Main integration guide
Settings Reference - All configuration options
Sequencing Configuration - SCORM 2004 sequencing setup

Event System Overview​

Registering Listeners​

Removing Listeners​

Event Naming Conventions​

Listener Patterns​

Standard Listeners​

Wildcard Listeners​

Element-Specific Listeners​

Core API Events​

SCORM 1.2 Events​

SCORM 2004 Events​

Commit Events​

BeforeTerminate​

CommitSuccess​

CommitError​

Draining commits before teardown​

Offline Events​

OfflineDataSynced​

OfflineDataSyncFailed​

Navigation Events​

SequenceNext​

SequencePrevious​

Sequencing Events (SCORM 2004 Only)​

Configuration​

Sequencing Event Reference​

Detailed Sequencing Event Examples​

onActivityDelivery​

onNavigationValidityUpdate​

onSequencingSessionEnd​

Multiple Listener Registration​

Cleanup Patterns​

Related Documentation​