What is a SCORM wrapper?

What a SCORM wrapper does

A SCORM wrapper is a small JavaScript library that ships inside the course. It finds the API object the LMS provides, then gives the content simple functions to start a session, read and write tracking data, save, and finish. The LMS supplies the API; the wrapper only locates it and calls it safely.

The reason wrappers exist is that talking to an LMS directly is fiddly. The content has to search the browser's window hierarchy for an object it did not create, work out which version of SCORM that object speaks, check a string return value after every call, and remember to finish the session properly. Every course needs that same plumbing, so authors put it in one reusable file instead of rewriting it per course.

A wrapper does not store anything, send anything over the network, or decide whether the learner passed. It is a thin translation layer between the course logic ("the learner finished page 12") and the specification's calls (SetValue on a data model element, then Commit). Everything the LMS records still goes through the LMS's own API object.

How does it find the LMS API?

SCORM does not give content a URL to post to. Instead, the LMS places a JavaScript object in a window that is an ancestor of the course window, and the course has to go looking for it. The object is called API in SCORM 1.2 and API_1484_11 in SCORM 2004.

The search a wrapper runs follows the discovery approach the specification describes:

1. Check the current window for the API object.
2. If it is not there, move to window.parent and check again, repeating up the frame hierarchy for a bounded number of levels.
3. If the top of that chain is reached without a match, check window.opener (the window that opened a pop-up launch) and walk up its parents the same way.
4. Stop and report failure if nothing is found, rather than looping forever.

A good wrapper also caches the object once found, so later calls do not repeat the search, and tries both names when it does not know in advance which version the course was published for.

function findAPI(win) {
  var tries = 0;
  while (!win.API_1484_11 && !win.API && win.parent && win.parent !== win && tries < 10) {
    tries++;
    win = win.parent;
  }
  return win.API_1484_11 || win.API || null;
}

1.2 and 2004 function names

The two versions expose the same eight operations under different names. A wrapper's main convenience is hiding that difference, so the course calls one function and the wrapper routes it to whichever API it found.

The data model element names differ too: completion lives in cmi.core.lesson_status in 1.2 but is split into cmi.completion_status and cmi.success_status in 2004. Some wrappers map common elements across versions; others leave element names to the course. Either way, every call returns a string — "true" or "false" for the action calls — and a careful wrapper checks it and reads the error code when it is "false". The full call sequence is covered in the SCORM API explained, call by call.

Wrapper vs LMS-side runtime libraries

Search results for "SCORM JavaScript library" mix two different things, and confusing them wastes time.

• A content-side wrapper runs inside the course. It looks for an API object and calls it. It assumes an LMS is already present and providing that object.
• An LMS-side runtime library runs in the player or LMS. It creates the API or API_1484_11 object, receives the course's calls, validates them against the data model, and stores the results. Open-source libraries such as scorm-again sit on this side.

If you are building a course, you want the first. If you are building something that launches courses — a player, a portal, a custom LMS — you want the second. Dropping an LMS-side library into a course does not give it somewhere to save data; it just creates an API object that answers the course and then forgets everything when the window closes.

Common wrapper failures

Most tracking problems that look like LMS bugs start in the wrapper layer. The usual suspects:

• API not found. The LMS launches the course in a new window or a deeper frame than the wrapper searches. The course runs normally and records nothing.
• Calls before initialise. Course code writes progress before the wrapper's initialise call has returned true. Strict platforms reject those writes with an error the course never reads.
• No terminate. The session ends when the tab closes rather than through LMSFinish or Terminate, so some platforms never close the attempt properly.
• Ignored return values. The wrapper calls SetValue but never checks for "false", so an invalid value or an over-length string fails silently.
• Version mismatch. The wrapper finds a 1.2 API but the course writes 2004 element names, or the reverse.

Each of these shows up immediately in a runtime log of the calls and return values, and is invisible without one. The wider pattern of silent tracking loss is covered in why SCORM completions go missing, and platform-specific causes in SCORM not working in your LMS.

Do you need one?

If you publish from an authoring tool, you already have one: every mainstream tool bundles its own wrapper into the export, and you should not replace it. If you are hand-building HTML content, use an established open-source wrapper rather than writing discovery and error handling from scratch; the edge cases above are exactly what mature wrappers have already met. Write your own only when you need behaviour no existing wrapper offers, and test it against more than one LMS launch method before trusting it.

Where SCORM Central fits

SCORM Central converts files you already have — PDF, PowerPoint, Word, or video — into SCORM 1.2, SCORM 2004, cmi5, or xAPI, and shows you the manifest, the full runtime log, and a conformance report on every build, so you can see exactly what a package will report before an LMS does. See how it works, or start with one file.