Перейти к основному содержимому

Snapshot vs Delta

После подписки сервер шлёт обновления матча двумя видами сообщений: match_snapshot (полное состояние) и match_delta (только изменения относительно предыдущего snapshot).

match_snapshot​

Полное состояние матча — поле data — тот же объект Match, что в ответе REST GET /v2/{sportSlug}/matches/{matchId}, но без блоков pregame, bestPlayers, analytics и scoreStatus и с исходными переводами названий (в REST они могут быть полнее). Если подписка оформлена с withBkOdds: true, snapshot дополнительно включает блок oddsBk с коэффициентами всех подключённых букмекеров — как REST с with_bk_odds=true (у матча без коэффициентов — пустой объект {}; при кратковременной деградации источника кэфов поле может отсутствовать — трактуйте как «нет данных»). Без флага oddsBk в снапшоте не приходит.

{
"type": "match_snapshot",
"matchId": 12345678,
"sportSlug": "football",
"data": {
"id": 12345678,
"status": "inprogress",
"currentMatchMinute": 67,
"homeScore": { "current": 2, "period1": 1, "period2": 1 },
"awayScore": { "current": 1, "period1": 1, "period2": 0 }
/* …полная структура Match */
},
"timestamp": 1714123200000
}

match_snapshot (полный кадр) отправляется в следующих случаях:

  • Сразу после subscribe на конкретный матч (action: "subscribe", type: "match") — сервер тут же шлёт snapshot с актуальным состоянием.
  • Когда сервер не может вычислить delta — если предыдущее состояние матча недоступно, вместо delta уходит полный матч.
  • После reconnect — переподписавшись на матч (см. первый пункт), клиент снова получает свежий snapshot и может выбросить старое локальное состояние.

match_delta​

Инкрементальные изменения относительно последнего snapshot для этого матча. Поле changes содержит три параллельных представления одного и того же дифа.

{
"type": "match_delta",
"matchId": 15370088,
"sportSlug": "tennis",
"changes": {
"added": {
"matchStatistics": {
"0": {
"groups": {
"1": {
"groupName": "Points",
"statisticsItems": [ /* ... */ ]
}
}
}
}
},
"updated": {
"homeScore": { "period1": 0 },
"awayScore": { "period1": 0 }
},
"flatChanges": {
"matchStatistics.0.groups.1.groupName": "Points",
"homeScore.period1": 0,
"awayScore.period1": 0
}
},
"timestamp": 1768461968409
}
ПолеТипОписание
addedobject?Новые элементы / поля, появившиеся в матче. Иерархическая структура — пригодна для глубокого merge.
updatedobject?Изменившиеся существующие поля. Иерархическая структура.
flatChangesobject?Плоский формат с dot-notation путями (например homeScore.period1). Удобно для логирования и reactivity-store'ов.

Любое из трёх полей может отсутствовать, если соответствующих изменений нет.

Удаления полей в delta не приходят

Сервер отправляет только добавленные (added) и изменённые (updated) поля. Если поле исчезло из матча, в delta это не отражается — клиент сохранит прежнее значение до следующего match_snapshot. На практике поля матча по ходу события почти не удаляются.

Поправки счёта после завершения матча

Подписка не завершается вместе с матчем: пока вы подписаны, любые изменения приходят дельтами. В низших и любительских лигах итоговый счёт может быть скорректирован через часы или дни после финального свистка — такая правка придёт обычным match_delta с изменёнными homeScore / awayScore (и winner / winnerCode). Признак окончательности счёта в REST — scoreStatus.final; в WebSocket-сообщения он не входит.

Применение delta​

Стандартный подход — deep-merge added и updated поверх предыдущего snapshot. Поле flatChanges обычно избыточно при наличии deep-merge и нужно только если ваш стор работает по «плоским» путям.

const state = new Map(); // matchId → полная структура Match

function applyMessage(msg) {
if (msg.type === 'match_snapshot') {
state.set(msg.matchId, msg.data);
return;
}
if (msg.type === 'match_delta') {
const prev = state.get(msg.matchId);
if (!prev) return; // delta пришла раньше snapshot — игнорируем
let next = prev;
if (msg.changes.added) next = deepMerge(next, msg.changes.added);
if (msg.changes.updated) next = deepMerge(next, msg.changes.updated);
state.set(msg.matchId, next);
}
}

deepMerge — любая стандартная реализация (например, lodash.merge, npm-пакет deepmerge). Единственное исключение из deep-merge — блоки oddsBk.<bookmaker>, они заменяются целиком (см. следующий раздел).

Дельты коэффициентов букмекеров (oddsBk)​

Дельты кэфов приходят только по подпискам с withBkOdds: true. Подписка без флага работает как раньше: ни oddsBk в снапшоте, ни дельт коэффициентов.

Формат блока определяется опцией подписки: с oddsStage: "all" — объединённая прематч+лайв доска (поле stage у рынков, updatedAtByStage/isBettingActiveByStage на доске), без неё — прежний формат одной текущей стадии. См. Bookmaker Odds.

