Using window.postMessage in LTI Tools

Canvas listens for events sent through the window.postMessage Javascript API (docs here) from LTI tools and other children rendered in iframes or opened in new tabs/windows. Tools can send various types of events to resize windows, launch in new windows, or other functionality. Note that this is not part of the LTI specification, and is Canvas-specific. In addition, these messages are not currently supported by any of the Canvas mobile apps, only the web version of Canvas.

The data sent to window.postMessage can be of any type, and each message type looks for different data. Most data is sent as an object with a subject property.

Some of these message handlers require the presence of a token, which identifies the tool launch. This token is present in the launch as a custom variable, $com.instructure.PostMessageToken, and should be passed in postMessage calls if it's present.

Message Recipient

Note: Previous versions of this documentation recommended always sending messages to window.top. This is no longer recommended, as tools should target the parent window they are embedded in.

If the LTI tool is launched in a iframe, as is most common, then postMessages should be sent to the window embedding the LTI tool (usually accessible by window.parent). However, if the tool is launched in a new tab, window, or popup, then postMessages should be directed to window.opener. The examples will use window.parent, but in practice, the target recipient can sometimes also be window.opener.

The LTI Platform Storage messages (lti.get_data and lti.put_data) should be sent to either the direct parent frame, or to a named frame that will be present in window.parent.frames. If this named frame is present, it will be returned in the lti.capabilities.response message and also present in the lti_storage_target body parameter in the LTI 1.3 Login and Launch requests. This is also defined in the Platform Storage spec.

Message Responses

Most message handlers will respond with a postMessage with a subject that matches the intial subject, with .response appended. If an error occurs during message handling, the response postMessage will contain an error property with a code and a message.

Sample code for receiving the response messages:

window.addEventListener('message', function (event) {
  // Process response
})

Messages sent by a tool that has been launched from a Canvas mobile app will not receive any response messages.

Message Types

lti.capabilities

At one point, this message type was named 'org.imsglobal.lti.capabilities', but the prefix was dropped before finalizing the spec. This format is no longer supported.

Responds with a list of subjects that Canvas will respond to, and if necessary the named frame to address each subject to. Part of the LTI Platform Storage spec, defined here.

Required properties:

Returning postMessage includes the following properties:

window.parent.postMessage({subject: 'lti.capabilities'}, '*')

lti.put_data

At one point, this message type was named 'org.imsglobal.lti.put_data', but the prefix was dropped before finalizing the spec. This format is no longer supported.

Stores the provided value at the provided key in Canvas's localstorage, partitioned by tool. Data stored by one tool cannot be accessed by another, is only stored in the user's browser, and is short-lived. Part of the LTI Platform Storage spec, defined here.

The spec requires that this message's target origin be set to the platform's OIDC Authorization url as defined here, so that the tool can be certain that Canvas is the entity receiving the message. To enable this feature, Canvas also requires that messages with this target origin are sent to the post_message_forwarding frame, which is a sibling frame to the tool. For now, tools are also still allowed to send this message directly to the parent window and use the wildcard * origin, although this does not conform to the spec.

All LTI login and launch requests include the lti_storage_target parameter, which signals to the tool which frame should receive these messages. The default value is _parent, which means messages should be sent to window.parent. When the value is something else (like post_message_forwarding), the tool should send message to the frame with that name present at window.parent.frames[lti_storage_target].

Note: When a tool is launched from within an active RCE (Rich Content Editor) this sibling frame may not be available, since the RCE uses an iframe to represent the editor box. If the message sent to this frame using this origin doesn't receive a timely response, the tool should fall back to sending the message to the parent window using the wildcard * origin.

Required properties:

Returned postMessage includes the following properties:

window.parent.frames['post_message_forwarding'].postMessage(
  {
    subject: 'lti.put_data',
    key: 'hello',
    value: 'world',
    message_id: '14556a4f-e9af-43f7-bd1f-d3e260d05a9f',
  },
  'http://sso.canvaslms.com'
)

window.parent.postMessage(
  {
    subject: 'lti.put_data',
    key: 'hello',
    value: 'world',
    message_id: '14556a4f-e9af-43f7-bd1f-d3e260d05a9f',
  },
  '*'
)

lti.get_data

At one point, this message type was named 'org.imsglobal.lti.get_data', but the prefix was dropped before finalizing the spec. This format is no longer supported.

Fetches the value stored at the provided key in Canvas's localstorage, partitioned by tool. Data stored by one tool cannot be accessed by another, is only stored in the user's browser, and is short-lived. Part of the LTI Platform Storage spec, defined here.

