Function List

All functions that set a value return true to indicate if they successfully set the value or false to indicate failure. Functions that retrieve values will return null to indicate a failure.

Functions marked with an asterisk (*) may not be supported on all LMSs. Functions that set a value will return false when the element is not supported. Functions that retrieve a value will return the default value for the specified data element.

Start

Start()

Called automatically when the frameset loads. Initializes the API and begins communication with the LMS. Start must be called before any other functions (except Time Tracking functions) may be called. This function is called automatically by the onload event of the indexAPI.html file and it should not need to be called again in most cases.

Exiting

These next four functions represent different ways you can indicate that the content is complete. The primary difference is the reason for leaving the content.

Finish()

Call this function when the user is completely finished with the content. Calling this function is optional, but if you choose not to ever call it, you should change the DEFAULT_EXIT_TYPE constant in Configuration.js to ensure that the content is properly completed (see comments in the file for the exact change).

Suspend()

Call this function when the user wants to pause the content with the intention of resuming later. If you want saved values to be persisted for the next time the user enters the content, it is wise to use the Suspend function to exit the content. In some rare cases, the LMS may choose to only persist data if the content specifically indicates that it is being “suspended”.

TimeOut()

Call this function when the user is being kicked-out of the content because he/she has exceeded the maximum time allowed for completion of the content (see Time Tracking functions below).

Unload()

This function is called automatically when the frameset is unloaded. It ensures that Finish is called if the user just closes out the content. This function should not need to be called in most cases.

SetReachedEnd()

You can optionally call this function to indicate that the user has made sufficient progress in the content to be considered complete. Essentially after calling this function, no matter what type of Finish function above winds up actually getting called when the user exits the content, the LMS will be told that the user finished the content (just as if the Finish function had been called). This function is useful for content that has a final diploma or confirmation page. When that final page is reached, you should call SetReachedEnd, that way if the user closes the browser before initiating an action that calls Finish, the LMS will be told that the user completed the content instead of unloading the content.

ConcedeControl()

This function will pass control back to the LMS and will optionally close the content window or navigate to a specific URL as determined by the EXIT_BEHAVIOR parameter in the configuration file. This function is a useful alternative to calling a specific Finish function. N.B. This function call should originate from a child (or descendent) frame of the indexAPI.html page. It should not be invoked from a popped up window.

Utilities

IsLoaded()

Can be called by child frames to ensure that the API is fully loaded and initialized.

WriteToDebug(strInfo)

The API maintains an extensive set of debug information. This information is basically a log of everything that happens within the API. If you wish to record more information about what is going on in your content, you can call this function to add a line to the debug information.

ShowDebugWindow()

This function will display a new window containing all of the available debug information. As new debug information is recorded, the contents of this window will be updated to reflect the new information. We recommend that you set up some form of event capture within your content that when fired, will call this function to display the current debug information. Alternatively, if you append the querystring parameter ShowDebug=true to the launch URL, the debug window will be displayed as soon as the content launches. A lot of processing occurs before your content is actually loaded, if you need to view the debug information during this time, it can be accessed by clicking on the screen and pressing the question mark key (?) three times consecutively.

GetLastError()

If a function returns a value that indicates an error has occurred (false for functions that set values, null for functions that retrieve values), then you can call this function to get an error code. The error code is an integer and constants representing the possible error codes are defined in APIConstants.js.

GetLastLMSErrorCode()

If the LMS is reporting an error, this returns the code as set by the LMS.

GetLastErrorDesc()

If an error was detected, this function will return a string describing the error in detail. When debugging, it is often useful to combine this information with the information in the debug log.

CommitData()

This function will tell the LMS that you want to ensure all of the data you have sent to it is immediately persisted. Some LMSs will cache data for a while before saving it permanently, invoking this function ensures that any cached data is permanently saved. It is useful to call this function periodically; however excessive use may slow down the content because it may require the LMS to make extra round trips between the client and the server. In most cases, simply setting a value will be sufficient to ensure that it is saved. For cmi5 and Tin Can CommitData must be called at least once to persist the xAPI Statement data to the LRS, because of this requirement it is automatically called by Finish for those standards.

