Embed tracks

Integrate Instruqt into your web pages or platform.

Overview

Instruqt allows you to embed tracks into your existing sites or share "Kiosk-mode" links to users, with pre-authorized tokens attached. This guide will cover both approaches, and how to customize each.

Only team owners and track authors can customize and obtain these sharing methods.

Embeds and kiosk mode links grant learners unlimited access to your track without any form of authentication. We recommend setting track limits as a safeguard.

HTML iframe

You can generate the <iframe> code snippet for a track using the Instruqt Web UI.

🌐 Web UI

1. Click the track you want to embed in your site.

2. In the header, under the Share dropdown, click Simple Embed.

3. You can optionally customize the embed settings under Customize. As you select options, the iframe code snippet will update.

4. Under the Embed iframe snippet, select Copy embed code. The snippet will look similar to the following:

   <iframe width="1140"
     height="640"
     sandbox="allow-forms allow-modals allow-popups allow-same-origin allow-scripts"
     src="https://play.instruqt.com/embed/instruqt-demos/tracks/example-track?token=em_Q6XaYOhXp3VSVe6K" style="border: 0;"
     allowfullscreen>
   </iframe>

5. Copy and paste the iframe snippet into your site.

Have an LMS? We provide an LTI integration that is preferred over simple embeds.

Kiosk Mode

Kiosk Mode is a direct link to a full-screen version of the embed experience. You can share the Kiosk mode link with your learners directly or integrate it on your website.

🌐 Web UI

1. Click the track you wish to generate a Kiosk Mode link for.

2. In the header, under the Share dropdown, click Simple Embed.

3. You can optionally customize the Kiosk Mode URL under Customize. As you select options, the URL will update.

4. Click Copy link and share with your leaners.

Customization options

The iframe and Kiosk Mode links offer following customization parameters:

Option	Description
Show challenges on splash screen	Provide learners with a preview list of all challenges in the track
Add custom button to finish screen	To provide a "Call to action" to learners after they complete your track, by adding a custom button taking learners to a link.
Customize text on finish screen	Change the default "Great job!" at the end of a track to a custom string.
Disable feedback collection on finish screen	Disable feedback collection if unwanted.

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.

Default URL parameters

All customization options can also be set programmatically by including the customization 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

• finish_text=[YOUR_TEXT]

• disable_feedback=true (default = false)

Custom URL parameters

Custom parameters are similar to UTM parameters in analytics tools. And they give extra contextual information about the current play. For example, 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 custom parameters are also reported for each play in the Plays report.

The following example sets the custom parameter called user_id to the value bob123:

https://play.instruqt.com/embed/TEAM/tracks/EXAMPLE?token=TOKEN&icp_user_id=bob123

Multiple parameters can be specified by separating them with an & symbol:

https://play.instruqt.com/embed/TEAM/tracks/EXAMPLE?token=TOKEN&icp_user_id=bob123&icp_campaign=campaignA

Embed event callbacks

Instruqt sends the folloing events to the parent web page when embedding a track. Instruqt uses the Window.postMessage() API to send these events.

Event Name	Description
track.started	A learner starts a track (clicks "Launch")
track.ready	The track's sandbox is ready to start (loading completed)
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
track.completed	A learner completes a track

You can use these events to store a learner's progress or trigger other events or behaviors in your systems.

One-time play token

You can replace all the tokens referenced above with a one-time play token if desired. You can generate said token using our GraphQL API.

Terminal

Open a terminal and run the following curl command:

cat >query.json <<EOF
{
  "query": "mutation {
    generateOneTimePlayToken(trackID:\"TRACK_ID\") 
  }"
}
EOF

curl -H "Authorization: Bearer YOUR_API_KEY" -X POST -d @query.json https://play.instruqt.com/graphql