Qualified Embed SDK

Interface: ChallengeOptions

ChallengeOptions

The available options for a challenge options hash.

Members

authToken :string

The authToken value from an AssessmentInvitation. This token allows a candidate to solve an embedded challenge and save the results back as a normal assessment.

This property is not used if the challenge is not storing the results back on an assessment result.

Type:
  • string

embedClientKey :string

The unique embed client key value set on your team.

Type:
  • string

autoStart :boolean

For embedded challenges with an authToken, this automatically starts the assessment and creates the solution when the embedded editor loads.

When false (the default), the user will need to click a button to start the challenge. This is recommended on pages with multiple embedded challenges, otherwise start times won't be very useful.

When the mode is readonly or restricted, this option is ignored.

Type:
  • boolean

mode :null|"readonly"|"restricted"

Enables setting up the editor in different read-only modes.

  • null The default, normal mode with full editing and saving.
  • "restricted" Means you can edit the code, but changes will never be saved, or sent back to the parent window.
  • "readonly" Means you cannot edit the code at all. Useful for reviewing-only, without making changes. This also disables running code.
Type:
  • null | "readonly" | "restricted"

language :string

Language to use on classic code challenges. This is recommended for multi-language challenges, as the user is not provided a way to change the language within the editor.

You can provide your own list of available languages using the results from the ChallengeOptions#onLoaded callback event.

Type:
  • string

theme :null|"light"|"dark"

Force the theme for this editor (one of light or dark). Leave unset to let the user select their own theme from the idesettings tab.

Type:
  • null | "light" | "dark"
Default Value:
  • "light"

hideTabs :string

Comma-delimited list of tabs to hide by tab ID or file path, overrides ChallengeOptions#showTabs.

Type:
  • string
See:
  • TAB_IDS for a list of common tab IDs.

showTabs :string

Comma-delimited list of tabs to show by tab ID or file path. When this is set, the default state is to show no tabs at all.

Type:
  • string
See:
  • TAB_IDS for a list of common tab IDs.

hideActions :boolean|"attempt"|"runTests"

If true, hides the list of actions in the upper left. This could be useful if you are wrapping this in your own interface.

