API. Запуск тестирования с прокторингом
Для начала тестирования нужно отправить POST-запрос из браузера на следующий URL:
https://[examus_url]/integration/simple/[integration_name]/start/
Тело запроса должно представлять собой form-data с одним параметром token, в котором передается JSON Web Token с информацией о сеансе тестирования. JWT должен быть подписан с использованием алгоритма HMAC-SHA256 (“HS256”), ключом для подписи является параметр jwt_secret. Больше информации о JSON Web Token можно найти на jwt.io, там же есть ссылки на библиотеки для работы с ним.
Пример JWT payload
{
"userId": "1232134",
"lastName": "Иванов",
"firstName": "Иван",
"thirdName": "Иванович",
"language": "ru",
"accountId": 123,
"accountName": "Название компании",
"examId": "unique-exam-id",
"courseName": "Физика",
"examName": "Финальный тест",
"userAgreementUrl": "https://school.org/eula",
"duration": 120,
"schedule": false,
"checkIdPhotoQuality": true,
"allowMultipleDisplays": true,
"allowVirtualEnvironment": true,
"auxiliaryCamera": false,
"auxiliaryCameraMode": "photo",
"proctoring": "offline",
"identification": "passport",
"rules": {
"allow_to_use_paper": true,
"allow_to_use_calculator": false
},
"desktopAppForbiddenProcesses": ["chrome.exe","Google Chrome"],
"desktopAppAllowedProcesses": ["chrome.exe","Google Chrome"],
"startDate": "2018-03-27T00:00:00Z",
"endDate": "2018-03-30T12:55:00Z",
"sessionId": "b3875623",
"sessionUrl": "https://go.bananas.com/opentest#test/b3875623",
"exp": 1612994131,
"ldb": true,
"biometricIdentification": {
"enabled": true,
"photo_url": "
",
"skip_fail": false,
"flow": "test-flow"
},
"scoreConfig": {
"cheater_level": 70,
"extra_user": 3.0,
"phone": 0.0
},
"visibleWarnings": {
"warning_extra_user_in_frame": false,
"warning_timeout": false
}
}
Пример JWT payload
|
Группа параметров |
Поле |
Тип |
Макс. длина |
Описание |
|
Параметры пользователя |
userId* |
string |
255 |
Идентификатор участника в системе заказчика. Он должен быть уникальным для каждого пользователя. |
|
|
string |
255 |
email участника в системе заказчика. |
|
|
lastName |
string |
255 |
Фамилия |
|
|
firstName |
string |
255 |
Имя |
|
|
thirdName |
string |
255 |
Отчество |
|
|
language |
string (enum) |
2 |
Язык пользователя. Двухбуквенный код из ISO 639-1. Обратитесь в поддержку Экзамуса, чтобы уточнить список поддерживаемых языков и активировать нужные. |
|
|
Параметры организации |
accountId* |
string |
255 |
Идентификатор организации в системе заказчика. Различные accountId нужны, если тест-систему используют несколько организаций, которые нужно различать между собой и разграничивать между ними доступ. |
|
accountName* |
string |
255 |
Название организации в системе заказчика
К этому параметру привязываются учётные записи прокторов, администраторов, видеозаписи тестируемых. Поэтому важно передавть одно и тоже значение accountName в рамках одной организации/контрагента, у которого проходят тесты с прокторингом. Смена значения приведёт к созданию новой компании, для которой потребуются новые учётные записи. |
|
|
Параметры экзамена |
courseName |
string |
450 |
Название учебного курса, в рамках которого сдается экзамен |
|
examId* |
string |
255 |
Идентификатор экзамена в системе, предпочтительно GUID |
|
|
examName* |
string |
500 |
Название экзамена |
|
|
userAgreementUrl |
string (URL) |
200 |
Ссылка на документ, содержащий правила проведения экзамена, с которыми пользователь будет ознакомлен перед началом экзамена |
|
|
duration* |
int |
- |
Продолжительность экзамена в минутах |
|
|
schedule* |
boolean |
- |
Необходимость записи в календаре, по умолчанию false |
|
|
auxiliaryCamera |
boolean |
- |
Включить дополнительную камеру со смартфона |
|
|
auxiliaryCameraMode |
string (enum) |
- |
Переключает режим второй камеры:
|
|
|
allowMobileDevices |
boolean |
- |
Включить прохождение с мобильных устройств |
|
|
proctoring* |
string (enum) |
- |
Тип прокторинга: “online” в случае с проктором, контролирующим сдачу экзамена (синхронный режим), “offline” в случае с пост-просмотром (асинхронный режим), “auto” в случае автоматического выставления заключения алгоритмами системы "identification" в случае подключения режима Идентификация |
|
|
identification |
string (enum) |
- |
Режим фотографирования. Доступные значения: “passport”, “face”, “face_and_passport”, “skip” |
|
|
rules |
JSON |
- |
||
|
trial |
boolean |
- |
true, если экзамен является пробным. Пробные экзамены не отображаются в архиве, их можно использовать для тестирования интеграции или для ознакомления студентов с системой прокторинга. По умолчанию false |
|
|
allowMultipleDisplays |
boolean |
- |
true, если в рамках экзамена разрешено использование дополнительного монитора. По умолчанию false |
|
|
allowVirtualEnvironment |
boolean |
- |
true, если разрешено запускать прокторинг в виртуальной машине. По умолчанию false |
|
|
checkIdPhotoQuality |
boolean |
- |
true, если требуется автоматическая проверка качества документа. По умолчанию false |
|
|
scoreConfig |
JSON |
- |
||
|
visibleWarnings |
JSON |
- |
||
|
desktopAppForbiddenProcesses |
JSON |
- |
Список строк, где каждая строка это название запрещенного процесса. |
|
|
desktopAppAllowedProcesses |
JSON |
- |
Список строк, где каждая строка это название разрешенного процесса. |
|
|
startDate* |
string (datetime) |
- |
Дата и время, начиная с которого можно запустить экзамен, в формате ISO 8601. Необходимо либо явно указывать часовой пояс, либо использовать специальный формат для UTC. В случае экзаменов без записи выставляется индивидуально для каждого сеанса прокторинга (т.е. является параметром сеанса, а не экзамена). |
|
|
endDate* |
string (datetime) |
- |
Дата и время, до которого можно запустить экзамен, в формате ISO 8601. В случае экзаменов без записи выставляется индивидуально для каждого сеанса прокторинга (т.е. является параметром сеанса, а не экзамена). |
|
|
Параметры сеанса |
sessionId* |
string |
230 |
Идентификатор сеанса в системе, предпочтительно GUID. Должен быть уникальным для каждой попытки в системе |
|
sessionUrl* |
string (URL) |
2550 |
Ссылка на прохождение экзамена в системе Важно! Это должна быть страница с тестом, которая уже открывается в прокторинге и где тестируемый видит вопросы теста. Если вдруг ссылка сама по себе запускает прокторинг, передаётся в JWT, то произойдёт открытие прокторинга в прокторинге. |
|
|
exp |
int |
- |
Дата и время истечения токена в числовом формате Unix timestamp. Для вычисления этого времени можно использовать формулу “текущее время + 30 секунд”. |
|
|
sessionFinishUrl |
string (URL) |
2550 |
Адрес страницы, на которую студент должен быть перенаправлен после завершения экзамена. Его также можно передать в параметрах завершения сеанса. |
|
|
reviewUrl |
string (URL) |
600 |
URL, на который будет отправлен результат прокторинга. Переопределяет review_url для этого сеанса прокторинга. |
|
|
Параметры среды |
ldb |
boolean |
- |
Необходимость открывать экзамен в защищенном (lockdown) браузере. Какой именно браузер использовать, нужно согласовать заранее. |
|
biometricIdentification |
JSON |
- |
||
|
faceHuntingEnabled |
boolean |
- |
true, если требуется подключение определения вовлеченности тестируемого |
|
Если передать в токене ID пользователя или экзамена, который уже был использован ранее, то в Экзамусе будет изменен уже существующий объект, а не создан новый. Таким образом можно поменять правила экзамена, его продолжительность и любые другие параметры.
Экзамус создает пользователя по переданной информации (либо использует существующего), авторизует его и создает сеанс прокторинга. После этого пользователь с помощью веб-приложения начинает сессию прокторинга, проходит идентификацию личности и проверку соединения, и в случае успеха Экзамус перенаправляет пользователя на страницу тестирования в системе заказчика по sessionUrl, указанному в токене.
Если во время сеанса прокторинга произошел разрыв связи или другие технические неполадки, из-за которых страница с экзаменом оказалась закрыта, тестируемый в течение небольшого промежутка времени (5-15 минут, в зависимости от того, как настроен таймаут на сервере Экзамуса) может зайти в тест заново по той же ссылке. Если связь отсутствовала слишком долго, сеанс прокторинга автоматически завершится, после чего потребуется заново сгенерировать ссылку для прохождения экзамена с новым sessionId.