Verona Interfaces Specification "Player" 6.0.0 documentation

Verona Interfaces Specification "Player" 6.0.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 important, 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

SEND vopReadyNotification
Ready Notification
The player announces that it's code is loaded and initialized so the communication can start.

Operation IDvopReadyNotification
Accepts the following message:
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.
RECEIVE vopStartCommand
Start Command
The application sends parameters for running the unit and commands the start of user interaction.

Operation IDvopStartCommand
Accepts the following message:
object
sessionId
required
string
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
These data stand for the answers and some additional information on the status of responding. Emitted by the player during the test, it is given back to the player on start to restore the former state.

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
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.
SEND vopStateChangedNotification
State Changed Notification
The state of the unit and/or of the player has changed. Some logs entries might be sent.

Operation IDvopStateChangedNotification
Accepts the following message:
object
sessionId
required
string
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
These data stand for the answers and some additional information on the status of responding. Emitted by the player during the test, it is given back to the player on start to restore the former state.

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
The player sends some information on pages (valid pages, current page).

array<object>
This is an array with the id of the page und its label. The order of the items matter.

object
id
required
string
label
string
Additional properties are allowed.
currentPage
string
Id of the page currently presented. This id 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.

object
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.
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": [ { "id": "p1", "label": "start" }, { "id": "p3", "label": "on the beach" } ], "currentPage": "p3" }, "log": [ { "timeStamp": "2021-11-15T10:22:25Z", "key": "UNIT_NAVIGATION_FAILED", "content": "{\"unitId\": \"M24093EX\", \"reason\": \"responsesIncomplete\"}" } ] }

This example has been generated automatically.
RECEIVE vopPageNavigationCommand
Page Navigation Command
The host wants the player to navigate to a specific page.

Operation IDvopPageNavigationCommand
Accepts the following message:
object
sessionId
required
string
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.
SEND vopUnitNavigationRequestedNotification
Unit Navigation Requested Notification
The user has triggered a navigation request.

Operation IDvopUnitNavigationRequestedNotification
Accepts the following message:
object
sessionId
required
string
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
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.
RECEIVE vopNavigationDeniedNotification
Navigation Denied Notification
The host lets the player know that a navigation request was denied due to player state.

Operation IDvopNavigationDeniedNotification
Accepts the following message:
object
sessionId
required
string
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.
RECEIVE vopPlayerConfigChangedNotification
Player Config Changed Notification
The host wants the player to update its configuration given at start.

Operation IDvopPlayerConfigChangedNotification
Accepts the following message:
object
sessionId
required
string
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.

required
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
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", "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.
SEND vopRuntimeErrorNotification
Runtime Error Notification
The player had some trouble and the response process is at risk.

Operation IDvopRuntimeErrorNotification
Accepts the following message:
object
sessionId
required
string
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.

code
required
string
The list should be defined after getting some experience with that operation.

Examples values:
"AUDIO_CORRUPT"
"GEOGEBRA_CRASH"
message
string
Some additional information.

Additional properties are allowed.
Examples
{ "sessionId": "idk8ur5jf9ru5jk", "code": "AUDIO_CORRUPT", "message": "Was not able to play Element 'audio_4'" }

This example has been generated automatically.
SEND 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'.

Operation IDvopWindowFocusChangedNotification
Accepts the following message:
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
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
The player sends some information on pages (valid pages, current page).

array<object>
This is an array with the id of the page und its label. The order of the items matter.

object
id
required
string
label
string
Additional properties are allowed.
currentPage
string
Id of the page currently presented. This id 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
These data stand for the answers and some additional information on the status of responding. Emitted by the player during the test, it is given back to the player on start to restore the former state.

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
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
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
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
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" 6.0.0

Operations

SEND vopReadyNotification

Examples

This example has been generated automatically.

RECEIVE vopStartCommand

Examples

This example has been generated automatically.

SEND vopStateChangedNotification

Examples

This example has been generated automatically.

RECEIVE vopPageNavigationCommand

Examples

This example has been generated automatically.

SEND vopUnitNavigationRequestedNotification

Examples

This example has been generated automatically.

RECEIVE vopNavigationDeniedNotification

Examples

This example has been generated automatically.

RECEIVE vopPlayerConfigChangedNotification

Examples

This example has been generated automatically.

SEND vopRuntimeErrorNotification

Examples

This example has been generated automatically.

SEND vopWindowFocusChangedNotification

Examples

This example has been generated automatically.

Schemas