The user will still be able to run the code using the shortcut keys (CMD/CTRL + ' or CMD/CTRL + Enter).

For Classic Code challenges, you can choose to only show RUN TESTS. Set the value of hideActions to "attempt". This hides the SUBMIT button, and disables running the code against the final submission tests. This could be useful for practice code or simple demo code.

To achieve the reverse (only allowing hidden tests), either configure the challenge without Sample Test Cases, or set the value of hideActions to runTests. Simply hiding the tab will not disable the button, which could be used if you want to configure an external editor.

Type:
  • boolean | "attempt" | "runTests"
Default Value:
  • false

initialLayout :Object

Override the default layout for the challenge. This does not replace ChallengeOptions#hideTabs or ChallengeOptions#showTabs, which are still used to define tab visibility. Visible tabs that are not listed in initialLayout are left in their default positions.

The first tab in each section will be the "active" tab when the editor loads.

Type:
  • Object
Properties:
Name Type Description
topLeft Array.<string>

List of tab IDs or file paths for the top left section of the editor.
Defaults to any editable files.
topRight Array.<string>

List of tab IDs or file paths for the top right section of the editor.
Defaults to all other tabs.
bottomLeft Array.<string>

List of tab IDs or file paths for the bottom left section of the editor.
Defaults to empty, and not recommended for smaller challenges.
bottomRight Array.<string>

List of tab IDs or file paths for the bottom right section of the editor.
Defaults to empty, and not recommended for smaller challenges.
See:
  • TAB_IDS for a list of common tab IDs.

initialFiles :Object

Sets the initial solution values on the challenge. Note that this will only be processed when the challenge is first loaded, and if there isn't an existing solution.

To change the solution content later, please use QualifiedEmbeddedChallenge#setFileContents.

Type:
  • Object
Properties:
Name Type Description
(path) string

Contents of each file. Use the file path as the key for project challenges, or code and testcases for classic challenges.

initialCursor :ChallengeOptions~Cursor

Sets the initial cursor position. Note that this will only be processed when the challenge is first loaded, and if there isn't an existing solution.

To change the cursor position later, please use QualifiedEmbeddedChallenge#setFileContents.

Type:

initialRunResult :ChallengeOptions~RunResult

Provides an initial run result, which should be the eventData.data returned from ChallengeOptions#onRun, QualifiedEmbeddedChallenge#runTests, or QualifiedEmbeddedChallenge#attempt.

This can include the fileData property, which will configure the entire solution at once. If ChallengeOptions#initialFiles or ChallengeOptions#initialCursor are provided, they will overwrite the values in fileData.

Type:

localStorageId :string

If provided, automatically saves and restores the contents of the challenge in localStorage using the given id as a key. This will also restore the last cursor position.

The data will automatically be serialized using the challengeId so you can use the same localStorageId value for the entire page of challenges (or even across multiple pages).

Note 1: Using this feature will override anything set in ChallengeOptions#initialFiles. If you want to replace the localStorage contents, you"ll need to call QualifiedEmbeddedChallenge#setFileContents using the ChallengeOptions#onLoaded event callback.

Note 2: The solution data will be stored on the domain of the parent frame, not on qualified.io. Also, the embed will never delete this data, so it is up to the outer page to manage its localStorage.

Type:
  • string

baseURL :string

Override the base URL of the Qualified application for testing and debugging.

Type:
  • string

Methods

onLoaded(eventData)

Callback for when the editor has loaded.

This callback is always called at least once, and can be called multiple times.

  • Before a solution is created (when provided an authToken), it will be called with started set to false.
  • It will always be called when the editor is ready to solve, with started set to true. This may be the first time it's called.
  • It will also be called again if there are changes that affect the challenge details, such as changing the challengeId, or the solution language.
Parameters:
Name Type Description
eventData Object
Properties
Name Type Description
manager QualifiedEmbedManager

Manager for this event
editor QualifiedEmbeddedChallenge

Editor for this event
challengeId string

Challenge ID of the editor for this event
data ChallengeOptions~LoadData

Information about the challenge, will also be stored in QualifiedEmbeddedChallenge#challengeData for future access.

onChange(eventData)

Callback with changes any time an embedded challenge solution is modified. It is also called when the solution is initially set up.

When the mode is readonly or restricted, this callback is not triggered.

Parameters:
Name Type Description
eventData Object
Properties
Name Type Description
manager QualifiedEmbedManager

Manager for this event
editor QualifiedEmbeddedChallenge

Editor for this event
challengeId string

Challenge ID of the editor for this event
data ChallengeOptions~FileContentsData

File Change Data

onRunStart(eventData)

Called when a run is started (internally or externally).

Note: if you want to better link run start to run results, it might be easier to use QualifiedEmbeddedChallenge#runTests and QualifiedEmbeddedChallenge#attempt directly, and disable the internal buttons. This allows you to link the start with the result, as those methods return a promise on completion.

Parameters:
Name Type Description
eventData Object
Properties
Name Type Description
manager QualifiedEmbedManager

Manager for this event
editor QualifiedEmbeddedChallenge

Editor for this event
challengeId string

Challenge ID of the editor for this event
data.type "test" | "attempt"

Type of run
data.fileData ChallengeOptions~FileContentsData

File data at beginning of run

onRun(eventData)

Callback with the results when any embedded challenge is run against tests, or classic code is attempted.

Parameters:
Name Type Description
eventData Object
Properties
Name Type Description
manager QualifiedEmbedManager

Manager for this event
editor QualifiedEmbeddedChallenge

Editor for this event
challengeId string

Challenge ID of the editor for this event
data ChallengeOptions~RunResult

Results of the code run

Type Definitions

LoadData

Data about the loaded challenge, solution, and more. Can be useful for rendering options for the candidate, such as language selection.

Properties:
Name Type Description
error string

If set, there was an error loading the challenge (invalid ID or restrictions)
started boolean

True if the editor is ready to solve.
solutionId string

If there's an assessment result, this will be the ID of the solution for this challenge.
solutionLanguage string

For Classic Code challenges, this is the current language being used for solving.
type string

Type of challenge ("CodeChallenge" or "AdvancedCodeChallenge")
title string

Title of challenge
summary string

Summary text on challenge, in Markdown
languages Array.<string>

List of languages available on the challenge
availableTabs Array.<string>

List of tabs available on the challenge (for hideTabs or showTabs)
fileData ChallengeOptions~FileContentsData

Current file contents (if available)

FileContentsData

File contents data

Properties:
Name Type Description
files Object

Hash of file name or path to file contents to be set on the challenge solution.

Properties
Name Type Description
(path) string

Contents of each file. Use the file path as the key for project challenges, or code and testcases for classic challenges.
cursor ChallengeOptions~Cursor

Contains information about where the cursor is at the time of the event.

Cursor

Cursor tracking data.

Properties:
Name Type Description
path string

Path to file. For classic code challenges, this will be code or testcases
line number

Line number
ch number

Character number

RunResult

Result of a code run. This is only a subset of the properties available.

Properties:
Name Type Description
type "test" | "attempt"

Type of run
fileData ChallengeOptions~FileContentsData

The solution files at the time of the attempt
flags Object
Properties
Name Type Description
success boolean

True if the code was run without error
passed boolean

True if the solution passed all tests
executionFailure boolean

True if unable to run the code
timeout boolean

True if the tests did not run within the allotted time
wallTime number

running time for the code
result Object

Details of the run result