Embed a track

Integrate Instruqt into your web pages or platform.
This guide explains how to:
​Embed a track into a web page​
​Use the embed url to share direct access to your track in Kiosk mode​
​Customize the embed / Kiosk mode​
​Integrate an embedded track with third-party platforms like an LMS​
Embed a track into a web page
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.
Video tutorial
You can also watch this video tutorial for embedding a track:
Embed a track in an HTML <iframe>
When using embed, people will have unlimited access to your track without any form of authentication. We recommend setting track limits as a safeguard.
Step 1: Copy the embed code
Only team owners and track authors can customise and obtain the embed snippet.
🌐 Web UI
1.Open your browser and go to play.instruqt.com.
↳ Instruqt shows your content.
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:
<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"
    style="border: 0;">
</iframe>
⇨ TEAM , TRACK_NAME, and YOUR_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.
Step 2: Embed the code into your web page
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.
Share a track in Kiosk Mode
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.
How to copy the Kiosk mode link
Only team owners and track authors can configure and obtain the Kiosk Mode link.
🌐 Web UI
1.Open your browser and go to play.instruqt.com.
↳ Instruqt shows your content.  
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, and YOUR_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.
​
Customize the embed
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
Integrating in third-party systems
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.
​Learning Tools Interoperability (LTI)
Which enables you to integrate embedded content using LTI.
Embed custom parameters
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
Embed event callbacks
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.
Events
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
Event payload
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 the track.challenge_* event payloads
the optional total_challenges name/value pair for the track.started, track.completed and  track.challenge_completed events.
Receiving event payloads
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.
Embed example with custom parameters
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.
Run the example web page
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 , and USER_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.
Check the custom parameter through webhooks events
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 the 
 expander arrow.
4.Click Refresh fields.
5.To expand the Test trigger, click the 
 expander 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.
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
Monitor tracks played via a track invite in real time
One time play tokens for embed
Last modified 9d ago