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:

javascript

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

api.reset() removes all listeners registered with on() by default. To retain them, call api.reset(undefined, { preserveListeners: true }). This option applies to that reset only. Register handlers once when preserving them; otherwise re-register after each reset and before launching content. Callbacks configured through sequencing.eventListeners are always retained. See Handling Activity Transitions for the complete reset and SCO-local data-loading sequence.

Removing Listeners

Use the off() method to remove event listeners:

javascript

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:

javascript

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

Wildcard Listeners

Match multiple events using dot notation:

javascript

// 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:

javascript

// 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.

javascript

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:

javascript

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:

javascript

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:

javascript

// 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.

javascript

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

OfflineDataSyncFailed

Fires when offline data sync fails after all retry attempts.

javascript

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

SequenceNext

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

javascript

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

SequencePrevious

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

javascript

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

javascript

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.

javascript

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.

javascript

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.

javascript

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:

javascript

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:

javascript

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

API Events Reference ​

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 ​

API Events Reference

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