Standard

This property (N.B. This is a property, not a method, so do not use parentheses when reading it.) of the API returns the learning standard being used to communicate with the LMS. Possible values include: “SCORM” (for SCORM 1.1 or SCORM 1.2), “SCORM2004” (for either SCORM 2004 2nd Edition or SCORM 2004 3rd Edition), “AICC”, “CMI5”, “TCAPI” (for Tin Can), or “NONE” (for standalone mode).

Storing and Retrieving General Data

GetStudentID()

Returns the ID of the student currently taking the content. There is no technical reason why you should need this value unless your content is performing some functionality that is outside the scope of the standards or unless the content displays the student’s id. For cmi5 the value is the account.name property of the Agent set as the actor provided by the launching system. For Tin Can the value is the IFI of the Agent provided as the actor by the launching system, in the case of an account IFI only the name property will be returned.

GetStudentName()

Returns the name of the student currently taking the content. Formatted “Last Name, First Name”. For cmi5 and Tin Can the value is determined by the launching system and passed through as the 'actor' query string parameter which is stringified using either the name property or the IFI of the Agent.

SetBookmark(strBookmark, strDesc)

Saves a string that represents the user’s current location in the content. This string can be formatted however you choose as long as it is less than 255 ASCII characters. This function should be called periodically as the user progresses through the content. For cmi5 and Tin Can setting a bookmark additionally queues an xAPI Statement to be sent during the next commit.

GetBookmark()

This function returns the last value that was saved using SetBookmark. If SetBookmark was not called previously, this function returns an empty string. This function is useful to call at the beginning of the content to retrieve the user’s last location and give him/her the option to return to that location.

SetDataChunk(strData)

This function allows you to save a string of data up to 4000 characters. This data can represent anything; it is just an arbitrary chunk of data. This function is useful for saving internal state data that does not correspond to any other data element.

GetDataChunk()

This function returns the last value that was saved using SetDataChunk. If SetDataChunk was not called previously, this function returns an empty string.

GetLaunchData()

When you package your content in a manifest file, you can optionally include a data string that should be passed to the content upon launch. This data is useful for setting configuration options within the content that are not included below in the Preferences functions. GetLaunchData will retrieve this data.

WriteComment(strComment)*

Some LMSs allow the trainee to make comments about the training as he/she is taking it. This function will save a trainee’s comment to the LMS. The total length of all comments cannot exceed 4096 characters. Additionally, the API uses a 3 character delimiter to separate each individual comment.

N.B. This functionality is not supported at all in AICC. The API will return values that you have set using WriteComment during the current session, but values from previous sessions will be lost in an AICC environment. Similarly, it is not supported in Tin Can (although it could be implemented through use of the State API).

GetLMSComments()* - Some LMSs send comments from the administrator to the trainee. This function will retrieve those comments. Returns an empty string if element is not supported.

Time Tracking

These functions allow you to provide functionality based on the time the user has spent in your training module. The total time spent in training is automatically tracked by the API and saved to the LMS when a Finish function is called. These functions only need to be used if you desire more functionality than just reporting total time spent. All Time Tracking functions represent time in milliseconds.

GetPreviouslyAccumulatedTime()

Returns the total number of milliseconds spent in training before this session.

GetSessionAccumulatedTime()

Returns the total number of milliseconds spent in training during this attempt.

SetSessionTime(intMilliseconds)

Call this function to override the automatic time tracking and reporting with a value of your choosing. This function only needs to be called if you want to record a value other than the actual time spent in training.

PauseTimeTracking()

Temporarily pauses the automatic time tracking until ResumeTimeTracking is called. This function is useful if your content implements a pause function and you do not want to report the time spent while the content was paused as time spent in training.

ResumeTimeTracking()

