Verona Interfaces Specification "Player" 5.2.0 documentation

Verona Interfaces Specification "Player" 5.2.0

This is one part of the Verona Online Assessment Standards. All messages are sent via the postMessage function of the html page. The player takes the page root of its parent as target (parent.window), and the application binds the function call to the iframe element of the player. Most importantly, the message body carries as first parameter the operationId of the message. The html page MUST contain a <script>-tag with metadata. The syntax and structure of this data are described here.

Operations

SUB vopReadyNotification
Ready Notification
The player announces that it's code is loaded and initialized so the communication can start.
Accepts the following message:
vopReadyNotificationMessage
application/json
Message IDvopReadyNotificationMessage
object
metadata
required
string
Via this property, the player sends the stringified metadata object defined as json-ld in the header of the html file. See here for more information.

Additional properties are allowed.
Examples
{ "metadata": "string" }

This example has been generated automatically.
PUB vopStartCommand
Start Command
The application sends parameters for running the unit and commands the start of user interaction.
Accepts the following message:
vopStartCommandMessage
application/json
Message IDvopStartCommandMessage
object
sessionId
required
string
uid: SessionIdString
The session id flags all communication. If a message has no or empty session id, it's not processed. The session id is unique and was generated by the application. Any simple algorithm would work. The session id helps to link the correct unit with the data of the message. Using the id of the player hosting html element is less reliable, because the element could be reused with another unit.

unitDefinition
string
format: byte
The definition of the unit (if given) lets the player adapt. An audio player gets it's audio sequence, a choice player gets it's options...

unitDefinitionType
string
This lets the player the unit definition format know. This might avoid UI mess after getting old definitions.

object
If there is any state what should be restored, then this is the information for that.

object
This data is used by the player to restore the former response state and by data processing systems to analyse the responses. The host must buffer all data parts, because the player might send only changed data parts, not always the whole package. The host stores all parts but only the last given version (respect timeStamp!). Every data part is identified by a unique key, the data is stored as serialized object (string).

Additional properties:
string
format: byte
presentationProgress
string
This reports the progress of presentation of unit content. The host can enable or disable the navigation to the next unit depending on that value. For example, all audio elements are required to be played or all pages must be presented to the page bottom. This way, giving no response to an item is always intended.

Allowed values:
"none"
"some"
"complete"
responseProgress
string
This reports the progress of responding. The host can enable or disable the navigation to the next unit depending on that value. The value 'complete' announces not only that all required responses are given but that these responses are valid too. The value 'complete' can be sent even not all responses are given - the host is interested only in REQUIRED responses. So make sure to mark all response elements correctly corresponding to this behaviour.

Allowed values:
"none"
"some"
"complete"
unitStateDataType
string
This string specifies the format of the data stored in dataParts (value). Every transformation or analysis of stored unit data requires knowledge about the format. When the host sends data to the player to restore the former unit state, the player should check the given data type to avoid data mess after getting an old data type.

Additional properties are allowed.
object
This data supplies some information or instruction about this specific run of the unit (number, unit title, some behavioral data for the player).

unitNumber
integer
>= 1
The player might show the numbering of the current unit to ease the navigation.

unitTitle
string
<= 50 characters
The player might show the title of the current unit. Unless the unit definition could consist of a title, the host might decide to change the title. For example, this is necessary if one unit appears more then once in a booklet.

unitId
string
<= 20 characters
The player might include the internal unit id in state variables or logs.

logPolicy
string
The host expects the player to send no logs, only important logs, all possible logs or even logs for debugging purposes. This is a guideline. The player can decide what exactly the logging consists of.

Allowed values:
"disabled"
"lean"
"rich"
"debug"
pagingMode
string
If the player makes it optional, then the page presentation can be changed by the host. The pages are presented separately, with page navigation buttons, concatenated to one big page or concatenated in snap mode (scrolling vertically, but only one page is visible at a time).

