SPLICE iframe Protocol: Prior Art

The following sections enumerate known JavaScript APIs and postMessage protocols in existing systems.

TLDR; There are three takeaways:

1. Two JavaScript calls suffice, to send and receive scores and state
2. One needs an iframe message for each of these calls, and another to inform the parent about size changes
3. To nobody’s surprise, everyone’s implementation has minor naming differences

EPUB for Education

A proposed EPUB for Education standard contains a JavaScript API for sending score and state to an EPUB reading system, and for retrieving previously sent scores and state:

EPUB.Education.reportScores([scores], callback)
EPUB.Education.getScores([location], callback)

Each scores object has the form

{ 
   score: number,
   location: string,
   metadata: { /* arbitrary element-specific state */ }
}

When scores are retrieved, the callback function is called with an array of

{ 
   score: number,
   location: string,
   timestamp: UTCTimeStamp,
   metadata: { ... }
}

VitalSource

VitalSource provides an EPUB reading system that is used by prominent textbook publishers including Pearson and Wiley. That reading system implements an earlier version of the EPUB for Education API, where the score information also contained:

• A client-side creation timestamp
• A progress percentage
• A success flag to indicate completion
• A response string (in addition to the state metadata)

VitalSource participated in the EPUB for Education process and presumably found these items unnecessary as standardization progressed.

LTI Client Side postMessages

IMS Global has a proposal, at version 0.1 as of October 17, 2022, for messaging between an iframe containing smart learning content and its parent in the learning platform.

Request structure:

{
  "subject": "lti.example",
  "message_id": "12345",
  …
}

Response structure:

{
  "subject": "lti.example.response",
  "message_id": "12345",
  …
}
Error responses have the format

{
  "subject": "lti.example.response",
  "message_id": "12345",
  "error": {
    "code": "bad_request",
    "message": "A specific useful error message"
  }
}

Defined services include:

• Enumeration of available services (lti.capabilities)
• Storage and retrieval of keyed strings (lti.put_data, lti.get_data)

lti_messaging

The Canvas LMS and others implement a postMessage protocol that is an extension of the preceding proposal. In addition to the capabilities and put_data/get_data messages, there are messages for window sizing and scrolling, alerts, and managing parts of the ambient Canvas UI.

Acos

The Acos server distributes smart learning content to learning management systems using different protocols.

Content can send events by calling

ACOS.sendEvent(eventName, payload, callback)

Two events are defined with names grade and log. The grade event sends an object

{
  points: …,
  max_points: …
}

The log event can send any JSON object.

Events are sent with HTTP POST, not postMessage.

The Acos server does not support saving and restoring state.

TODO: edX XBlock

https://edx.readthedocs.io/projects/xblock-tutorial/en/latest/overview/introduction.html

https://edx.readthedocs.io/projects/xblock-tutorial/en/latest/concepts/events.html

self.runtime.publish(self, "grade",
                    { value: submission_result
                      max_value: 1.0 })

JSAV

The OpenDSA textbooks contain smart learning content in iframes, such as JSAV instances. JSAV is a library for authoring interactive exercises involving data structures such as graphs, trees, and linked lists. JSAV has a logEvent method that can be configured to send messages to the parent frame. Here is a typical message:

{ 
   type: "jsav-exercise-step-fixed", 
   tstamp: "2023-03-20T17:53:37.325Z", 
   av: "DijkstraPE",
   currentStep: 2,
   desc: { score: 0, complete: 0.17 },
   ​​score: { total: 6, correct: 0, undo: 0, fix: 1, student: 0 },
   seed: "580379635345",
   totalTime: 576179,
   tstamp: "2023-03-20T17:53:37.325Z",
   uiid: 1679334241146
}

Codio

Codio is a system for delivering interactive computing courses. It has an internal API for smart learning content with these calls:

codio.assessments.send(iid, state, result)
codio.assessments.get(iid, callback)

Here, state is an arbitrary object, and result a number between 0 and 100. The callback is invoked with an error or { answer: state }.

zyBooks

Zybooks has an IframeWithApi tool that includes an iframe into a book. The iframe is expected to use the PenPal library and make these three calls:

parent.submit(score, state)
state = await parent.getState()
parent.resize(docHeight, docWidth)

CodeCheck Assignments