Resumes automatic time tracking after PauseTimeTracking has been called. Note that if you use this function without previously calling PauseTimeTracking the system will treat it as an attempt to start all time tracking from this point on. In other words, you can call this function near the start of the content to begin actual time tracking at a moment other than the initial launch of the content. This functionality could be useful if you only want to record the time spent after any introductory materials have been presented.

GetMaxTimeAllowed()*

Some LMSs will specify the maximum time a trainee may spend attempting a lesson. This function returns that value in milliseconds. If no timeout value is specified, this function will return 36002439990 which is the maximum amount of time that SCORM can store (equivalent to 9999 hours, 99 minutes and 99.99 seconds).

DisplayMessageOnTimeout()*

If the LMS specifies a timeout value, it will likely also specify whether or not you should display a message to the user when his or her time has expired. This function returns true or false to indicate whether or not to display a message.

ExitOnTimeout()*

If the LMS specifies a timeout value, it will likely also specify whether or not you should force the user to exit from the content when his or her time has expired. This function returns true or false to indicate whether or not to forcibly exit.

Scoring

GetPassingScore()*

Some LMSs allow the content to retrieve the score that is necessary for the student to pass the content. This function returns that score as a number (float) between 0 and 100. If no value is specified, the API returns 0.

SetScore(intScore, intMaxScore, intMinScore)

Allows you to record the score that the user achieved in the content to the LMS. In addition, you should also specify the minimum and maximum scores that were available. All scores should be numbers (float) between 0 and 100.

GetScore()

Retrieves a score (float) previously recorded by SetScore. If no score was previously set, this function returns an empty string.

Interactions

The following functions record how the learner responded to various question types. Each function accepts the same set of arguments that will be described once below. Note that there are special packaging requirements for using these functions under AICC, see the AICC packaging section for more detail.

• strID — A unique identifier for the question within your content. This value should be a valid URI.
• response — The response that the learner gave to the question. Each question type has specific requirements for this value’s format.
• blnCorrect — A boolean value that indicates whether or not the answer was correct. This parameter can also accept one of the “interaction result” constants as defined in the APIConstants.js file for finer control.
• correctResponse (optional) — The correct response to the question. Each question type has specific requirements for this value’s format.
• strDescription (optional) — A string describing the interaction (only recorded in SCORM 2004, cmi5, and Tin Can).
• intWeighting (optional) — A number that indicates the importance of this question relative to other questions.
• intLatency (optional) — The number of milliseconds it took for the user to respond to the question.
• strLearningObjectiveID (optional) — The identifier of a learning objective that this interaction is associated with. This identifier could correspond to a value set using the Objectives functions.

Response Identifiers

Some of the interaction recording functions below can accept ResponseIdentifier objects as arguments. The purpose of these objects is to allow you to report the most verbose information possible across systems. Some LMS systems have stringent restrictions on the types of response information that can be recorded. These restrictions, while conformant, are often too strict to be practical, for instance only a single letter can be recorded to report the result of a multiple choice question. To accommodate these systems while still providing verbose information to systems that will accept it, you can create a ResponseIdentifier object which contains both a short and a long version of the result you wish to report. The short version should be a single character that is either a letter or a number. The long version should be a string that is less than 255 characters. A ResponseIdentifier object can be created by calling the CreateResponseIdentifier(strShort, strLong) function.

Record Interactions

RecordTrueFalseInteraction(strID, blnResponse, blnCorrect, blnCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)*

Records the result of a true/false question. blnResponse, blnCorrect, and blnCorrectResponse must each be a JavaScript Boolean.

RecordMultipleChoiceInteraction(strID, aryResponse, blnCorrect, aryCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)*

Records the result of a multiple choice question. aryResponse and aryCorrectResponse can each be either:

• A single character alphanumeric string representing the response
• A single ResponseIdentifier object
• An array of ResponseIdentifier objects representing multiple selections that must be / were made

RecordFillInInteraction(strID, strResponse, blnCorrect, strCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)*

Records the result of a fill-in question. strResponse and strCorrectResponse are both strings, less than 255 characters. In SCORM 2004, LMSs can handle up to 4000 characters.