Allowed values:
"separate"
"buttons"
"concat-scroll"
"concat-scroll-snap"
printMode
string
If this mode is 'on', the host presents the unit as preview for printing. Depending on the unit, the player modifies the presentation by (1) assignment of print styles, (2) ALL unit parts are displayed regardless of conditions, (3) all pages are displayed among each other, (4) the height of the given space is ignored (no vertical scrollbars by player). If the mode is set to 'on-with-ids', the player adds control labels to show the IDs.

Allowed values:
"off"
"on"
"on-with-ids"
array<string>
This lets the player know, what navigation target is enabled to natigate to. The player might then alter the presentation of responding buttons.

Items:
string
uid: NavigationTarget
This enumeration lists all possible targets the player could send a navigation request for, relative to the position of the current unit. This could be the next and previous unit, last and first unit of the current range of units (booklet, testlet) or the end of the test. The ending is seen as kind of termination of test, e. g. the announcement of the testee, that all responses are given. What exactly the host will navigate to depends of the nature of the test or the use case and might depend on configuration parameters of the specific booklet as well.

Allowed values:
"next"
"previous"
"first"
"last"
"end"
startPage
string
This requests the player to navigate to a certain page after loading. The host might know this page id from former usages of the unit.

directDownloadUrl
string
After starting the player and loading the unit definition and former responses, it might be necessary to load additional code or data from the server. This data is identified by an resource ID (usually a file name). The player can download this resource by itself without further interaction with the host frontend. The property directDownloadUrl provides the url for download. The player extends this url by an url separator "/" and the resource ID (uri-encoded if needed).

Additional properties are allowed.
Additional properties are allowed.
Examples
{ "sessionId": "idk8ur5jf9ru5jk", "unitDefinition": "iqb-scripted::1.4.0 title::Testscript Title2??Hilfetext2 multiple-choice::mc_var1::1::Multiple Choice Feld: ::Choice1##Choice2##Choice3??Hilfetext1 drop-down::dd_var1::1::Dropdown Feld: ::Choice1##Choice2##Choice3??Hilfetext1 checkbox::check_var1::0::Ja klick mal! if-start::dd_var1::1 input-text::jajaj::sap osjxapsoxa if-else input-text::jajaj22::sap osjxapsoxa UUUU text::NOT Choice1 if-end", "unitDefinitionType": "iqb-scripted@1.4.0", "unitState": { "dataParts": { "page1": "{\"a\": 1, \"b\": 233}", "page2": "{\"c\": \"sehr gut!\", \"d\": true}" }, "presentationProgress": "none", "responseProgress": "some", "unitStateDataType": "iqb-standard@2.1.2" }, "playerConfig": { "unitNumber": "14", "unitTitle": "Ein wunderbarer Ausflug", "unitId": "M24093EX", "logPolicy": "lean", "pagingMode": "concat-scroll", "printMode": "off", "enabledNavigationTargets": [ "next" ], "startPage": "page5", "directDownloadUrl": "https://www.iqb-testcenter.de/download/iskeid-34e845-didmmemdkek" } }

This example has been generated automatically.
SUB vopStateChangedNotification
State Changed Notification
The state of the unit and/or of the player has changed. Some logs entries might be sent.
Accepts the following message:
vopStateChangedNotificationMessage
application/json
Message IDvopStateChangedNotificationMessage
object
sessionId
required
string
uid: SessionIdString
The session id flags all communication. If a message has no or empty session id, it's not processed. The session id is unique and was generated by the application. Any simple algorithm would work. The session id helps to link the correct unit with the data of the message. Using the id of the player hosting html element is less reliable, because the element could be reused with another unit.

timeStamp
required
string
format: date-time
Ensures, that later arriving states are ignored.

object
To be stored, evaluated etc. This is the main yield, the responses.

object
This data is used by the player to restore the former response state and by data processing systems to analyse the responses. The host must buffer all data parts, because the player might send only changed data parts, not always the whole package. The host stores all parts but only the last given version (respect timeStamp!). Every data part is identified by a unique key, the data is stored as serialized object (string).

