Deep Linking

The /api/deeplinking endpoints implement the Deep Linking Service are used to create Tool Links in the Platform.

Deep Linking Flow¶

The Deep Linking flow starts in the same way as a regular launch, but the user is redirected to a resource selection endpoint instead:

The LTIaaS server will receive the deep linking launch on behalf of the Tool;
Validate the IdToken and store it in the database;
Redirect the user to the Tool's Deep Linking URL, configured during the LTIaaS onboarding process, passing the ltik representing the current launch context.
Tool displays the resource selection screen.
Tool makes a request to the deep linking endpoint with the selected resources.
LTIaaS responds with the generated self-submitting form.
Tool appends form to HTML body.
Form self submits and finalizes deep linking process.

Create Deep Linking form¶

ROUTE	METHOD	AUTHENTICATION METHOD
`/api/deeplinking/form`	`POST`	`LTIK_AUTH_V1`

Request¶

Parameters¶

PARAMETER	TYPE	LOCATION	REQUIRED
`contentItems`	`Array`	`body`	✔️
`options`	`Object`	`body`

contentItems: An array of resources formatted as Content Items following the IMS Content Item specification. The most commonly used type of contentItem is ltiResourceLink, the Tool Link.
options: An object containing one or more of the following fields:
- If the deep linking process succeeded:
  - options.message - Message displayed to the user if the deep linking process is successfully completed.
  - options.log - Log generated by the Platform if the deep linking process is successfully completed.
- If the deep linking process failed:
  - options.errMessage - Message displayed to the user if the deep linking process finishes with an error.
  - options.errLog - Log generated by the Platform if the deep linking process finishes with an error.

Sending options.errMessage or options.errLog will cause the LMS to reject the deep linking submission and display the error message.

Example usage¶

// Calling the API in the backend
app.post('/submit-link', async (req, res, next) => {
  const ltik = req.query.ltik
  const link = {
    contentItems: [{
      type: 'ltiResourceLink',
      url: 'https://your.ltiaas.com?resourceid=123456',
      title: 'Resource'
    }],
    options: { 
      message: 'Deep Linking successful!',
      log: 'deep_linking_successful'
    }
  }
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.post('https://your.ltiaas.com/api/deeplinking/form', { json: link, headers: { Authorization: authorizationHeader } }).json()
  return res.send(response)
})

// Append self-submitting form to HTML body in the frontend
$('body').append(response.form)

Specifying resources when using deep linking¶

The url field of a content item should point to your LTIaaS instance. In order to pass parameters to your Tool and identify the selected resource you can add query parameters to the URL.

Example:

URL passed inside the Deep Linking content item: https://your.ltiaas.com?resource=1234
URL the user will be redirected to after a successful launch from the created resource: https://tool.com?resource=1234

Response¶

Returns a self-submitting form with the signed JWT containing the selected resources that must be appended to the HTML body.

form - Self-submitting form that must be appended to the HTML body.

Example response¶

{ 
  form: '<form id="ltijs_submit" style="display: none;" action="https://ltiadvantagevalidator.imsglobal.org/ltitool/deeplinkresponse.html" method="POST"><input type="hidden" name="JWT" value="eyJhbGciOiJIUzIVCJ9.eyJzdWIbmFtZSI6IG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKV_adQssw5c" /></form><script>document.getElementById("ltijs_submit").submit()</script>' 
}

Create Deep Linking Message¶

If you want to build your own self-submitting form, it is also possible to create only the signed JWT message.

ROUTE	METHOD	AUTHENTICATION METHOD
`/api/deeplinking/message`	`POST`	`LTIK_AUTH_V1`