RecordMatchingInteraction(strID, aryResponse, blnCorrect, aryCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)*

Records the result of a matching question. A matching interaction requires the learner to match items from one set of values with corresponding items in another set of values. The aryResponse and aryCorrectResponse values each must contain both a source and a target for the matching. These value are represented in a MatchingResponse object created with the MatchingResponse constructor (var x = new MatchingResponse(source, target)). aryResponse and aryCorrectResponse can be either:

• A single MatchingResponse object
• An array of MatchingResponse objects representing multiple selections that were made

RecordPerformanceInteraction(strID, strResponse, blnCorrect, strCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)*

Records the result of a performance question. A performance interaction requires the learner to perform a series of steps. Both strResponse and strCorrectResponse are simply represented as a string.

RecordSequencingInteraction(strID, aryResponse, blnCorrect, aryCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)*

Records the result of a sequencing question. A sequencing interaction requires the learner to identify the logical order for members of a list. aryResponse and aryCorrectResponse can be either:

• A string representing the response
• A single ResponseIdentifier object
• An array of ResponseIdentifier objects representing multiple steps that must be/were made

RecordLikertInteraction(strID, response, blnCorrect, correctResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)*

Records the result of a likert question. A likert question asks the user to select from a discrete set of choices along a scale. These are often used for survey questions such as “Rate your experience on a scale from 1 to 10”. response and correctResponse can be either:

• A string representing the response
• A single ResponseIdentifier object

RecordNumericInteraction(strID, strResponse, blnCorrect, strCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)*

Records the result of a numeric question. strResponse and strCorrectResponse are represented by a single number (which may or may not contain a decimal point).

Retrieve Interactions

The following functions retrieve interaction values from the LMS contingent on the content previously reporting those interactions. Put simply, if interactions have been recorded using the prior “Record” functions, those interactions can be retrieved below. It is crucial to note that only SCORM 2004 and cmi5 support the retrieval of interactions. All other standards will return null or empty values.

It is also important to note that each of these methods takes a parameter (strInteractionID) that specifies the interaction being requested. This is the “long” parameter accepted by the ResponseIdentifier when setting the interaction data.

In each case, interactions are implemented using a journaling scheme. This means that each interaction is recorded, even if it has the same identifier. But when requesting these items, only the most recent interaction with that identifier is returned.

GetInteractionType(strInteractionID)*

Returns the type of interaction (as enumerated in APIConstants.js). Possible values include, true-false, matching, etc.

GetInteractionTimestamp(strInteractionID)*

Returns a JavaScript date indicating the time of most recent interaction with this identifier.

GetInteractionCorrectResponses(strInteractionID)*

Returns an array containing each of the correct responses as previously reported by the content. Depending on the type of interaction, this can return a MatchingResponse or a standard string. It is important to note that this always returns an array even if it is a single response.

GetInteractionWeighting(strInteractionID)*

Returns the weighting reported by the content for this interaction.

GetInteractionLearnerResponses(strInteractionID)*

Returns an array containing the learner’s responses as reported previously by the content. Again, this is an array and must be treated as such.

GetInteractionResult(strInteractionID)*

Returns the “correctness” of the response given by the learner and reported by the content.

GetInteractionLatency(strInteractionID)*

Returns the latency (in milliseconds) of the learner in responding to the interaction (as reported previously by the content).

GetInteractionDescription(strInteractionID)*

Returns the description previously provided by the content.

State

These functions allow you to determine the state or status of the content. Possible statuses are described as constants in the APIConstants.js file.

GetStatus()

Returns the current status of the content.

SetPassed()

Sets the current status of the content to passed. If there is a mastery score stored in the LMS (as specified in your content packaging) and if you record a score for the content, then this function does not need to be called; the LMS will automatically compare the score to the mastery score to determine if the content was passed or failed. In cmi5 the comparison to the mastery score will be done in the content, but automatically by Driver. xAPI (and consequently Tin Can) has no concept of a mastery score, so to get a stored passed value you must call SetPassed.