Additional properties:
string
format: byte
presentationProgress
string
This reports the progress of presentation of unit content. The host can enable or disable the navigation to the next unit depending on that value. For example, all audio elements are required to be played or all pages must be presented to the page bottom. This way, giving no response to an item is always intended.

Allowed values:
"none"
"some"
"complete"
responseProgress
string
This reports the progress of responding. The host can enable or disable the navigation to the next unit depending on that value. The value 'complete' announces not only that all required responses are given but that these responses are valid too. The value 'complete' can be sent even not all responses are given - the host is interested only in REQUIRED responses. So make sure to mark all response elements correctly corresponding to this behaviour.

Allowed values:
"none"
"some"
"complete"
unitStateDataType
string
This string specifies the format of the data stored in dataParts (value). Every transformation or analysis of stored unit data requires knowledge about the format. When the host sends data to the player to restore the former unit state, the player should check the given data type to avoid data mess after getting an old data type.

Additional properties are allowed.
object
Information important only for the application to ensure the correct visual, such as navigation buttons.

object
This data is structured as "page key" => "page label", so we have (1) keys for navigation commands or state notifications and (2) strings as labels of navigation buttons if needed.

Additional properties:
string
currentPage
string
Key of the page currently presented. This key is taken from the list of valid pages. If the paging mode is 'concat-scroll', the first page with parts in view port is taken as current page.

Additional properties are allowed.
array<object>
Log entries (lean version) add some information to the response in order to understand the response process better or (rich version) let the analyst replay every change of the state.

timeStamp
required
string
format: date-time
key
required
string
This key might help to classify the events afterwards.

content
string
format: byte
Some information to specify the event.

Additional properties are allowed.
Examples
{ "sessionId": "idk8ur5jf9ru5jk", "timeStamp": "2021-11-15T10:22:25Z", "unitState": { "dataParts": { "page1": "{\"a\": 1, \"b\": 233}", "page2": "{\"c\": \"sehr gut!\", \"d\": true}" }, "presentationProgress": "none", "responseProgress": "some", "unitStateDataType": "iqb-standard@2.1.2" }, "playerState": { "validPages": { "page1": "Seite 1", "page2": "Seite 2" }, "currentPage": "page4" }, "log": [ { "timeStamp": "2021-11-15T10:22:25Z", "key": "UNIT_NAVIGATION_FAILED", "content": "{\"unitId\": \"M24093EX\", \"reason\": \"responsesIncomplete\"}" } ] }

This example has been generated automatically.
PUB vopPageNavigationCommand
Page Navigation Command
The application wants the player to navigate to a specific page.
Accepts the following message:
vopPageNavigationCommandMessage
application/json
Message IDvopPageNavigationCommandMessage
object
sessionId
required
string
uid: SessionIdString
The session id flags all communication. If a message has no or empty session id, it's not processed. The session id is unique and was generated by the application. Any simple algorithm would work. The session id helps to link the correct unit with the data of the message. Using the id of the player hosting html element is less reliable, because the element could be reused with another unit.

target
required
string
Id of the page matching one of the validPages given to the application by the playerState data of the StateChangedNotification.

Additional properties are allowed.
Examples
{ "sessionId": "idk8ur5jf9ru5jk", "target": "page4" }

This example has been generated automatically.
SUB vopUnitNavigationRequestedNotification
Unit Navigation Requested Notification
The user has triggered a navigation request.
Accepts the following message:
vopUnitNavigationRequestedNotificationMessage
application/json
Message IDvopUnitNavigationRequestedNotificationMessage
object
sessionId
required
string
uid: SessionIdString
The session id flags all communication. If a message has no or empty session id, it's not processed. The session id is unique and was generated by the application. Any simple algorithm would work. The session id helps to link the correct unit with the data of the message. Using the id of the player hosting html element is less reliable, because the element could be reused with another unit.