Коэффициенты букмекеров обновляются отдельным потоком: сервер отслеживает изменения кэфов каждого подключённого букмекера и шлёт opt-in подписчикам матча match_delta, где changes.updated.oddsBk.<bookmaker> — блок этого букмекера целиком (та же структура BookmakerOddsData, что и в REST/match_snapshot):

{
"type": "match_delta",
"matchId": 12345678,
"sportSlug": "football",
"changes": {
"added": {},
"updated": {
"oddsBk": {
"melbet": {
"slug": "melbet",
"name": { "en": "Melbet", "ru": "Мелбет" },
"updatedAt": 1714123200000,
"isBettingActive": true,
"markets": { /* полный набор рынков букмекера */ }
}
}
},
"flatChanges": {
"oddsBk.melbet": { /* тот же блок целиком; ключ = слаг букмекера: melbet | pari | marathon | betboom | pinnacle */ }
}
},
"timestamp": 1714123200000
}

Особенности:

  • Дельта приходит только при реальном изменении значений — сервер сравнивает сами кэфы/рынки, а не таймстемпы обновления фида. Нет изменений — нет сообщений.
  • Блок заменяется целиком, НЕ deep-merge. Рынок или исход может исчезнуть из блока (линия закрыта букмекером) — deep-merge оставил бы в вашем состоянии устаревший рынок. Правильное применение:
if (msg.type === 'match_delta' && msg.changes.updated && msg.changes.updated.oddsBk) {
const prev = state.get(msg.matchId);
if (prev) {
prev.oddsBk = { ...(prev.oddsBk || {}) };
for (const [bk, block] of Object.entries(msg.changes.updated.oddsBk)) {
prev.oddsBk[bk] = block; // замена блока букмекера целиком
}
}
}
  • В одном сообщении приходит блок одного букмекера (изменения у разных букмекеров независимы); added в таких дельтах пустой.
  • Приходят подписчикам обоих типов топиков — и match:{slug}:{id}, и sport:{slug} — но только тем, кто подписался с withBkOdds: true.
  • Появление коэффициентов у матча (флаги hasBkOdds) по-прежнему приходит обычной дельтой полей матча — всем подписчикам, флаг не требуется.

match_deleted​

Если матч удалён из ленты данных (встреча убрана или пересоздана в расписании), подписчики матча и спорт-канала получают уведомление:

{
"type": "match_deleted",
"matchId": 12345678,
"sportSlug": "football",
"timestamp": 1783420000000
}

Получив match_deleted, прекратите ожидать обновления по этому матчу — match_snapshot/match_delta по нему больше не придут. Подписка на топик матча при этом не разрывается автоматически: отпишитесь (unsubscribe) или закройте её вместе с соединением. Если встреча была пересоздана в расписании, она появится под новым matchId — найти её можно через REST (GET /v2/{sportSlug}/matches?date=... или поиск ?q=).

Какие поля меняются​

  • Часто (live-update): homeScore, awayScore, status, matchStatistics, liveEvents, oddsBase, oddsBk (блок букмекера целиком — см. выше).
  • При смене состояния часов матча: currentMatchMinute, currentMatchSecond — это значения на момент сообщения (timestamp), а не тикающий счётчик. В дельту они попадают, как правило, при старте тайма или овертайма и при изменении добавленного времени, а не каждую секунду; любое сообщение с этими полями — точка ресинхронизации. Между такими сообщениями ведите отсчёт локально: elapsedSec = currentMatchMinute * 60 + currentMatchSecond + (Date.now() − msg.timestamp) / 1000, пока status === "inprogress" и идёт игровой отрезок (statusDescription вида 1st half, 2nd half, экстра-таймы; в паузах — Halftime, Extra time halftime, Awaiting extra time, серия пенальти — часы стоят), с ограничением сверху длительностью отрезка плюс добавленное время (overtimeLength). У хоккея/баскетбола (стоп-часы) значение обновляется вместе с данными источника; у тенниса и других видов — это время с начала текущего отрезка. В REST GET /v2/{sportSlug}/matches/{matchId} поля считаются заново при каждом запросе.
  • Однократно по ходу матча: homeTeam.lineup / awayTeam.lineup (за час-два до старта; сам состав приходит один раз, но статистика игроков в нём — players[].statistics — обновляется по ходу матча и может уточняться после его окончания, см. следующий пункт), referee (часто за день), venue (статика на матч).
  • После завершения матча (все виды спорта): матч повторно читается у источника через 6 часов и через двое суток после окончания (теннис и настольный теннис — также через 5 минут и через час), поэтому могут измениться счёт, liveEvents, tennis.pointByPoint / tableTennis.pointByPoint, matchStatistics и homeTeam.lineup.players[].statistics / awayTeam.lineup.players[].statistics. Часть лиг публикует итоговую статистику позже финального свистка (например, в КХЛ на финальной сирене броски в створ бывают равны числу голов), в настольном теннисе розыгрыши публикуются с задержкой. Пока вы подписаны на матч, уточнения приходят обычными match_delta — с путями вида updated.matchStatistics.0.groups.0.statisticsItems.0.homeValue или updated.homeTeam.lineup.players.<i>.statistics.shots (новые строки показателей и новые ключи статистики игрока — в added).
  • Не меняется: id, tournament, season, category, startTimestamp, homeTeam.id, awayTeam.id, dateEvent.

