Live 3D Tracker — описание сервиса

Содержание

Что это такое
Демонстрация
Кому подходит сервис
Как подключить трекер
- Прямой iframe
- Подключение через embed.js
Откуда берётся gameid
Поддерживаемые виды спорта
Возможности стандартного подключения
Доступ и домены
Что нужно передать для подключения
Что важно учитывать
Что делать, если трекер не работает
Дополнительные услуги по разработке

Что это такое

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

Трекер получает данные матча и отображает их в виде визуальной сцены. Он не является самостоятельным источником спортивных данных и используется вместе со спортивной линией SportAPI.

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

Посмотреть внешний вид трекера для разных видов спорта можно на демонстрационной странице.

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

Кому подходит сервис

Сервис подходит:

букмекерским сайтам и приложениям;
спортивным порталам;
сервисам live-score и статистики;
медиа и другим проектам, которые показывают спортивные события в реальном времени.

Как выглядит подключение

Чтобы подключить трекер, Вам необходимо:

Написать менеджеру SportAPI в Telegram и сообщить, что Вы хотите подключить Live 3D Tracker.
Отправить менеджеру домен, на котором будет работать трекер. Можно указать рабочий домен, тестовый домен и localhost, если разработчик будет выполнять интеграцию на своём компьютере.
Получить у менеджера ключ доступа. Менеджер активирует его для указанных Вами доменов. На другом домене этот ключ работать не будет.
Подключить спортивную линию SportAPI, если она ещё не подключена. Трекер сам не предоставляет список матчей — он только визуально отображает данные выбранного live-матча.
Найти нужный live-матч методом events или event и взять значение поля zp. Это значение нужно передать в трекер как gameid.
Передать ID вида спорта в параметре sport. Таблица поддерживаемых видов спорта и их ID приведена ниже.
Выбрать удобный способ встраивания: прямой iframe или подключение через embed.js.

Если поле zp у выбранного матча равно null, значит трекер для этого матча недоступен. Трекер работает только для live-матчей.

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

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

Это самый простой вариант. Разработчик добавляет на страницу один 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 — язык интерфейса.

Самый простой способ сменить матч — изменить gameid в адресе iframe. Также матч можно сменить без перезагрузки iframe, отправив ему новое значение через postMessage:

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

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

Вызывайте switchMatch() после загрузки iframe, например при выборе пользователем другого матча.

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

Этот вариант подходит, если на странице нужно управлять виджетом через JavaScript, например менять матч без полной перезагрузки страницы:

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

<script src="https://bet-embed-sport-tracker.vercel.app/embed.js"></script>
<script>
  BetZoneEmbed.init({
    container: '#zone',
    key: 'pk_live_yourkey',
    gameid: 745829876,
    sport: 1,
    lang: 'ru',
    height: 360
  });
</script>

Метод BetZoneEmbed.init() создаёт трекер внутри указанного контейнера и возвращает объект управления. Не вызывайте zone.update() сразу после init(): в этот момент виджет внутри iframe может быть ещё не готов и не получит новые параметры.

Вызывайте update() после сообщения READY или позже, когда пользователь выберет другой матч:

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 });
}

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

Если трекер нужно полностью убрать со страницы, используйте:

zone.destroy();

В обоих случаях трекер работает внутри iframe. При подключении через embed.js этот iframe создаётся автоматически. Страницу трекера нельзя использовать как отдельную страницу — она предназначена только для встраивания.

Ключ можно разместить в коде страницы: он привязан к разрешённым доменам и не будет работать на другом сайте.

Откуда берётся `gameid`

Трекер только визуализирует матч. Чтобы получить идентификатор трекера, клиенту нужна подписка на спортивную линию SportAPI.

В данных матча спортивной линии нужно найти поле zp:

{
  "zp": 745829876
}

Значение zp необходимо передать в параметр gameid:

gameid = zp

Например, если спортивная линия возвращает "zp": 745829876, то при инициализации трекера нужно передать gameid: 745829876.

Если спортивная линия возвращает:

{
  "zp": null
}

это означает, что для данного матча live-трекер отсутствует. В таком случае виджет показывать не нужно.

Live 3D Tracker работает только для матчей в статусе live и только для видов спорта, перечисленных ниже.

Какие виды спорта поддерживаются

В параметре sport передаётся идентификатор вида спорта:

ID	Вид спорта
1	Футбол
2	Хоккей
3	Баскетбол
4	Теннис
5	Бейсбол
6	Волейбол
7	Регби
8	Гандбол
10	Настольный теннис
13	Американский футбол
17	Водное поло
21	Дартс
26	Формула-1
28	Австралийский футбол
44	Скачки
66	Крикет
86	CS:GO / киберспорт

Доступные виды спорта и языки могут зависеть от тарифа клиента. Если передать вид спорта, который не входит в подключённый тариф, вместо трекера появится сообщение «этот вид спорта не входит в тариф». В этом случае нужно обратиться к менеджеру SportAPI, а не искать ошибку в коде интеграции.

Возможности стандартного подключения

При стандартном подключении доступны:

выбор языка интерфейса;
настройка высоты и мобильной раскладки;
добавление названия бренда и логотипа;
выбор доступного режима 2D или 3D;
смена отображаемого матча без перезагрузки страницы.

Эти возможности не требуют индивидуальной разработки. По умолчанию используется трекер стандартного вида. Для добавления логотипа клиент передаёт файл логотипа менеджеру SportAPI.

Если клиенту нужны другие изменения внешнего вида или поведения трекера, разработчики SportAPI могут выполнить их по индивидуальному заданию. Стоимость оценивается отдельно для каждого проекта. Возможные доработки описаны в документе «Дополнительные услуги по разработке».

Доступ и домены

Трекер работает только с активным ключом.
Ключ привязывается к домену клиента.
Для интеграции можно добавить тестовый домен и localhost.
Если домен изменился, новый домен необходимо отправить в поддержку SportAPI.
Триальный ключ автоматически перестаёт работать после окончания срока.

Если ключ отсутствует, отключён или используется на неразрешённом домене, виджет вернёт ошибку доступа 403.

Что нужно передать для подключения

Клиент должен отправить менеджеру или в поддержку SportAPI:

рабочий домен, на котором будет использоваться трекер;
тестовый домен и необходимость работы на localhost, если они нужны;
логотип клиента, если его нужно добавить;
выбранные параметры стандартного подключения;
информацию о необходимости индивидуальных доработок.

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

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

Что важно учитывать

Трекер предназначен для размещения внутри страницы и работает через iframe.
Трекер отображает только live-матчи.
Наличие трекера для матча определяется по полю zp спортивной линии.
Для каждого матча необходимо передавать правильные gameid и sport.
Ширина виджета адаптируется к контейнеру автоматически.
Рекомендуемая высота — 360–420 px на компьютере и 220–280 px на мобильном устройстве.
Названия команд поступают из источника спортивных данных. Язык виджета меняет интерфейс и названия событий, но не обязательно изменяет названия команд.

Если трекер не работает

Для диагностики нужно отправить в поддержку:

ссылку на страницу с установленным виджетом;
используемое значение gameid из поля zp;
код вида спорта;
скриншот виджета и консоли браузера.

Основные причины: домен не добавлен к ключу, ключ отключён, матч не находится в статусе live, поле zp равно null или передан неправильный код вида спорта.

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

Дополнительные услуги по разработке Live 3D Tracker

Общая информация

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

Стоимость и срок оцениваются отдельно после получения требований клиента.

Доработки, которые можно выполнить быстро

К таким изменениям относятся возможности, для которых уже есть техническая основа:

изменение цветов и цветовой палитры;
добавление логотипа или водяного знака клиента;
изменение иконок;
изменение подписей и отдельных элементов интерфейса;
настройка панелей, рамок и акцентных элементов;
изменение мобильной раскладки;
настройка положения команд;
включение ленты событий;
настройка доступного режима 2D или 3D;
изменение стандартных анимаций и времени их показа.

Точный срок зависит от количества изменений и предоставленных материалов.

Индивидуальная разработка под заказ

По отдельному заданию можно оценить:

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

Возможность реализации подтверждается разработчиками после изучения задачи.

Что нужно передать для оценки

описание желаемого результата;
макет, пример или ссылку на похожую реализацию;
логотип, иконки, шрифты и фирменные цвета;
список элементов, которые нужно изменить;
требования для компьютеров и мобильных устройств;
желаемый срок запуска.

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

Для обсуждения доработок напишите менеджеру SportAPI в Telegram.