target
required
string
uid: NavigationTarget
This enumeration lists all possible targets the player could send a navigation request for, relative to the position of the current unit. This could be the next and previous unit, last and first unit of the current range of units (booklet, testlet) or the end of the test. The ending is seen as kind of termination of test, e. g. the announcement of the testee, that all responses are given. What exactly the host will navigate to depends of the nature of the test or the use case and might depend on configuration parameters of the specific booklet as well.

Allowed values:
"next"
"previous"
"first"
"last"
"end"
Additional properties are allowed.
Examples
{ "sessionId": "idk8ur5jf9ru5jk", "target": "next" }

This example has been generated automatically.
PUB vopNavigationDeniedNotification
Navigation Denied Notification
The host lets the player know that a navigation request was denied due to player state.
Accepts the following message:
vopNavigationDeniedNotificationMessage
application/json
Message IDvopNavigationDeniedNotificationMessage
object
sessionId
required
string
uid: SessionIdString
The session id flags all communication. If a message has no or empty session id, it's not processed. The session id is unique and was generated by the application. Any simple algorithm would work. The session id helps to link the correct unit with the data of the message. Using the id of the player hosting html element is less reliable, because the element could be reused with another unit.

array<string>
This optional parameter explains the reason for the failed attempt to navigate. The player can visualise the problem to the testee. For example, all required but empty input elements get a red border or the message 'please scroll down' is presented.

Items:
string
Allowed values:
"presentationIncomplete"
"responsesIncomplete"
Additional properties are allowed.
Examples
{ "sessionId": "idk8ur5jf9ru5jk", "reason": [ "presentationIncomplete" ] }

This example has been generated automatically.
SUB vopWindowFocusChangedNotification
Window Focus Changed Notification
In some use cases like exam mode the host must know whether the host or the player has the window's focus. If none of these windows have the focus (i. e. the testee has left the test), some logging or warning could be necessary. The player should listen to the window events 'blur' and 'focus'.
Accepts the following message:
vopWindowFocusChangedNotificationMessage
application/json
Message IDvopWindowFocusChangedNotificationMessage
object
timeStamp
required
string
format: date-time
Ensures, that later arriving states are ignored.

hasFocus
required
boolean
true if the player got the focus, false if it lost the focus.

Additional properties are allowed.
Examples
{ "timeStamp": "2021-11-15T10:22:25Z", "hasFocus": true }

This example has been generated automatically.

Schemas

object
uid: LogEntry
The player can send any information about events happening during the interaction phase.

timeStamp
required
string
format: date-time
key
required
string
This key might help to classify the events afterwards.

content
string
format: byte
Some information to specify the event.

Additional properties are allowed.
object
uid: PlayerState
object
This data is structured as "page key" => "page label", so we have (1) keys for navigation commands or state notifications and (2) strings as labels of navigation buttons if needed.

Additional properties:
string
currentPage
string
Key of the page currently presented. This key is taken from the list of valid pages. If the paging mode is 'concat-scroll', the first page with parts in view port is taken as current page.

Additional properties are allowed.
object
uid: UnitState
object
This data is used by the player to restore the former response state and by data processing systems to analyse the responses. The host must buffer all data parts, because the player might send only changed data parts, not always the whole package. The host stores all parts but only the last given version (respect timeStamp!). Every data part is identified by a unique key, the data is stored as serialized object (string).

Additional properties:
string
format: byte
presentationProgress
string
This reports the progress of presentation of unit content. The host can enable or disable the navigation to the next unit depending on that value. For example, all audio elements are required to be played or all pages must be presented to the page bottom. This way, giving no response to an item is always intended.

Allowed values:
"none"
"some"
"complete"
responseProgress
string
This reports the progress of responding. The host can enable or disable the navigation to the next unit depending on that value. The value 'complete' announces not only that all required responses are given but that these responses are valid too. The value 'complete' can be sent even not all responses are given - the host is interested only in REQUIRED responses. So make sure to mark all response elements correctly corresponding to this behaviour.

Allowed values:
"none"
"some"
"complete"
unitStateDataType
string
This string specifies the format of the data stored in dataParts (value). Every transformation or analysis of stored unit data requires knowledge about the format. When the host sends data to the player to restore the former unit state, the player should check the given data type to avoid data mess after getting an old data type.

