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.

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.

If the LTI tool is launched in a iframe, as is most common, then postMessages should be sent to window.top. Usually window.parent should suffice, but there are some situations where that may not refer to the Canvas window. window.top refers to the topmost parent window, which should always be Canvas. 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.top.

Message Types

requestFullWindowLaunch

Launches the tool that sent the event in a full-window context (ie not inside a Canvas iframe). Mainly used for Safari launches, since Safari disables setting cookies inside iframes.

Required properties:

Optional properties:

window.top.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.top.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.top.postMessage({subject: 'lti.resourceImported'}, '*')

lti.hideRightSideWrapper

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

Required properties:

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

lti.frameResize

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

Required properties:

Optional properties:

window.top.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.top.postMessage({subject: 'lti.fetchWindowSize'}, '*')

lti.showModuleNavigation

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

Required properties:

window.top.postMessage(
  {
    subject: 'lti.frameResize',
    show: true
  },
  '*'
)

lti.scrollToTop

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

Required properties:

window.top.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.top.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.top.postMessage({subject: 'lti.removeUnloadMessage'}, '*')

lti.screenReaderAlert

Shows an alert for screen readers.

Required properties:

window.top.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.top.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.top.postMessage({subject: 'lti.enableScrollEvents'}, '*')