The spec requires that this message's target origin be set to the platform's OIDC Authorization url as defined here, so that the tool can be certain that Canvas is the entity receiving the message. To enable this feature, Canvas also requires that messages with this target origin are sent to the post_message_forwarding frame, which is a sibling frame to the tool. For now, tools are also still allowed to send this message directly to the parent window and use the wildcard * origin, although this does not conform to the spec.

All LTI login and launch requests include the lti_storage_target parameter, which signals to the tool which frame should receive these messages. The default value is _parent, which means messages should be sent to window.parent. When the value is something else (like post_message_forwarding), the tool should send message to the frame with that name present at window.parent.frames[lti_storage_target].

Note: When a tool is launched from within an active RCE (Rich Content Editor) this sibling frame may not be available, since the RCE uses an iframe to represent the editor box. If the message sent to this frame using this origin doesn't receive a timely response, the tool should fall back to sending the message to the parent window using the wildcard * origin.

Required properties:

Returning postMessage includes the following properties:

window.parent.frames['post_message_forwarding'].postMessage(
  {
    subject: 'lti.get_data',
    key: 'hello',
    message_id: '14556a4f-e9af-43f7-bd1f-d3e260d05a9f',
  },
  'http://sso.canvaslms.com'
)

window.parent.postMessage(
  {
    subject: 'lti.get_data',
    key: 'hello',
    message_id: '14556a4f-e9af-43f7-bd1f-d3e260d05a9f',
  },
  '*'
)

requestFullWindowLaunch

Launches the tool that sent the event in a full-window context (ie not inside a Canvas iframe).

Required properties:

Optional properties:

window.parent.postMessage(
  {
    subject: 'requestFullWindowLaunch',
    data: {
      url: 'https://example-tool.com/launch',
      placement: 'course_navigation',
      launchType: 'new_window',
      launchOptions: {
        width: 1000,
        height: 800,
      },
    },
  },
  '*'
)

toggleCourseNavigationMenu

Opens and closes the course navigation sidebar, giving more space for the tool to display.

Required properties:

window.parent.postMessage({subject: 'toggleCourseNavigationMenu'}, '*')

lti.resourceImported

Notifies the Canvas page holding the tool that a resource has finished importing. Canvas will respond by reloading the page, if the tool was present in the external apps tray. Used on wiki pages.

Required properties:

window.parent.postMessage({subject: 'lti.resourceImported'}, '*')

lti.hideRightSideWrapper

Tells Canvas to remove the right side nav in the assignments view.

Required properties:

window.parent.postMessage(
  {
    subject: 'lti.hideRightSideWrapper',
  },
  '*'
)

lti.frameResize

Tells Canvas to change the height of the iframe containing the tool.

Required properties:

Optional properties:

window.parent.postMessage(
  {
    subject: 'lti.frameResize',
    height: 400,
  },
  '*'
)

lti.fetchWindowSize

Sends a postMessage event back to the tool with details about the window size of the tool's containing iframe.

Required properties:

Returning postMessage includes the following properties:

window.parent.postMessage({subject: 'lti.fetchWindowSize'}, '*')

lti.showModuleNavigation

Toggles the module navigation footer based on the message's content.

Required properties:

window.parent.postMessage(
  {
    subject: 'lti.showModuleNavigation',
    show: true,
  },
  '*'
)

lti.scrollToTop

Scrolls the iframe all the way to the top of its container.

Required properties:

window.parent.postMessage({subject: 'lti.scrollToTop'}, '*')

lti.setUnloadMessage

Sets a message to be shown in a browser dialog before page closes (ie "Do you really want to leave this page?")

Required properties:

window.parent.postMessage(
  {
    subject: 'lti.setUnloadMessage',
    message: 'Are you sure you want to leave this app?',
  },
  '*'
)

lti.removeUnloadMessage

Clears any set message to be shown on page close.

Required properties

window.parent.postMessage({subject: 'lti.removeUnloadMessage'}, '*')

lti.screenReaderAlert

Shows an alert for screen readers.

Required properties:

window.parent.postMessage(
  {
    subject: 'lti.screenReaderAlert',
    body: 'An alert just for screen readers',
  },
  '*'
)

lti.showAlert

Shows an alert using Canvas's alert system, and includes the name of the LTI tool that sent the message.

Required properties:

Optional properties:

window.parent.postMessage(
  {
    subject: 'lti.showAlert',
    alertType: 'warning',
    body: 'An warning to be shown',
    title: 'Tool Name',
  },
  '*'
)

lti.enableScrollEvents

Sends a debounced postMessage event to the tool every time its containing iframe is scrolled.

Required properties:

Returning postMessage includes the following properties:

window.parent.postMessage({subject: 'lti.enableScrollEvents'}, '*')