Additional properties are allowed.
NavigationTarget
string
uid: NavigationTarget
This enumeration lists all possible targets the player could send a navigation request for, relative to the position of the current unit. This could be the next and previous unit, last and first unit of the current range of units (booklet, testlet) or the end of the test. The ending is seen as kind of termination of test, e. g. the announcement of the testee, that all responses are given. What exactly the host will navigate to depends of the nature of the test or the use case and might depend on configuration parameters of the specific booklet as well.

Allowed values:
"next"
"previous"
"first"
"last"
"end"
SessionIdString
string
uid: SessionIdString
The session id flags all communication. If a message has no or empty session id, it's not processed. The session id is unique and was generated by the application. Any simple algorithm would work. The session id helps to link the correct unit with the data of the message. Using the id of the player hosting html element is less reliable, because the element could be reused with another unit.
object
uid: PlayerConfig
unitNumber
integer
>= 1
The player might show the numbering of the current unit to ease the navigation.

unitTitle
string
<= 50 characters
The player might show the title of the current unit. Unless the unit definition could consist of a title, the host might decide to change the title. For example, this is necessary if one unit appears more then once in a booklet.

unitId
string
<= 20 characters
The player might include the internal unit id in state variables or logs.

logPolicy
string
The host expects the player to send no logs, only important logs, all possible logs or even logs for debugging purposes. This is a guideline. The player can decide what exactly the logging consists of.

Allowed values:
"disabled"
"lean"
"rich"
"debug"
pagingMode
string
If the player makes it optional, then the page presentation can be changed by the host. The pages are presented separately, with page navigation buttons, concatenated to one big page or concatenated in snap mode (scrolling vertically, but only one page is visible at a time).

Allowed values:
"separate"
"buttons"
"concat-scroll"
"concat-scroll-snap"
printMode
string
If this mode is 'on', the host presents the unit as preview for printing. Depending on the unit, the player modifies the presentation by (1) assignment of print styles, (2) ALL unit parts are displayed regardless of conditions, (3) all pages are displayed among each other, (4) the height of the given space is ignored (no vertical scrollbars by player). If the mode is set to 'on-with-ids', the player adds control labels to show the IDs.

Allowed values:
"off"
"on"
"on-with-ids"
array<string>
This lets the player know, what navigation target is enabled to natigate to. The player might then alter the presentation of responding buttons.

Items:
string
uid: NavigationTarget
This enumeration lists all possible targets the player could send a navigation request for, relative to the position of the current unit. This could be the next and previous unit, last and first unit of the current range of units (booklet, testlet) or the end of the test. The ending is seen as kind of termination of test, e. g. the announcement of the testee, that all responses are given. What exactly the host will navigate to depends of the nature of the test or the use case and might depend on configuration parameters of the specific booklet as well.

Allowed values:
"next"
"previous"
"first"
"last"
"end"
startPage
string
This requests the player to navigate to a certain page after loading. The host might know this page id from former usages of the unit.

directDownloadUrl
string
After starting the player and loading the unit definition and former responses, it might be necessary to load additional code or data from the server. This data is identified by an resource ID (usually a file name). The player can download this resource by itself without further interaction with the host frontend. The property directDownloadUrl provides the url for download. The player extends this url by an url separator "/" and the resource ID (uri-encoded if needed).

Additional properties are allowed.

Verona Interfaces Specification "Player" 5.2.0

Operations

SUB vopReadyNotification

Examples

This example has been generated automatically.

PUB vopStartCommand

Examples

This example has been generated automatically.

SUB vopStateChangedNotification

Examples

This example has been generated automatically.

PUB vopPageNavigationCommand

Examples

This example has been generated automatically.

SUB vopUnitNavigationRequestedNotification

Examples

This example has been generated automatically.

PUB vopNavigationDeniedNotification

Examples

This example has been generated automatically.

SUB vopWindowFocusChangedNotification

Examples

This example has been generated automatically.

Schemas