Embed a track
Integrate Instruqt into your web pages or platform.
This guide explains how to:
Embedding is integrating external content into a web page. And Instruqt tracks can be embedded into your web pages. Either as an embed in an HTML <iframe> element or as a link to a track in Kiosk Mode.
Browsers offer Kiosk Mode to run an application full screen without any browser user interface such as toolbars and menus. Kiosk Mode is useful when you need more screen space or want your Instruqt track to run alongside the page that launched the track.
You can also watch this video tutorial for embedding a track:
When using embed, people will have unlimited access to your track without any form of authentication. We recommend setting track limits as a safeguard.
Only team owners and track authors can customise and obtain the embed snippet.
🌐 Web UI
- 1.
- 2.Click the TRACK_NAME of the track you want to embed. ↳ Instruqt shows the corresponding Track overview page.
- 3.In the right sidebar, under Share this track, click Embed track ↳ The Embed page opens. Under
Embed iframe snippet
you will see a code snippet like this:<iframewidth="1140"height="640"sandbox="allow-same-origin allow-scripts allow-popups allow-forms allow-modals"src="https://play.instruqt.com/embed/TEAM/tracks/TRACK_NAME?token=YOUR_GENERATED_TOKEN"style="border: 0;"></iframe>⇨TEAM
,TRACK_NAME
, andYOUR_GENERATED_TOKEN
will contain your team, track name, and token in the src-line. - 4.Optionally, you can choose to customise the embed under Customise. See here for more information. This will update the embed snippet.
- 5.Click Copy embed code.
Code editor
- 1.Open the web page where you want to embed your track in your code editor.
- 2.Paste the copied embed code into the web page's source code.
- 3.Save and deploy the web page.
Kiosk Mode is a direct link to a full-screen version of the embed. You can share the Kiosk mode link with your learners directly or integrate it on your website.
When sharing the Kiosk mode link, people will have unlimited access to your track without any form of authentication. We recommend setting track limits as a safeguard.
Only team owners and track authors can configure and obtain the Kiosk Mode link.
🌐 Web UI
- 1.
- 2.Click the TRACK_NAME of the track you want to share. ↳ Instruqt shows the corresponding Track overview page.
- 3.In the right sidebar, under Share this track, click Share kiosk mode link ↳ The Embed page opens on the Kiosk mode link section. You will see a code snippet like this:https://play.instruqt.com/embed/TEAM/tracks/TRACK_NAME?token=YOUR_GENERATED_TOKEN"⇨
TEAM
,TRACK_NAME
, andYOUR_GENERATED_TOKEN
will contain your team, track name, and token in the src-line. - 4.Optionally, you can choose to customise the embed under Customise. See here for more information. This will update the kiosk link.
- 5.Click to select the URL and then copy it using CTRL/CMD+C (or right-click & copy). You can share this URL with your learners directly or use it to integrate it on your website.
You can customize the embed (and Kiosk mode) to your needs. To do so, go to the Customize section and select:
- Show challenges on splash screen To better manage expectations of your learners.
- Add custom button to the finish screen To control what happens after learners complete your track.
- Button text: what should the button say?
- Button link: where (url) should the button take the user?
- How should the link behave? Should it open in a new tab (default), in the same
_window
, or replace the current iframe only (_self
)?
Updating the embed customization after embedding
If you have embedded or linked to a track and later customize the settings, you will also need to update your embed snippet or Kiosk mode link.
Programatically customising the embed
Both customisation options can also be set programmatically by including the custom parameters in the embed or Kiosk mode url:
showChallenges=true
(default = false)finish_btn_text=[YOUR_BUTTON_TEXT]
finish_btn_url=[YOUR_BUTTON_URL]
finish_btn_target= _blank
,_top
or_self
You can even take embedding one step further by integrating an embedded track with a third-party system like an LMS. You have the following options for this:
- Embed custom parameters Which enables you to send custom parameters to embedded tracks. For example, the learner's user id in an LMS.
- Embed event callbacks Which enables you to receive event information from embedded tracks. For example, a track completed event to store the learner's progress in an LMS.
When you need to integrate an embedded track with a third-party system, it is essential to understand in what context certain events occur. Suppose a learner is playing a track embedded inside your LMS, and you need to match an Instruqt event to the learner inside your LMS. Such as notifying the learner that he skipped a challenge, which influences his scoring rate.
You can send custom parameters to an embedded track to achieve such integrations. Custom parameters are similar to UTM parameters in analytics tools. And they give extra contextual information about the current play. For example, the current user inside your LMS or the origin of this specific track play.
You pass custom parameters at the end of the URL for embedded tracks. Any parameters prefixed with
icp_
will be stored with the learner's track play and propagated to webhook events related to that track play.The following example sets the custom parameter called
user_id
to the value cool101
:https://play.instruqt.com/embed/TEAM/tracks/EXAMPLE?token=TOKEN&icp_user_id=cool101
Multiple parameters can be specified by separating them with an
&
symbol: https://play.instruqt.com/embed/TEAM/tracks/EXAMPLE?token=TOKEN&icp_user_id=cool101&icp_campaign=campaignA
Instruqt sends back events to the parent web page when embedding a track. Instruqt uses the Window.postMessage() API to send these events. You can use these events to store a learner's progress or trigger other events or behaviors in your systems.
Instruqt sends the following events for each track play:
Event Name | Description |
---|---|
track.started | A learner starts playing a track |
track.completed | A learner completes a track |
track.challenge_started | A learner starts a challenge |
track.challenge_skipped | A learner skipped a challenge |
track.challenge_completed | A learner or the platform stopped a track |
The event data that Instruqt sends is formatted in JSON and called the payload. This is an example of the
track.challenge_started
event payload:JSON
{
"event": "track.challenge_started",
"params": {
"track_slug": "getting-started-with-instruqt",
"challenge_slug": "your-first-challenge"
}
}
All event payloads contain the following parts:
- the
event
name/value pair - the
params
object with:- the
track_slug
name/value pair - the optional
challenge_slug
name/value pair for all thetrack.challenge_*
event payloads - the optional
total_challenges
name/value pair for thetrack.started
,track.completed
andtrack.challenge_completed
events.
To receive events payloads, you will need to add an event listener to the web page that has the Instruqt embed. Here is a code snippet of how you might do this:
JavaScript
window.addEventListener("message", (event) => {
// Check the event is from Instruqt
if (event.origin !== "https://play.instruqt.com") {
return;
}
// Event payload is available in event.data
console.log(
"Received event:", event.data.event,
"with params:", event.data.params)
}, false);
This event listener writes received event data to the browser console.
This is an example of a web page with:
- An embedded track in an HTML <iframe> with a custom parameter for the user id.
- An event listener for receiving the event (callback) payload and writing event data to the browser console.
HTML/JavaScript
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Embedded track</title>
</head>
<body>
<iframe
width="1140"
height="640"
sandbox="allow-same-origin allow-scripts allow-popups allow-forms allow-modals"
src="https://play.instruqt.com/embed/TEAM/tracks/TRACK_NAME?token=YOUR_GENERATED_TOKEN&icp_user_id=USER_ID"
style="border: 0;">
</iframe>
<script>
window.addEventListener("message", (event) => {
// Check the event is from Instruqt
if (event.origin !== "https://play.instruqt.com") {
return;
}
// Event payload is available in event.data
console.log(
"Received event:", event.data.event,
"with params:", event.data.params)
}, false);
</script>
</body>
</html>
⇨ Replace
TEAM
, TRACK_NAME
, YOUR_GENERATED_TOKEN
, and USER_ID
with your team, track name, token, and custom parameter for user id.Processing event payload
Notice that the event payload is available in the
event.data
object (lines 27 and 28). The example writes data from this object to the browser console, but you can process the event payload in any way you want with JavaScript. For example, you can use payload data to show learning progress on the current web page or send payload data to an API.- 1.Open your code editor and create a new HTML file.
- 2.Copy the example code and paste it into your new HTML file.
- 3.Replace
TEAM
,TRACK_NAME
,YOUR_GENERATED_TOKEN
, andUSER_ID
with your team, track name, token, and custom parameter for user id. - 4.Save and name the HTML file. You can give it a name like
embeddedtrack.html
. - 5.Open
embeddedtrack.html
in your browser. ↳ Your browser shows the start screen of your embedded track. - 6.Press
F12
in your browser to open the Inspect window. - 7.Click the Console tab.
- 8.Click Launch → in the embedded track. ↳ Instruqt sends an event back to your event listener.
- 9.Notice that your event listener wrote a new entry in the Console tab with content like this:Received event: track.started with params: ► {track_slug: 'TRACK_SLUG'}⇨
TRACK_SLUG
will contain your track slug.
Instruqt propagates custom parameters to Webhook events. Subsequently, this example propagates the
user_id
parameter. To check this out, elaborate on the Webhooks Zapier example:Zapier
- 1.Open your Zap in Zapier.
- 2.Click Edit on your Catch Hook trigger.
- 3.To expand the Setup trigger, click theexpander arrow.
- 4.Click Refresh fields.
- 5.To expand the Test trigger, click theexpander arrow.
- 6.Select the latest request from the Request list. Click Load More if necessary. ↳ Zapier shows the lastest received event data, which contains:
custom_parameters:
**`user_id:`**`USER_ID`\
⇨USER_ID
will contain your user id.
Wow, you are a true Instruqt expert now. You know how to integrate Instruqt with third-party systems, opening a whole new interactive learning world.