Embedding challenges allows you to show one or more challenges on a page. These are great for education & training, but can also be used for quick, low-stakes tests.
When embedding challenges, you can:
- Completely control the candidate experience, including setting the theme and controlling the workflow better.
- Provide inline access to practice or example challenges.
- Override or limit some functionality.
- Enable read-only or restricted editing modes.
- Dynamically change file contents.
Quick Start Example
<div data-qualified-embed="507f19cde860e19729a1e810"></div>
<script src="https://cdn.jsdelivr.net/gh/andela-technology/qualified-embed@v1.0.0-legacy/dist/embed.min.js"></script>
<script type="application/javascript">
window.qualifiedEmbedManager = window.QualifiedEmbed.init({
// generate embeds by looking through nodes
autoCreate: true,
// shared options for new embeds
options: {
// optional authToken for saving results from API call
authToken: authTokenFromAssessmentInvitation,
embedClientKey: embedClientKeyFromTeamSettings,
theme: "dark",
},
// challenge-specific options
challengeOptions: {
"507f19cde860e19729a1e810": {
language: "javascript",
hideTabs: "instructions,idesettings",
},
},
// Common callbacks, can also be set per-challenge
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 embedded challenges: 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 AssessmentInvitations 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.
Embedded Challenge Limitations
The Embed editor is not intended as a 1-to-1 replacement for the dedicated assessment suite. Several features are not available within the embedded app at this time, including:
- Time-Limits are not shown or enforced, either for whole assessments or for individual challenges. If you need to enforce time limits, you should manage them within your application.
- Quiz Challenges are not currently supported at all.
-
Project Code Challenges are presented in a
limited format:
- There is no way to submit project challenges.
- Candidates are not able to add, rename, or delete files.
- There is no file tree.
-
The editor also only shows editable
(
readwrite
) files to the candidate.
- External IDE is not supported.
- For Assessments, your system will be required to mark the assessment as submitted for complete scoring.
If any of the above are necessary for your use case, try embedding full assessments instead.
Initial Setup
For configuring group of challenges, please use
init
on
window.QualifiedEmbed
. Once you've set up your manager, you can create individual
embeds using
QualifiedEmbed#createEditor
. See
QualifiedEmbeddedChallenge
for the editor functions.
Direct Challenge Creation
If you only plan on using a single challenge, and want to control the creation and removal of that challenge through code, you can also create an embedded challenge directly:
var editor = new window.QualifiedEmbeddedChallenge({
node: iframeNode,
challengeId: "507f19cde860e19729a1e810",
options: {
embedClientKey: embedClientKeyFromTeamSettings,
theme: "dark",
language: "javascript",
},
});
Note that this method doesn't allow the use of
autoCreate
.
Simple Embedding
If you do not need to interact with the challenge, 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 embeds. Options can be set on the manager (for shared options across all embeds), and further customized on each editor individually.
Below will highlight some of the more useful options.
A complete list of options is available in
ChallengeOptions
.
Example Appearance Options
These options will help you configure the style and visible components of the editor.
-
mode
can be set toreadonly
orrestricted
to change how editing and saving works. -
theme
can be forced to be one oflight
(default) ordark
. If you don't set the theme, the user can change the theme in theidesettings
tab, and it will sync across embeds. -
hideTabs
andshowTabs
can be used to hide challenge tabs you do not want, such asinstructions
oridesettings
. SeeTAB_IDS
for common tab names. -
hideActions
can be set totrue
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.
Example 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 embedded editor provides several callbacks throughout its lifecycle. Click on any callback for details.
-
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 withinitialFiles
. -
onRunStart()
is called at the start of any run of the code. -
onRun()
is called after every completed run of the code. It includes a lot of detailed information about the run results.