# 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** в `