In-Player Quiz: описание модуля

Назначение

In-Player Quiz — это интерактивные вопросы во время просмотра лекции. Модуль помогает удерживать внимание пользователя и закреплять ключевые факты прямо в момент просмотра.

За корректно завершенные вопросы пользователь получает баллы рейтинга. Начисление происходит по каждому вопросу отдельно, сразу после терминального результата.

Где используется

In-Player Quiz привязан к конкретной лекции/видео.

In-Player Quiz не является экзаменом курса и не заменяет тренажер.

Для одной лекции может быть только один активный In-Player Quiz.

Клиент запрашивает In-Quiz по идентификатору лекции: lectureId.

Основные сущности

InPlayerQuiz

Контейнер вопросов для одной лекции.

Содержит:

id;

список вопросов.

InPlayerQuizQuestion

Вопрос, который нужно показать на конкретном моменте видео.

Содержит:

id

timestamp — позиция на видео, в микросекундах

duration — время показа, в микросекундах

text — текст вопроса

ratingScore — количество баллов рейтинга за правильный ответ

type — тип вопроса: basic или super

state — состояние вопроса для текущего пользователя

answers — список вариантов ответа

Порядок вопросов и ответов определяется порядком элементов в массиве.

InPlayerQuizAnswer

Вариант ответа.

В клиентском API содержит только:

id

text

Признак правильности ответа не возвращается до завершения вопроса.

InPlayerQuizQuestionState

Состояние вопроса для текущего пользователя.

Содержит:

status

selectedAnswerId

correctAnswerId

correctAnswerId возвращается только после терминального результата, чтобы клиент мог подсветить правильный ответ.

Статусы вопроса

pending — вопрос еще не завершен

right — пользователь выбрал правильный ответ

failed — пользователь выбрал неправильный ответ, время закончилось или вопрос смахнули

Все статусы, кроме pending, являются терминальными. Терминальный результат не должен изменяться повторными запросами.

Пропущенные вопросы

Отдельного статуса missed нет.

Если пользователь перемотал видео, ушел в PiP или по другой причине не увидел вопрос, вопрос остается в статусе pending. В конце просмотра клиент показывает финальную очередь из вопросов, которые все еще находятся в pending.

Финальная очередь запускается:

после последнего вопроса

или при достижении 90% просмотра лекции

Клиент должен запустить финальную очередь только один раз в рамках текущего сценария просмотра.

Пользовательский сценарий

Клиент запрашивает In-Quiz для лекции

Если In-Quiz не найден, backend возвращает 404

Если In-Quiz есть, клиент отслеживает timestamp вопросов во время просмотра

На нужной позиции видео клиент показывает вопрос

Пользователь выбирает ответ, пропускает вопрос по таймауту или закрывает его

Клиент отправляет терминальный результат вопроса

Backend сохраняет результат и, если ответ правильный, атомарно начисляет баллы рейтинга

Backend возвращает обновленное состояние вопроса

Клиент локально пересчитывает общий прогресс In-Quiz по состояниям вопросов

10.

В конце просмотра клиент показывает финальную очередь оставшихся pending вопросов

Начисление рейтинга

Баллы рейтинга начисляются только за right

failed завершают вопрос без начисления баллов

Начисление происходит сразу после завершения конкретного вопроса

Повторная отправка результата по уже завершенному вопросу не начисляет баллы повторно

Что считает клиент

Backend не возвращает агрегированное состояние In-Player Quiz.

Клиент сам выводит из списка вопросов:

завершен ли весь In-Quiz

количество отвеченных вопросов

количество правильных ответов

количество ошибок

количество оставшихся вопросов

сумму набранных баллов рейтинга

данные для финального экрана

Это уменьшает дублирование данных в контракте и убирает риск рассинхронизации агрегатов с состоянием вопросов.

Ответственность backend

Backend отвечает за:

выдачу активного In-Quiz для лекции

хранение терминальных результатов вопросов

защиту от повторного начисления рейтинга

атомарное сохранение правильного результата и рейтинговой транзакции

возврат correctAnswerId только после терминального результата

валидацию админских данных In-Quiz

Ответственность клиента

Клиент отвечает за:

локальный onboarding

локальную настройку отключения In-Quiz

показ вопросов по timestamp

обработку таймаута и закрытия вопроса

запуск финальной очереди pending вопросов

расчет агрегатов и финального экрана из списка вопросов

API поверхность

Клиентские endpoint'ы:

GET /in-player-quiz — получить In-Quiz для лекции и состояния вопросов текущего пользователя

POST /in-player-quiz/questions/{questionId}/result — завершить вопрос

Что намеренно не добавляем

Отдельный endpoint старта In-Player Quiz

Отдельный endpoint финальной очереди

Отдельный endpoint summary/final screen

Синхронизацию onboarding

Синхронизацию пользовательской настройки отключения In-Player Quiz

Требования

Для правильной работы API требуется провести миграцию ID лекций. Необходимо сделать так, чтобы ID лекций был глобально уникальным. Источник

In-Player Quiz: описание модуля

Назначение#

Где используется#

Основные сущности#

InPlayerQuiz#

InPlayerQuizQuestion#

InPlayerQuizAnswer#

InPlayerQuizQuestionState#

Статусы вопроса#

Пропущенные вопросы#

Пользовательский сценарий#

Начисление рейтинга#

Что считает клиент#

Ответственность backend#

Ответственность клиента#

API поверхность#

Что намеренно не добавляем#

Требования#

Назначение

Где используется

Основные сущности

InPlayerQuiz

InPlayerQuizQuestion

InPlayerQuizAnswer

InPlayerQuizQuestionState

Статусы вопроса

Пропущенные вопросы

Пользовательский сценарий

Начисление рейтинга

Что считает клиент

Ответственность backend

Ответственность клиента

API поверхность

Что намеренно не добавляем

Требования