SetFailed()

Sets the current status of the content to failed. If there is a mastery score stored in the LMS (as specified in your content packaging) and if you record a score for the content, then this function does not need to be called; the LMS will automatically compare the score to the mastery score to determine if the content was passed or failed. In cmi5 the comparison to the mastery score will be done in the content, but automatically by Driver. xAPI (and consequently Tin Can) has no concept of a mastery score, so to get a stored failed value you must call SetFailed.

ResetStatus()

Resets the status of the content back to incomplete if you previously set it to passed or failed. In cmi5 status can only be reset up until a commit following a completion or passed.

GetEntryMode()

Determines if the user has previously taken this content. Constants are defined in APIConstants.js that indicate whether this is the user’s first time in the content, whether the user is resuming a previously paused attempt on this content or whether the user has previously completed the content and is now just reviewing it again.

GetLessonMode()

Determines the mode in which the user is taking the content. Constants are defined in APIConstants.js to specify if the user is just browsing the content, is reviewing the content or is making a normal attempt at the content.

GetTakingForCredit()

Determines if the user is taking the content for credit or if the user is just “auditing” the lesson.

Objectives

Some LMSs allow you to record the results of individual objectives within your content. These objectives are arbitrarily determined by the content author but are intended to reflect the completion of distinct sections of your content. Note that there are special packaging requirements for using these functions under AICC, see the AICC packaging section for more detail. In cmi5 and Tin Can, these are no-ops by default. It would be possible, though, to send xAPI statements for virtually anything.

SetObjectiveStatus(strObjectiveID, Lesson_Status)*

Allows you to record the current status of an objective within the content. Possible values for Lesson_Status are defined as constants in the APIConstants.js file and are the same values that may be used for the status of the lesson as whole. Objective ID is a string that uniquely identifies the objective within your content.

GetObjectiveStatus(strObjectiveID)*

Returns the previously set status of an objective. ObjectiveID is the ID that was passed to SetObjectiveStatus to uniquely identify the objective. If no status was previously set for this ID, this function returns LESSON_STATUS_NOT_ATTEMPTED.

SetObjectiveScore(strObjectiveID, intScore, intMaxScore, intMinScore)*

Records the score achieved for a particular objective. ObjectiveID is a string that uniquely identifies the objective within the content. Score is the actual score that the trainee earned while MaxScore and MinScore are the best and worst scores respectively that the trainee could have earned. All scores must be numbers (float) between 0 and 100.

GetObjectiveScore(strObjectiveID)*

Returns the score previously saved for this objective. ObjectiveID is a string that uniquely identifies the objective within this lesson. If no score was previously set, this function returns an empty string.

SetObjectiveDescription(strObjectiveId, strObjectiveDescription)*

Allows you to record a textual description of the objective being saved. ObjectiveID is a string that uniquely identifies the objective within the content. ObjectiveDescription is the text you wish to save. N.B. Objective descriptions are only supported by SCORM 2004.

GetObjectiveDescription(strObjectiveId)*

Returns the description previously saved for this objective. ObjectiveID is a string that uniquely identifies the objective within this lesson. If no description was previously set, this function returns an empty string. N.B. Objective descriptions are only supported by SCORM 2004.

SetObjectiveProgressMeasure(strObjectiveId, strObjectiveProgressMeasure)*

Allows you to record a measure of the progress the learner has made toward completing the SCO. ObjectiveID is a string that uniquely identifies the objective within the content. ObjectiveProgressMeasure is a string representation of a float indicating the progress you wish to save.

GetObjectiveProgressMeasure(strObjectiveId)*

Returns the progress measure previously saved for this objective. ObjectiveID is a string that uniquely identifies the objective within this lesson. If no measure was previously set, this function returns an empty string.

Preferences

SetAudioPreference(PlayPreference, intPercentOfMaxVolume)*

