1.1 Glossary

For the rest of this document, the following definitions apply:

• Tool Frame: The iframe opened by the learning platform to launch the tool, or the window if the tool was launched in its own tab/window.
• Tool Frame Parent: The Tool Frame immediate parent or the window.opener if the tool was launched in its own tab/window.
• Target Frame: Frame to which should be sent messages. If defined, the target frame must be a direct child frame from the Tool Frame Parent.
• window postMessage - The window.postMessage() method safely enables cross-origin communication between Window objects; e.g., between a page and a pop-up that it spawned, or between a page and an iframe embedded within it. See Mozilla postMessage documentation.

2.1 Target window

In the case of a tool, unless specified otherwise by a message's documentation, the default target window is the parent window of the window the login initiation request was made to or the parent of the window the LTI message . If the parent window object is not available then the window opener should be used instead. If neither window objects are available then postMessage communication is not able to take place.

The target window can usually be determined in the following way through JavaScript:

let target_window = window.parent || window.opener;

In the case of a platform sending a new postMessage, the target window will be the window the login initiation request is made to.

In the case of a tool or a platform responding to a postMessage that it has received, the event source must be used as the window target unless specified otherwise.

The following JavaScript allows the fetching of the event source window:

window.addEventListener('message', function(event) {
    // Validate message
    let target_window = event.source;
    // Send response postMessage
})

2.2 Target frame

The target frame is the window object to which a tool will actually send a postMessage. If not explicitly specified, the target frame is the same as the target window.

A platform may optionally provide the name of the target frame that must be used. The name must refer to a named child of the target window. The name may be passed to the tool via either a query parameter or the capabilities discovery request.

The target frame can be determined in the following way through JavaScript:

let target_window = window.parent || window.opener;
let target_frame = get_target_name() ? target_window.frames[get_target_name()] : target_window;

2.3 Target origin

When making a postMessage request, a target origin must be specified to prevent potentially sensitive information from being sent to a malicious party. Each message type will indicate the requirement for securing the origins of the request.

3.1 Request parameters:

• All messages value must be a Javascript Object.
• Each request must be sent to the Tool Frame Parent unless the message specifies a Target Frame, in which case the message must be sent to that frame.
• Each request message must contain a message_id property with an identifier uniquely identifying this request.
• Each request message must contain a subject property with the message type identifying the interaction. Subject values are specified in each message specification document.

3.2 Response parameters:

• Each response message must contain the message_id property with the identifier value from the request it is responding to.
• Each response message must contain the subject property. Its value must be the value of the request's subject with the .response suffix appended.
• Each response must be posted to the window from where originated the request (i.e. the event.source window)

3.3 Error codes

This specification defines the following error codes. This is an open vocabulary. Message specifications and platforms may define additional codes relevant to their operation when more applicable.

• unsupported_subject: subject is not supported.
• wrong_origin: message event.source is not authorized to send that message.
• bad_request: the request properties are not valid and the message cannot be processed.
• error: a generic error code indicating an error during the processing of the message, to be used when there is not a more specific code available.

3.4 Example postMessages

These examples show the basic format of the post-messages. Any service built on top of these base messages will have their own properties defined within the specification documents describing them.

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

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

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

4.1 Capabilities Request postMessage

This describes the rules for request/response style communication and how it is used to allow a platform to advertise its messaging capabilities i.e. which messages are supported and if there is any restriction on how they need to be accessed.

A tool may at runtime discover the front-end capabilities from the Learning Platform by issuing a request to the parent window. This allows the tool to have a deterministic understanding of the supported interactions rather than relying on heuristic like timeout on message responses to infer no support for messages.

window.parent.postMessage({
  "subject": "lti.capabilities",
  "message_id": "12345"
}, "*")

{
    "message_id": "12345",
    "subject": "lti.capabilities.response",
    "supported_messages": [
        {
            "subject": "lti.capabilities"
        },
        {
            "subject": "lti.example"
        }
    ]
}

window.parent.postMessage({
    "subject": "lti.example", ...
    }, ...)

{
    "message_id": "12345",
    "subject": "lti.capabilities.response",
    "supported_messages": [
        {
            "subject": "lti.capabilities"
        },
        {
            "subject": "lti.example",
            "frame": "platformFrameName"
        }
    ]
}

window.parent.frames["platformFrameName"].postMessage({
    "subject": "lti.example", ...
    }, ...)