Sport-specific delta-поля​

В changes.added / changes.updated встречаются как универсальные поля (homeScore, awayScore, currentMatchMinute, status, matchStatistics, oddsBase), так и sport-specific:

  • Tennis (tennis.*): tennis.sets[N] (по каждому сыгранному сету), tennis.momentum[N] (новые точки на momentum-графике), tennis.pointByPoint[N] (новые розыгрыши — в WS-потоке приходят независимо от типа подписки).
  • Table Tennis (tableTennis.*): tableTennis.sets[N] (счёт по каждой партии), tableTennis.pointByPoint[N] (новая партия), tableTennis.pointByPoint[N].points[N] (новые розыгрыши — партии по возрастанию номера, розыгрыши в хронологическом порядке, поэтому новые элементы приходят в added). Как и tennis.pointByPoint, приходят независимо от типа подписки. После окончания матча розыгрыши, опубликованные источником с задержкой, приходят такими же дельтами.
  • Esports (esports.*): esports.games[N] (по каждой карте серии), esports.games[N].statistics (обновления командных счётчиков), esports.games[N].rounds.normaltime[N] (новый CS2-раунд), esports.games[N].bans (драфт MOBA), esports.games[N].homeTeamPlayers[N] / awayTeamPlayers[N] (обновления KDA/ADR).
  • Football: referee.* (если данные подгружаются позже старта), liveEvents[N] (новые события матча).

Полный список sport-specific полей по виду спорта — см. Sport-specific data.

Подписка на спорт vs на матч​

Оба типа подписки получают обновления через один и тот же механизм Change Stream, а сообщения форматируются с детализацией (как REST detail-эндпоинт), поэтому liveEvents, tennis.pointByPoint и tableTennis.pointByPoint присутствуют в потоке независимо от типа подписки — в отличие от REST-списка, где этих полей нет. Разница между подписками — в начальном snapshot и охвате.

subscribe на конкретный матч (match:<slug>:<id>)

  • Сразу приходит match_snapshot с полным состоянием.
  • Дальше — обновления только по этому матчу.

subscribe на весь спорт (sport:<slug>)

  • Обновления приходят по всем матчам спорта, у которых произошли изменения. Держите Map по matchId, чтобы разводить состояния.
  • ⚠️ Начальный snapshot по каждому матчу НЕ высылается. Первое сообщение по матчу может оказаться match_delta, который нельзя применить без предыдущего состояния. Поэтому для спорт-подписки:
    • засейте текущее состояние через REST (например, список матчей GET /v2/{sportSlug}/matches), затем применяйте delta поверх;
    • новые матчи (появившиеся в расписании после подписки) в потоке не анонсируются — периодически обновляйте список через REST;
    • любой пришедший match_snapshot трактуйте как полный сброс состояния этого матча;
    • match_delta для матча, которого ещё нет в вашем Map, игнорируйте до прихода snapshot (как в примере applyMessage выше).

Reconnect-стратегия​

  1. При close (любой код кроме 1008) — переподключиться, см. Error codes → Recovery.
  2. Заново подписаться на нужные топики.
  3. Дождаться match_snapshot для каждого матча — игнорировать всё локальное состояние, перезалить из snapshot.
  4. Применять последующие match_delta поверх свежего snapshot.

Нужен ли REST-снапшот после reconnect:

  • Подписка на матч (type: "match") — как правило, нет: на новом соединении subscribe сам присылает match_snapshot — тот же объект Match, что в REST GET /v2/{sportSlug}/matches/{matchId} (с oddsBk при withBkOdds: true), но без блоков pregame, bestPlayers, analytics, scoreStatus и с исходными переводами названий; если эти блоки нужны — запросите REST. На уже открытом соединении повторный subscribe на тот же топик отвечает already_subscribed без снапшота; снапшота «по запросу» нет.
  • Подписка на спорт (type: "sport") — да: начальных снапшотов по матчам в ней нет (снапшот матча приходит только как fallback вместо дельты), новые матчи не анонсируются — засейте состояние через REST (список матчей с нужными fields= / with_bk_odds=true), периодически обновляйте список и применяйте дельты только к матчам, для которых есть состояние.
  • Номеров сообщений (sequence) и повтора пропущенных сообщений нет — сервер не хранит сессию клиента. Дельты не несут удалений полей, поэтому для долгоживущих подписок периодически сверяйте состояние с REST (например, при смене status матча).

Полный готовый пример: Recipes → Live matches feed.