If your content offers audio content, this allows you to save a setting that determines if the user has selected to have that audio content played. You can also save a setting that represents a relative volume at which the user prefers to hear his/her audio. Use the constants PREFERENCE_ON and PREFERENCE_OFF defined in APIConstants.js to pass to the PlayPreference parameter. Use an integer between 1-100 to pass to the intPercentOfMaxVolume parameter (100 is loudest volume, 1 is softest volume).

GetAudioPlayPreference()*

Retrieves the user’s preferred audio play setting as set by SetAudioPreference. If PREFERENCE_ON is returned, the user prefers to hear audio, if PREFERENCE_OFF is returned, the user does not prefer to hear audio. If PREFERENCE_DEFAULT is returned, that user will accept whatever the default setting is for your content. (Constants are defined in APIConstants.js.)

GetAudioVolumePreference()*

Returns an integer between 1 and 100 that indicates the relative volume at which the listener prefers to hear audio. 1 is the softest, 100 is the loudest. Default is 100.

SetLanguagePreference(strLanguage)*

Allows you to save a string that indicates which language the trainee prefers to have content delivered in. This string can be in any format that you choose.

GetLanguagePreference()*

Retrieves the string previously set by SetLanguagePreference. If SetLanguagePreference has not been called before, returns an empty string.

SetSpeedPreference(intPercentOfMax)*

Allows you to save an integer that indicates a relative speed at which the user prefers to experience the content. The integer can be between 1 and 100 with 1 being the slowest and 100 being the fastest. Note that this function is not the same as SetAudioPreference. This function represents the content as a whole while SetAudioPreference only represents the audio within the content.

GetSpeedPreference()*

Returns the integer previously set by SetSpeedPreference. If SetSpeedPreference has not been called before, returns 100.

SetTextPreference(intPreference)*

Allows you to save a setting that determines if the trainee prefers to have a text narration accompanying audio playback. Pass the constants PREFERENCE_ON or PREFERENCE_OFF defined in APIConstants.js.

GetTextPreference()*

Allows you to retrieve a previous text preference value set using SetTextPreference. If SetTextPreference has not been called previously, then PREFERENCE_DEFAULT is returned.

Shared State

Driver includes support for a standard known as IMS Shared State Persistence (SSP). SSP allows content to save arbitrarily large amounts of data in “buckets”. These buckets of data can be shared across different parts of the course. Unfortunately, support for SSP by LMSs is still quite limited so take care when using these functions to be able to gracefully degrade when support is not available.

DetectSSPSupport()

Returns true if the current LMS supports SSP, false otherwise. Use this function to check for support before using other SSP functions.

CreateDataBucket(strBucketId, intMinSize, intMaxSize)*

Before a SSP bucket can be used, it must first be created. strBucketId is a unique identifier you will use to reference this bucket of data. This identifier must be unique within your course (across all SCOs if using a multi-SCO course). Content must also request a storage allotment. intMinSize represents the minimum size you will require for this bucket. intMaxSize represents the maximum size the content could take advantage of. Both size values are represented in characters (i.e. if you need to store a 10,000 character string, send a size request of 10,000 which actually corresponds to 20,000 bytes since JavaScript characters are Unicode). The LMS has the option to grant the max size, the min size or no allotment (N.B. It will always be one of these three values. Nothing in between is allowed). Use the GetBucketInfo function to determine what allotment the LMS granted this bucket.

GetBucketInfo(strBucketId)*

Returns an SSPBucketSize object detailing the total amount of space that was allocated to the specified bucket and the total amount of space currently used in the specified bucket. The SSPBucketSize object has two properties, TotalSpace and UsedSpace, both of which are integers representing a size in characters.

GetDataFromBucket(strBucketId)*

Returns the data currently stored in a bucket as a string.

PutDataInBucket(strBucketId, strData, blnAppendToEnd)*

Adds data to an existing bucket. Setting blnAppendToEnd to true will append the value passed in strData to the end of the existing data in the bucket. Setting blnAppendToEnd to false will replace any existing data with the value stored in strData.