The CodeCheck Assignments system used to have a proprietary JavaScript API and postMessage API for aggregating content into LTI assignments. It now uses the SPLICE content protocol.

The JavaScript API:

horstmann_config.score_change_listener(element, state, score)
horstmann_config.retrieve_state = function(element, callback)

• element is the root DOM element of the activity, which must have an id
• state is an arbitrary object
• score is a number between 0.0 and 1.0

Upon successful retrieval, callback(element, state) is invoked.

The postMessage format had three query types:

{ query: 'docHeight', param: { docHeight: ... }}
{ query: 'send', param: { id: ..., state: ..., score: ... }} 
{ query: 'retrieve', param: { id: ... }, nonce }

The first two queries have no response. The retrieve query returns { request: /* the entire request */, param: state }

PAWS Cumulate-Adapt2 Protocol

CUMULATE (Centralized User Modeling Architecture for TEaching) collects evidence (events) about student learning from multiple applications. CUMULATE supports a protocol that allows external applications to send learner interaction events for student modeling purposes. In short, to report student activity, the external application should indicate what learning object the student (user) is working on, who the student is, and what the outcome of this interaction is (success/failure).

External applications send the interaction logs using HTTP GET requests to the CUMULATE’s report servlet using the following URL format:

http://<server>?app=<application>&act=<learning_object>&sub=<learning_object_step>
&usr=<learner>&grp=<group>&sid=<session_id>&res=<result>&svc=<service_parameters>

• app – application id denoting the application that the student is working with (required)
• act – learning object, the student is working with (required)
• sub – the step of the learning object (mandatory/optional depending on application)
• usr – student id whose activity is reported (mandatory)
• grp – group or class or section that student belongs to (mandatory)
• sid – session id, a token of up to 5 characters (mandatory)
• res – result of the interaction, 0 if unsuccessful, 1 if successful, or any value in between in case of partial success, -1 is reserved for "no credit" activities such as viewing a worked example (mandatory)
• svc – an arbitrary string the application might want to store for later (e.g. capturing context), not parsed by user modeling server (optional)

Example request URL:

http://adapt2.sis.pitt.edu/cbum/um?app=3&act=helloworld.c&sub=12&usr=myudelson&grp=200721&sid=FD34A&res=1&svc=adaptive_link

For more details, please visit these pages: Cumulate and Cumulate Protocol Related publications:

1. Zadorozhny, V., Yudelson, M., and Brusilovsky, P. (2008) A Framework for Performance Evaluation of User Modeling Servers for Web Applications. Web Intelligence and Agent Systems 6(2), 175-191. DOI
2. Yudelson, M., Brusilovsky, P., and Zadorozhny, V. (2007) A user modeling server for contemporary adaptive hypermedia: An evaluation of the push approach to evidence propagation. In Conati, C., McCoy, K. F., and Paliouras, G. Eds., User Modeling, volume 4511 of Lecture Notes in Computer Science, pp 27-36. Springer, 2007. PDF DOI
3. Brusilovsky, P., Sosnovsky, S. A., and Shcherbinina, O. (2005). User Modeling in a Distributed E-Learning Architecture. Paper presented at the 10th International Conference on User Modeling (UM 2005), Edinburgh, Scotland, UK, July 24-29, 2005. PDF DOI

OpenDSA Implementation:

OpenDSA is an interactive eTextbook platform that provides comprehensive support for a range of Computer Science-related topics such as Data Structures and Algorithms, Formal Languages, Programming Languages, and more. OpenDSA is LTI powered and also supports a seamless communication of scores, progress tracking, and student data between the tool and the LMS. OpenDSA offers a collection of exercise types, with the most commonly used being Khan Academy-style exercises and JSAV exercises. The light weight protocol has been integrated to collect scores, state and interactions from both exercise types currently and can be sent back to maybe a server or a parent page.

These are some potential use cases for the light weight protocol for OpenDSA

1. External Tool Integration: OpenDSA can act as an external tool, the exercises can be embedded within other systems via an iframe. In this scenario, the scores and student progress data collected from OpenDSA exercises can be transmitted back to the parent HTML or any server.
2. Server Interaction and Grade Passback: The lightweight protocol can also facilitate server-side communication. In this use case, student scores are sent directly to OpenDSA server and then to the LTI service for grade passback in the LMS.

---

Contact us

Last updated: