arrow_back Embeddables
Screen Player Build and above
The Screen Player surfaces one standalone screen, or a quiz section, inside your product. Learners stay on that screen (or walk the quiz internally); next and back at the edges are host intents so you can route them yourself.
Use it for a single knowledge check, a microlearning card, or an embedded quiz that should not look like a full course. Theme comes from themeId. Quiz attempts persist against the token identity so a failed quiz stays failed on re-embed. Non-quiz screens are stateless.
Hosts who created the screen via either Screen Builder path listen here for start / complete / failed / exhausted (and score) on the same host postMessage channel.
API Endpoint
POST
/v1/headless/embed/screenBody parameters
| Field | Type | Example | Description | Demo Value |
|---|---|---|---|---|
action | string | view | — | — |
screenId | number | 123 | — | — |
identifier | string | your-user-id | — | — |
clientIdentifier | string | your-tenant-id | — | — |
name | string | Jane Doe | — | — |
avatar | string | https://example.com/avatar.jpg | — | — |
options.hideNavigation | boolean | false | Hide the player footer pill. Item and question holds still compute, and locked/unlocked events still fire so host chrome can match. | |
options.lockSteps | boolean | true | Restrict navigation to reached screens. Set false to open any screen through Next, Back, the outline or a host navigation/goto message with data: { id }. | |
options.showContinue | boolean | true | Show the quiz results Continue button. Set false when the host drives navigation after a pass. | |
options.language | string | — | Player language. Defaults to the workspace default course language, or English when none is set. | |
options.themeId | number | — | Custom theme ID to apply to the embeddable. | |
options.expiresIn | string | 3h | Link opening lifetime, "30s" to "3h" (e.g. "5m"). Invalid values return 400. |
Emitted Events
How to listen to events| Type | Event | Description | Notes |
|---|---|---|---|
session | ready | Fires when the screen player is mounted and ready. | |
screen | start | Fires when a screen comes into view. | Shape is { type: 'screen', event, data }. Requires api_authoring; a play-only api client receives no events. |
screen | end | Fires when a screen is navigated away from. | |
screen | complete | Fires when a screen is completed. | Trigger varies by screen type. A scored quiz pass includes data.score.percentage and data.score.passed. |
screen | answer | Fires when a quiz question is answered. | Quiz screens only. For choice questions, answer lists the selected option text and answerChoiceIds lists the stable option IDs in the same order. |
screen | failed | Fires when a scored quiz is failed. | Quiz screens only. Includes data.score.percentage, data.score.passed, data.score.attemptsUsed, data.score.attemptsAllowed, and data.score.retriesAvailable (derived remaining). |
screen | exhausted | Fires when a scored quiz is failed and no retries remain. | Quiz screens only. Same score object as failed. Does not fire when attemptsAllowed is -1. Fires in addition to failed. |
navigation | next | Fires when the learner presses next on the last screen. The player does not leave; the host routes. | |
navigation | back | Fires when the learner presses back on the first screen. The player does not leave; the host routes. | |
navigation | locked | Fires when footer next is locked (required items, questions, or holds). | |
navigation | unlocked | Fires when footer next becomes available. |
Playback event
{
"type": "screen",
"event": "complete",
"data": {
"id": 123,
"score": { "percentage": 80, "passed": true }
}
}