Задание для ИИ-агента: подключить Live 3D Tracker

Назначение документа

Этот файл содержит задание для ИИ-агента, который должен подключить Live 3D Tracker к существующему сайту или веб-приложению клиента.

Выполни интеграцию в соответствии с архитектурой и стилем проекта. Не изменяй существующие функции, дизайн и структуру проекта без необходимости.

Что нужно получить перед началом

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

1. Страницу или компонент, где должен отображаться трекер.
2. Ключ доступа вида pk_live_..., выданный менеджером SportAPI.
3. Рабочий или тестовый домен, активированный для этого ключа.
4. Источник данных спортивной линии SportAPI.
5. Поле zp в данных выбранного матча.
6. ID вида спорта из таблицы ниже.
7. Нужный язык интерфейса.
8. Требования к высоте и мобильному отображению.

Если ключ или другие обязательные данные отсутствуют, не придумывай их. Подготовь интеграцию с понятными переменными-заполнителями и сообщи пользователю, какие данные ещё нужно получить.

Для получения ключа и активации домена пользователь должен обратиться к менеджеру SportAPI в Telegram. Для локальной разработки менеджеру нужно отдельно сообщить, что ключ должен работать на localhost.

Основные правила

• Трекер работает только для матчей в статусе live.
• Трекер не предоставляет спортивную линию и список матчей.
• Для получения данных матчей и поля zp нужна подписка на спортивную линию SportAPI.
• Значение параметра gameid всегда берётся из поля zp: gameid = zp.
• Если zp отсутствует или равно null, трекер для матча недоступен. Не создавай пустой виджет.
• Передавай правильный ID вида спорта в параметре sport.
• Доступные виды спорта и языки могут быть ограничены тарифом ключа.
• Ключ можно использовать в клиентском коде: он защищён привязкой к разрешённым доменам.
• Не добавляй нестандартные параметры оформления и не изменяй дизайн трекера. Индивидуальные визуальные доработки выполняет SportAPI по отдельному заказу.

Демонстрация

Внешний вид трекера можно посмотреть на демонстрационной странице.

Демонстрация не использует реальные live-данные и не заменяет проверку интеграции на live-матче, у которого zp не равно null.

Коды видов спорта

Не предполагай, что внутренний ID спорта в проекте клиента совпадает с ID в этой таблице. Если проект использует свои идентификаторы, создай явное соответствие.

Выбор способа подключения

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

Используй embed.js, если пользователь переключает матчи на одной странице или проекту нужно управлять стандартными параметрами через JavaScript.

Способ 1. Прямой iframe

Базовый пример:

<iframe
  id="live-tracker"
  src="https://bet-embed-sport-tracker.vercel.app/?key=pk_live_yourkey&gameid=745829876&sport=1&lang=ru"
  style="width: 100%; height: 360px; border: none; display: block;"
  allowfullscreen
  title="Live tracker"
></iframe>

Стандартные параметры адреса:

• key — ключ клиента;
• gameid — значение поля zp;
• sport — ID вида спорта;
• lang — язык интерфейса;
• mobile=1 — мобильное отображение;
• view=2d или view=3d — доступный режим отображения.

Самый простой способ сменить матч — изменить gameid и sport в src элемента iframe.

Матч также можно сменить без перезагрузки iframe через postMessage. Отправляй сообщение только после загрузки iframe или по действию пользователя:

const trackerFrame = document.querySelector('#live-tracker');
let trackerLoaded = false;

trackerFrame.addEventListener('load', () => {
  trackerLoaded = true;
});

function switchMatch(gameid, sport) {
  if (!trackerLoaded) return;

  trackerFrame.contentWindow.postMessage(
    {
      type: 'CONFIG',
      payload: { gameid, sport }
    },
    'https://bet-embed-sport-tracker.vercel.app'
  );
}

Не используй '*' в качестве targetOrigin.

Способ 2. Подключение через embed.js

Загрузчик:

https://bet-embed-sport-tracker.vercel.app/embed.js

Базовый пример:

<div id="zone"></div>

<script src="https://bet-embed-sport-tracker.vercel.app/embed.js"></script>
<script>
  let trackerReady = false;

  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://bet-embed-sport-tracker.vercel.app') return;

    if (event.data?.type === 'READY') {
      trackerReady = true;
    }
  });

  const zone = BetZoneEmbed.init({
    container: '#zone',
    key: 'pk_live_yourkey',
    gameid: 745829876,
    sport: 1,
    lang: 'ru',
    height: 360
  });

  function switchMatch(gameid, sport) {
    if (!trackerReady) return;
    zone.update({ gameid, sport });
  }

  function switchLanguage(lang) {
    if (!trackerReady) return;
    zone.update({ lang });
  }
</script>

Не вызывай zone.update() сразу после init(). В этот момент iframe ещё может загружаться, поэтому сообщение будет потеряно. Вызывай update() после получения READY или позже по действию пользователя.

Стандартные параметры init():

Метод update() позволяет изменить gameid, sport, lang, mobile и view без пересоздания виджета.

Когда компонент или блок трекера удаляется со страницы, вызови:

zone.destroy();

React, Vue, Svelte и другие SPA

При интеграции в SPA:

1. Загружай внешний скрипт после монтирования компонента или штатным механизмом фреймворка.
2. Не добавляй один и тот же <script> при каждом рендере.
3. Не обращайся к window и DOM во время серверного рендеринга.
4. Вызывай init() только после появления контейнера в DOM и загрузки embed.js.
5. Сохраняй объект, возвращённый init().
6. При изменении матча вызывай update() только после готовности виджета.
7. При размонтировании вызывай destroy() и удаляй созданные обработчики событий.

Используй принятые в проекте способы загрузки скриптов, хранения настроек, обработки состояний и адаптивной вёрстки.

Состояния и ошибки

Предусмотри следующие ситуации:

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

Адаптивность

• Ширина трекера должна занимать 100% контейнера.
• Рекомендуемая высота — 360–420 px на компьютере.
• Рекомендуемая высота — 220–280 px на мобильном устройстве.
• Для мобильного режима используй mobile: true или mobile=1.
• Не фиксируй ширину в пикселях.

Используй breakpoints и дизайн-систему существующего проекта.

Проверка результата

После реализации проверь:

1. Виджет загружается на разрешённом домене с действующим ключом.
2. При zp: null виджет не создаётся.
3. Не-live матч не показывает трекер.
4. В gameid передаётся значение поля zp.
5. Код спорта соответствует таблице или явному отображению ID проекта.
6. update() не вызывается до READY.
7. Матч и язык меняются без полной перезагрузки страницы.
8. Прямой iframe принимает CONFIG только после загрузки.
9. На мобильном и компьютере используются подходящие размеры.
10. При повторном монтировании не появляются дубликаты скриптов, iframe или обработчиков.
11. При удалении компонента вызывается destroy().
12. Доступные тесты, линтер, проверка типов и сборка проекта проходят успешно.

Если нельзя проверить интеграцию из-за отсутствия ключа, разрешённого домена или live-матча с zp, выполни все доступные проверки и перечисли, что пользователь должен проверить после получения доступа.

Формат отчёта пользователю

После завершения сообщи:

• какие файлы были изменены;
• какой способ подключения выбран и почему;
• откуда берутся gameid и sport;
• какие состояния ошибок реализованы;
• какие проверки выполнены;
• какие данные или внешние проверки ещё нужны.

Поддержка SportAPI: @suport_sportapi.