# HTML-интерактивы: руководство автора, манифест v1, SDK Interactive Presentations исполняет ваш HTML-интерактив **как есть**: ваш DOM, CSS, JavaScript, анимации и собственные экраны результатов. Платформа отвечает за изоляцию, управление занятием, приём и хранение данных. Структуру ответа она не задаёт: в SQLite сохраняется ровно тот JSON, который передал интерактив. ## 1. Самый быстрый путь 1. Добавьте в интерактив **одну строку** там, где задание завершено: ```js InteractiveAPI.submit({ любые: 'данные', placed: ['B', 'C'], trace: [...] }); ``` Старый вызов `TrainingAPI.submit('s06', 'main', payload)` тоже работает без правок. 2. В кабинете нажмите «Загрузить» и выберите HTML-файл. Он станет презентацией из двух слайдов: интерактив и результаты. 3. Нажмите «Предпросмотр». Откроется тестовая сессия; она помечена и не смешивается с учебными. SDK подключать вручную не нужно: платформа вставляет его первым скриптом в ``. > **Почему без вызова SDK ответы не собираются.** Произвольный JavaScript платформа не разбирает и не угадывает, что считать «ответом». Интерактив без вызова `submit` работает и выглядит как в оригинале, но результаты участников не передаются. Отчёт совместимости при загрузке предупредит об этом. ## 2. Что можно загрузить | Что | Как распознаётся | |---|---| | Самостоятельный HTML с JS | Нет набора слайдов `
`, есть скрипт | | HTML-презентация из `
` | Статичные слайды рендерятся платформой. Слайды со своей механикой исполняются в песочнице исходным документом (показывается только нужная секция) | | Презентация со встроенными документами (`const TPL = {"i_s26": "…"}` + `srcdoc`) | Документы извлекаются как самостоятельные интерактивы (`i_`) и экраны результатов (`r_`); токены `__NAME__` заменяются константами `NAME` из скрипта | | ZIP: HTML + JS + CSS + картинки + шрифты | Один HTML в корне — интерактив; относительные пути работают | | ZIP: `presentation.html` + `interactive-manifest.json` + `interactives/…` | Манифест автора поверх найденного в презентации | | ZIP: только `interactive-manifest.json` + файлы | Слайды строятся по манифесту (или по `slides` в нём) | | ZIP с `deck.json` | Готовый пакет (как в 0.1) | | JSON `ipres/interactives` | Манифест к уже загруженной презентации (например, серверные правила проверки) | | JSON с `application/ipres+json` | Стандартные интерактивы — формы вопросов (режим B, совместимость) | Режимы импорта задаются переключателем в кабинете: - `auto` — по умолчанию. - `native` — все слайды со скриптами исполняются в песочнице. - `standard` — `ipres+json` важнее собственной разметки. - `static` — поведение версии 0.1: скрипты удаляются. Скрипты молча больше не удаляются ни в одном режиме, кроме `static`. ## 3. Манифест `interactive-manifest.json` (версия 1) ```json { "format": "ipres/interactives", "version": 1, "title": "Место контроля", "size": { "width": 1600, "height": 900 }, "interactives": [ { "id": "s06", "title": "Место контроля", "version": "1.0", "entry": "interactives/s06/index.html", "query": "", "views": { "results": "interactives/s06/results.html" }, "payload": { "schemaVersion": "1", "maxBytes": 65536 }, "attempts": { "policy": "firstOnly", "max": null }, "acceptance": { "autoOpen": true }, "demo": { "enabled": true }, "processing": { "validator": { "name": "path-control@1", "config": "private/s06-rules.json" }, "aggregator": { "name": "path-control@1", "options": {} }, "feedback": "never" }, "results": { "visibility": "published", "raw": "host", "rawLimit": 500 }, "sandbox": { "profile": "strict", "allow": {}, "modals": false, "popups": false }, "audience": { "layout": "responsive" }, "legacyIds": ["s06"] } ], "placements": [ { "after": "intro", "interactive": "s06", "view": "main" } ] } ``` | Поле | Обязательно | Значение | |---|---|---| | `id` | да | Латиница, цифры, `_` и `-`, до 64 символов. Стабильный идентификатор, к которому привязаны ответы | | `entry` | да | Путь к HTML внутри пакета (не в `private/`) | | `query` | нет | Строка запроса к документу. Для слайда из общей презентации: `ipres-slide=` | | `views` | нет | Экраны: `{"имя": "путь"}` или `{"имя": {"src": "…", "query": "…"}}`. Имя `main` зарезервировано за `entry`. Экранов может быть несколько или ни одного: без `results` платформа покажет нейтральную техническую сводку | | `attempts.policy` | нет | Что учитывать в статистике: `firstOnly` (по умолчанию: первая завершённая попытка), `latest`, `allAttempts`, `eventStream` (все события). Хранятся всегда все события | | `attempts.max` | нет | Предел завершённых попыток на участника | | `acceptance.autoOpen` | нет | Открывать приём при первом показе слайда (по умолчанию `true`) | | `processing.validator` | нет | Доверенный серверный валидатор; `config` — JSON в `private/` | | `processing.aggregator` | нет | Доверенный агрегатор. Без него экран получает нейтральные частоты (`frequency@1`) и сырые записи по правам | | `processing.feedback` | нет | Возвращать ли оценку участнику в квитанции: `never` (по умолчанию), `instant`, `onReveal` | | `results.visibility` | нет | Кому доступен агрегат: `published` (после публикации), `always`, `host` | | `results.raw` | нет | Обезличенные сырые записи: `host` (по умолчанию), `published` (и экрану после публикации), `none` | | `sandbox.profile` | нет | `strict` (по умолчанию), `media` (blob: для медиа и Web Worker), `network` (плюс явно перечисленные https-источники в `sandbox.allow.connect/img/font/media/script/style`) | | `sandbox.modals`, `popups` | нет | Разрешить `alert`/`confirm` и открытие окон. Это исключение: укажите причину в описании | | `audience.layout` | нет | `responsive` — iframe во весь экран телефона (вёрстку адаптирует сам интерактив); `fit` — как слайд, вписанный целиком. Участник может переключить кнопкой ⤢ | Манифест проверяется при загрузке. Ошибки показываются в кабинете с указанием места, а сессию с ошибками создать нельзя. **Привязка к слайдам** (`deck.json`): - `{"type":"app","interactive":"s06","view":"main"}` — интерактив на весь слайд; - `{"type":"app","interactive":"s06","view":"results"}` — его экран результатов; - несколько интерактивов на одном html-слайде: `
`, у слайда `"embeds":[{"interactive":"s26"}]`. Номера слайдов задания и результатов не обязаны идти подряд. **`private/`** не раздаётся никогда — ни участникам, ни песочнице. Если в манифесте `config` задан объектом, загрузчик сам вынесет его в `private/-validator.json`. ## 4. SDK `InteractiveAPI` (протокол 1) | Метод | Результат | |---|---| | `init(config?)` | `Promise`: `{sessionId, interactiveId, view, role, mode, participantId, contentVersion, status, capabilities, policy, lastSaved}` | | `submit(payload, {eventType='completed', idempotencyKey, part, schemaVersion, meta}?)` | `Promise<квитанция>` | | `emit(eventType, payload)` | Промежуточное событие; учитывается при политике `eventStream` | | `getSessionState()` / `getState()` | `{acceptance, published, revealed, slide, role, mode}` | | `getResults({cursor, limit})` | `{counts, aggregate, verified, reveal, raw, nextCursor, status, access, version}` — только разрешённое роли | | `reset()` | Новая попытка (новый `attemptId`); интерфейс сбрасывает сам интерактив | | `on(event, fn)` / `off` / `subscribe` / `unsubscribe` | Подписка на события | | `getCapabilities()` | Что разрешено в этой роли | **Квитанция** `submit`: `{ok, status, eventId, attempt, primary, receivedAt, contentVersion, error}`. Значения `status`: - `saved` — ответ сохранён; - `duplicate` — повторная доставка, ничего не изменилось; - `queued` — нет связи, ответ ждёт на устройстве и отправится сам; - `demo` — режим ведущего, ничего не сохраняется; - `view-only` — общий экран; - `closed` — приём закрыт; - `rejected` — ответ отклонён; - `standalone` — файл открыт вне платформы. **События**: - `ready`, `state`, `session:changed`; - `submissions:opened`, `submissions:closed`; - `results:published`, `results:unpublished`, `results:updated`; - `answers:revealed`; - `submission` (статус отправки), `connection`, `reset`. **Роли**: | Роль | Режим | Отправка | Чтение результатов | |---|---|---|---| | Ведущий | `demo` | `submit` возвращает `demo`, в базу не попадает | Всё | | Участник | `live` | Только свои ответы | По правам манифеста | | Экран | `view` | `view-only` | По правам манифеста | | Экран результатов (`view ≠ main`) | `results` | Нет | Разрешённые данные | Форма вызова из ТЗ `submit({interactiveId, questionId, answer})` тоже поддерживается: `answer` становится payload, `questionId` — частью ответа (`part`). ### Совместимость с прежним `TrainingAPI` | Вызов | Поддержка | |---|---| | `TrainingAPI.submit(slideId, questionId, payload)` | Полностью. Payload сохраняется как есть; `slideId` и `questionId` — в метаданных | | `TrainingAPI.isDemo()`, `participantId`, `sessionId`, `flush()`, `getResults()` | Да | | Собственная реализация `window.TrainingAPI = {…}` в файле | Адаптер остаётся главным; методы автора используются как запасные. Демо-заглушка сборщика с `demo:true` удаляется при импорте (это видно в отчёте) | | `const`/`let TrainingAPI` | **Не перехватывается.** Отчёт совместимости выдаёт ошибку `legacy-shadow` и рекомендует правку | | `fetch('…/api/results?sessionId=&slideId=')` (экраны результатов под Cloudflare) | Перехватывается. Ответ в формате прежнего Worker (`units.main`, `questions`, `sessionParticipants`) строит агрегатор `legacy-results@1` | | Прямые `fetch`/XHR/WebSocket к Cloudflare | Заблокированы. Используйте вызовы выше | ## 5. Доверенные обработчики (код платформы, а не загружаемый) | Имя | Назначение | |---|---| | `path-control@1` | Маршрут атаки через контрольные точки (`steps` с `points` и `weak`, `quality: full/residual`). Исходы: `stopped`, `stopped_residual`, `ineffective`, `failed`. Агрегат: точки, комбинации, этапы остановки, доля успешных | | `key-match@1` | Сравнение путей payload с эталоном: `equals`, `set`, `order`, `anyOf` (несколько верных решений), `pairs`, `contains`. Исходы: `Passed`, `Partial`, `Failed` | | `frequency@1` | Нейтральные частоты значений, элементов, комбинаций, последовательностей, числовые min/max/среднее, без «правильно/неправильно» | | `legacy-results@1` | Агрегат в формате прежнего Cloudflare Worker | Исход, посчитанный в браузере (например, `stoppedAt`), хранится как часть ответа автора, но **оценкой не считается**. `path-control@1` дополнительно фиксирует расхождение (`clientMismatch`). Чтобы добавить новый обработчик, разработчик платформы пишет модуль в `server/processing/` и регистрирует его в `index.js`. Из ZIP серверный код не загружается. ## 6. Песочница и что в ней меняется - **Изоляция.** Интерактив работает на **отдельном origin** в `