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.
- If the deep linking process succeeded:
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 |
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.
- If the deep linking process succeeded:
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/message', { json: link, headers: { Authorization: authorizationHeader } }).json()
return res.send(response)
})
// Building self-submitting formn and appending it to HTML body in the frontend
const form = '<form id="ltijs_submit" style="display: none;" action="' + response.endpoint + '" method="POST"><input type="hidden" name="JWT" value="' + response.message + '" /></form><script>document.getElementById("ltijs_submit").submit()</script>'
return form
$('body').append(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 signed JWT containing the selected resources that must be inserted in a self-submitting form and appended to the HTML body, and the endpoint to which the message has to be submitted to in order to finish the Deep Linking flow.
- message - Signed JWT containing the selected resources that must be inserted in a self-submitting form and appended to the HTML body.
- endpoint - Endpoint to which the message has to be submitted to in order to finish the Deep Linking flow
Example response¶
{
message: 'eyJhbGciOiJIUzIVCJ9.eyJzdWIbmFtZSI6IG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKV_adQssw5c',
endpoint: 'https://ltiadvantagevalidator.imsglobal.org/ltitool/deeplinkresponse.html'
}