Qualified Embed SDK

Docs for how to use embed a Qualified code challenge into your site.

View an interactive demo here

Quick Start Example

<div data-qualified-embed="507f19cde860e19729a1e810"></div>

<script src="//www.qualified.io/embed.js"></script>
<script type="application/javascript">
window.qualifiedEmbedManager = window.QualifiedEmbed.init({
    // generate editors by looking through nodes
    autoCreate: true,

    // shared options for new editors
    options: {
        authToken: authTokenFromAssessmentInvitation,
        embedClientKey: embedClientKeyFromTeamSettings,
        theme: "dark",
    },

    // challenge-specific options
    challengeOptions: {
        "507f19cde860e19729a1e810": {
            language: "javascript",
            hideTabs: "instructions,idesettings",
        },
    },

    onChange({ manager, editor, challengeId, data }) {
    	// save changes made to the solution
    },
    onRun({ manager, editor, challengeId, data }) {
        console.log("challenge " + challengeId + " was run with this result:");
        console.log(data);
    }
});
</script>

Usage

There are two main ways to use the embedded editor: authenticated and public.

  • Public Means using individual challenges with the embeddable flag set. These challenges will not save solutions back to the Qualified service. This mode lets you build your own system around individual challenges.
  • Authenticated Means inviting a user using the Qualified API, and supplying an authToken to have the candidate take the embedded challenge similar to a full assessment.

You can mix both techniques in the same page, within the same manager. This can be useful for including practice or example challenges within a larger assessment.

Initial Setup

For configuring group of challenges, please use init on window.QualifiedEmbed. Once you've set up your manager, you can create individual editors using QualifiedEmbedManager#createEditor. See QualifiedEmbeddedEditor for the editor functions.

Simple Embedding

If you do not need to interact with the challenge and you do not want to use the QualifiedEmbeddedManager, you can directly embed an iframe and configure some options via the URL. This could be used for static site generators, where you might not have easy access to injecting the embed library.

To learn more about this, see the UrlParams page.

Configuration Details

The Embed SDK includes a lot of functionality to fine-tune your editors. Options can be set on the manager (for shared options across all editors), and further customized on each editor individually.

A complete list of options is available at ChallengeOptions. Below will highlight some of the more useful options.

Appearance Options

These options will help you configure the style and visible components of the editor.

  • mode can be set to readonly or restricted to change how editing and saving works.
  • theme can be forced to be one of light (default) or dark. If you don't set the theme, the user can change the theme in the idesettings tab, and it will sync across editors.
  • hideTabs and showTabs can be used to hide challenge tabs you do not want, such as instructions or idesettings. See TAB_IDS for common tab names.
  • hideActions can be set to true if you want to wrap the Qualified editor with your own custom controls.
  • initialLayout is an advanced option that lets you configure exactly where each editor tab shows up.

Challenge Content Options

These options will help you set up the challenge correctly.

  • language is used to set the language on multi-language classic code challenges.
  • initialFiles is used to override the contents of the files used within the challenge.
  • localStorageId can be set to automatically back up and restore the editor's contents within the browser's localStorage.

Callbacks

The editors provide several callbacks throughout its lifecycle.

  • onLoaded() is called once after the challenge is loaded. It includes information about the loaded challenge.
  • onChange() is called every time the editor's contents change (debounced to prevent too much noise). Use this to build a custom save/restore along with initialFiles.
  • onRun() is called after every completed run of the code. It includes a lot of detailed information about the run results.