> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ru/web-games/matchmaking.md).

# Матчмейкинга

Добавьте матчмейкинг в свою браузерную игру с помощью необязательного JavaScript SDK от Edgegap, который легко расширять и настраивать по мере роста вашего многопользовательского проекта.

Этот SDK — это необязательный стартовый набор для пользователей JavaScript и TypeScript, который позже можно расширять и настраивать.

## 💡 Возможности

{% columns %}
{% column %}

* Полные примеры
* Промисы и асинхронные циклы
* Тикеты, группы, команды
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Переменные матча
* Определения типов (TypeScript)
* Автоматизация обратной подгрузки
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* Браузер, Node.js, Bun, Deno
* Без зависимостей
* Автоматический повтор
  {% endcolumn %}
  {% endcolumns %}

## ✔️ Подготовка

JavaScript SDK содержит необязательные утилиты интеграции для Deployments и Matchmaking. Этот пакет официально поддерживает все современные браузеры, Node.js 22 и новее, Bun и Deno.

{% hint style="info" %}
**Последняя версия JavaScript SDK — `1.1.0`**. Все примеры в этой документации актуальны.
{% endhint %}

{% hint style="success" %}
Этот пакет предоставляется на 100% бесплатно в рамках Условий и положений бесплатного тарифа.
{% endhint %}

#### Требования

<details>

<summary>Разрешите веб-источники вашей игры в конфигурации Matchmaker</summary>

Браузеры обращаются к вашему Matchmaker только со страниц, чьё происхождение указано в `allowed_cors_origins` в конфигурации вашего Matchmaker. Записи сопоставляются с полным origin, включая схему и порт:

* `https://*.my-game.com` сопоставляется со всеми поддоменами по HTTPS,
* `localhost` ничего не сопоставляет, указывайте локальные dev-серверы полностью, например `http://localhost:5173` .

</details>

<details>

<summary>Включите TLS Upgrade для WebSocket-порта вашего игрового сервера</summary>

Установите [порт версии приложения](https://docs.edgegap.com/ru/learn/orkestraciya/application-and-versions.md#port-mapping) протокол в `WS` и включите **TLS Upgrade**, чтобы браузеры могли подключаться по защищённому WebSocket (`wss://`).

</details>

#### Установка

Установите пакет из npm с помощью вашего любимого менеджера пакетов:

{% tabs %}
{% tab title="npm" %}
{% code collapsedlinecount="10" %}

```bash
npm install @edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="pnpm" %}
{% code collapsedlinecount="10" %}

```bash
pnpm add @edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="yarn" %}
{% code collapsedlinecount="10" %}

```bash
yarn add @edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="bun" %}
{% code collapsedlinecount="10" %}

```bash
bun add @edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="deno" %}
{% code collapsedlinecount="10" %}

```bash
deno add npm:@edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="CDN (без сборщика)" %}
Загружайте браузерную сборку в HTML-играх без сборщика. Всё доступно в `Edgegap` global, а Matchmaking — в `Edgegap.matchmaking`:

{% code collapsedlinecount="10" %}

```html
<script src="https://cdn.jsdelivr.net/npm/@edgegap/sdk@1.1.0/dist/browser/edgegap.iife.js"></script>
```

{% endcode %}

Или импортируйте её как ES-модуль:

{% code collapsedlinecount="10" %}

```html
<script type="module">
  import { matchmaking, getConnectionUrl } from 'https://cdn.jsdelivr.net/npm/@edgegap/sdk@1.1.0/dist/browser/edgegap.js'
</script>
```

{% endcode %}
{% endtab %}
{% endtabs %}

У пакета есть две точки входа:

* `@edgegap/sdk/matchmaking` :
  * `GroupAgent`, `ServerAgent`, `MatchEnvironment`, `MatchmakingError`, `Api` .
* `@edgegap/sdk` - общие утилиты:
  * `getConnectionUrl`, `DeploymentEnvironment` .
  * `Observable`, `Logger`, различные HTTP-хелперы.

#### Проверенные источники

Этот пакет публикуется только в npm как [`@edgegap/sdk`](https://www.npmjs.com/package/@edgegap/sdk), из исходного кода на [GitHub](https://github.com/edgegap/sdk-js-sessions-matchmaker-server-browser). CDN вроде jsDelivr и unpkg зеркалируют npm-пакет. Не доверяйте непроверенным источникам, пакеты с похожими названиями вне `@edgegap` scope не связаны с Edgegap!

{% hint style="success" %}
**Каждый релиз публикуется GitHub Actions с** [**npm provenance**](https://docs.npmjs.com/generating-provenance-statements), что связывает пакет с коммитом, из которого он был собран. Проверяйте установленные пакеты с помощью `npm audit signatures` .
{% endhint %}

{% hint style="info" %}
При загрузке из CDN закрепляйте точную версию с помощью [Subresource Integrity](https://developer.mozilla.org/docs/Web/Security/Subresource_Integrity) , чтобы отклонять изменённые версии.
{% endhint %}

### Обновить пакет

Обновите до последней версии с помощью вашего менеджера пакетов:

{% code collapsedlinecount="10" %}

```bash
npm install @edgegap/sdk@latest
```

{% endcode %}

При загрузке из CDN измените версию в URL и заново сгенерируйте хэш целостности.

{% hint style="info" %}
Некоторые релизы могут содержать несовместимые изменения. Это будет отмечено новой MAJOR-версией.
{% endhint %}

## 🍀 Начало работы

Это руководство предполагает базовые знания [Matchmaking](https://docs.edgegap.com/ru/learn/matchmeiking.md) концепций и работающего Matchmaker.

{% hint style="success" %}
**Мы настоятельно рекомендуем клонировать наш** [**Three.js Minigames**](#three.js-minigames) **пример** и следовать коду по мере чтения этого документа.
{% endhint %}

### Обзор

Наш SDK активно использует [Observer](https://refactoring.guru/design-patterns/observer) шаблон программирования и позволяет обрабатывать изменения с помощью колбэков, [промисы](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise), или [асинхронной итерации](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/for-await...of) — что лучше подходит для вашего игрового цикла.

{% hint style="info" %}
Этот пакет интегрирует [Matchmaking](https://docs.edgegap.com/ru/learn/matchmeiking.md) и [Deployments](https://docs.edgegap.com/ru/learn/orkestraciya/deployments.md) утилиты. Вы можете свободно повторно использовать любой код для своих собственных кастомизированных форков и интеграций.
{% endhint %}

Этот пакет включает:

* Утилиты для конкретных сервисов:
  * [#group-agent](#group-agent "mention") - полную интеграцию браузерного клиента для повторного использования/расширения.
  * [#server-agent](#server-agent "mention") - полную интеграцию бэкфилла игрового сервера для повторного использования/расширения.
  * `MatchEnvironment` - типизированные [переменные Matchmaking](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#injected-environment-variables) для вашего игрового сервера.
  * `Api` - определения эндпоинтов, обработка ошибок и автоматизация повторов.
* Типы для конкретных сервисов — типы запросов и ответов, полностью соответствующие JSON API Matchmaking.
* Общие утилиты — URL подключения, переменные развёртывания, логирование, HTTP, observables и т. д.

### Group Agent

**Управление тикетами, получение хоста и обнаружение beacon** выполняются Group Agent.

После создания агент **обработчик (ваш игровой код) должен инициализировать агента** и при необходимости предоставить:

* `onMonitorUpdate` колбэк — отслеживает изменения состояния сервиса.
* `onGroupUpdate` колбэк — отслеживает и реагирует на изменения группы и назначения хоста.

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

Ожидается, что обработчик агента возьмёт управление на себя и будет вызывать функции агента с этого момента:

* `beacons` для получения списка доступных [Ping Beacons](https://docs.edgegap.com/ru/learn/orkestraciya/ping-beacons.md).
* `measureBeaconsRoundTripTime` для измерения задержек по заданному набору beacon.
* `createGroup` чтобы лидер лобби создал присоединяемую группу, в которую можно приглашать друзей.
* `joinGroup` чтобы присоединиться к существующей группе, используя ID группы, переданный через стороннее лобби/бэкенд.
* `setReady` чтобы отметить владельца группы и участников как готовых и начать поиск матчей.
* `nextAssignment` чтобы дождаться назначения хоста после того, как группа начнёт поиск.
* `resumeMatchmaking` чтобы загрузить сохранённую группу и продолжить поиск в случае перезагрузки страницы.
* `stopMatchmaking` чтобы удалить тикет (если матч не найден) и покинуть очередь.
* `dispose` чтобы очистить все таймеры, прервать запросы и удалить подписчиков.

Вот три разных демонстрируемых шаблона конкурентности, выберите тот, который вам больше нравится:

{% tabs %}
{% tab title="Promise" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl } from '@edgegap/sdk'
import { GroupAgent, MatchmakingError } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize()

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)

try {
  const assignment = await agent.nextAssignment()
  connect(getConnectionUrl(assignment, 'gameport'), agent.group.current.ticket_id)
} catch (error) {
  if (!(error instanceof MatchmakingError)) throw error
  showRetryButton(error.message)
}
```

{% endcode %}
{% endtab %}

{% tab title="Асинхронный цикл" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, ObservableActionType } from '@edgegap/sdk'
import { GroupAgent } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize()

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)

for await (const { type, message, event, current } of agent.group) {
  if (type === ObservableActionType.Error) {
    showRetryButton(message)
    break
  }
  if (event.code !== 'updated') continue
  showStatus(current.status)
  if (current.status === 'CANCELLED') {
    showRetryButton(message)
    break
  }
  if (current.status !== 'HOST_ASSIGNED') continue
  connect(getConnectionUrl(current.assignment, 'gameport'), current.ticket_id)
  break
}
```

{% endcode %}
{% endtab %}

{% tab title="Колбэки" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, ObservableActionType } from '@edgegap/sdk'
import { GroupAgent } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize(
  (_monitor, _type, message) => console.log('matchmaker', message),
  (group, type, message, event) => {
    if (type === ObservableActionType.Error) return showRetryButton(message)
    if (event.code !== 'updated') return
    showStatus(group.current.status)
    if (group.current.status === 'CANCELLED') return showRetryButton(message)
    if (group.current.status === 'HOST_ASSIGNED')
      connect(getConnectionUrl(group.current.assignment, 'gameport'), group.current.ticket_id)
  },
)

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)
```

{% endcode %}
{% endtab %}
{% endtabs %}

`profile` и `attributes` должно соответствовать профилю в вашей конфигурации Matchmaker, `gameport` — это имя порта из вашей версии приложения. `getConnectionUrl` возвращает `wss://` URL для WebSocket-портов.

{% hint style="warning" %}
**Браузеры не могут отправлять ICMP-, UDP- или TCP-ping, на которые отвечают beacon Edgegap,**, поэтому `measureBeaconsRoundTripTime` по умолчанию сообщает `0` для каждого beacon. Передайте свою собственную `ping` реализацию в параметрах агента, чтобы измерять задержку другим способом.
{% endhint %}

Когда устанавливается новое соединение игрока, ожидается, что игрок отправит свой ID тикета игровому серверу с помощью вашего netcode, чтобы сопоставить подключения с [переменные Matchmaking](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#injected-environment-variables). Ваш игровой сервер в этот момент ещё может инициализироваться, поэтому **игроки должны несколько раз повторять подключение**:

{% code collapsedlinecount="10" %}

```javascript
const connect = (url, ticketId, attempts = 10) => {
  const socket = new WebSocket(url)
  let opened = false
  socket.onopen = () => {
    opened = true
    socket.send(JSON.stringify({ ticketId }))
  }
  socket.onclose = () => !opened && attempts > 1 && setTimeout(() => connect(url, ticketId, attempts - 1), 1000)
}
```

{% endcode %}

{% hint style="success" %}
Сохраняйте данные подключения в клиенте или бэкенде игры, чтобы переподключиться в случае неожиданного сбоя. См. [#resume-after-reload](#resume-after-reload "mention").
{% endhint %}

### Server Agent

Server Agent выполняет **создание backfill, обнаружение назначения тикетов, обнаружение отказа от backfill и его удаления. Он также отслеживает и воссоздаёт backfill, которые истекли, у которых истёк grace period подключения или которые были оставлены — чтобы достичь желаемого размера команды**.

Server Agent отслеживает текущих подключённых игроков и автоматически включает их тикеты в новые backfill, чтобы гарантировать, что игроки из backfill будут подобраны согласно правилам настроенного профиля.

После создания агент **обработчик (ваш серверный код) должен инициализировать агента** и предоставить:

* `тикеты` - игроки, уже сопоставленные с этим сервером, из [переменные Matchmaking](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#injected-environment-variables).
* `onMonitorUpdate` колбэк — отслеживает изменения состояния сервиса.
* `onBackfillUpdate` колбэк — отслеживает и реагирует на изменения backfill.

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

Ожидается, что обработчик сервера возьмёт управление на себя и будет вызывать функции агента с этого момента:

* `addBackfills` чтобы создавать backfill, пока назначенные игроки и открытые backfill не достигнут целевого размера команды.
* `playerConnected` чтобы не заменять первоначальных или добавленных из backfill игроков, которые так и не подключились.
  * Возвращает тикет игрока, или `null` если тикет не назначен этому серверу — отклоняйте такие соединения.
* `abandonPlayer` чтобы сообщить, что подключённый игрок покинул сервер и должен быть заменён.
* `abandonAllBackfills` чтобы немедленно остановить backfilling сервера и удалить backfill.
  * Этот метод следует вызвать перед остановкой сервера. Игроки, уже назначенные на этот момент, должны заново присоединиться к matchmaking, поскольку сервер завершает работу.
  * Назначенные backfill на момент этого вызова всё ещё могут подключиться в пределах настроенного grace period.
* `abandonBackfill` чтобы принудительно отказаться от конкретного backfill (кастомные реализации обработчиков).
* `dispose` чтобы очистить таймеры, прервать запросы и удалить подписчиков.

{% code collapsedlinecount="10" %}

```javascript
import { WebSocketServer } from 'ws'
import { DeploymentEnvironment } from '@edgegap/sdk'
import { MatchEnvironment, ServerAgent } from '@edgegap/sdk/matchmaking'

const deployment = DeploymentEnvironment.fromEnv(process.env)
const match = MatchEnvironment.fromEnv(process.env)

const agent = new ServerAgent({
  baseUrl: process.env.MATCHMAKER_URL,
  authToken: process.env.MATCHMAKER_TOKEN,
  profile: match.matchProfile,
  targetTeamSize: 4,
  attributes: {
    assignment: {
      request_id: deployment.requestId,
      fqdn: deployment.fqdn,
      public_ip: deployment.publicIp,
      ports: deployment.portMapping,
      location: deployment.location,
    },
  },
})

agent.initialize(
  match.tickets,
  (_monitor, _type, message) => console.log('matchmaker', message),
  (_backfills, _type, _message, event) => {
    if (event.code === 'assigned') console.log(`ticket ${event.ticketId} is joining`)
  },
)
agent.addBackfills()

const wss = new WebSocketServer({ port: 7777 })

wss.on('connection', (socket) => {
  socket.once('message', (data) => {
    const { ticketId } = JSON.parse(data.toString())
    if (!agent.playerConnected(ticketId)) return socket.close(4001, 'unknown ticket')
    socket.once('close', () => agent.abandonPlayer(ticketId))
  })
})

process.once('SIGTERM', () => agent.abandonAllBackfills(() => process.exit(0)))
```

{% endcode %}

{% hint style="danger" %}
**Загружайте серверные токены из переменных окружения**, например используя [Переменные версии приложения](https://docs.edgegap.com/ru/learn/orkestraciya/application-and-versions.md#injected-variables). Токены, которые используют ваши игровые серверы, никогда не должны включаться в браузерный bundle.
{% endhint %}

### Переменные матча

Читайте [переменные Matchmaking](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#injected-environment-variables) на вашем игровом сервере, чтобы проверять подключающихся игроков и назначать команды, не вызывая никакого API:

{% code collapsedlinecount="10" %}

```javascript
import { WebSocketServer } from 'ws'
import { MatchEnvironment } from '@edgegap/sdk/matchmaking'

const match = MatchEnvironment.fromEnv(process.env)
const wss = new WebSocketServer({ port: 7777 })

wss.on('connection', (socket) => {
  socket.once('message', (data) => {
    const { ticketId } = JSON.parse(data.toString())
    const ticket = match.tickets[ticketId]
    if (!ticket) return socket.close(4001, 'unknown ticket')
    console.log(`игрок присоединился к команде ${ticket.team_id} в матче ${match.matchId}`)
  })
})
```

{% endcode %}

`match` содержит `matchProfile`, `matchId`, `тикеты` (по ticket ID), `группы`, `команды`, и сопоставленные `равенство` и `пересечение` значения. Разбор никогда не выбрасывает исключение, поэтому тот же сервер работает локально.

Игроки, присоединяющиеся через backfill не перечислены в `match.tickets`, поэтому серверы, использующие Server Agent, проверяют подключающихся игроков с помощью `agent.playerConnected` вместо этого.

## 🧪 Примеры

Начните с примеров, включая полную рабочую интеграцию как для сервера, так и для клиента.

### [Three.js Minigames](#three.js-minigames)

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

Добавьте новый профиль matchmaking и игровой сервер, чтобы легко расширить этот пример под вашу игру.

### Соберитесь в группу

Присоединяйтесь к очереди матчмейкинга вместе с группой друзей, при этом всем игрокам требуется подтвердить участие перед началом поиска. Владелец группы создаёт группу и делится её ID через ваше лобби или бэкенд:

{% code collapsedlinecount="10" %}

```javascript
const attributes = { beacons: latencies }

// на устройстве владельца группы
agent.group.subscribe((group, _type, _message, event) => {
  if (event.code === 'created') shareWithFriends(group.current.group_id)
})
agent.createGroup({ profile: 'simple-example', attributes, is_ready: false }, true)

// на устройстве каждого друга, после того как они получат ID группы
agent.joinGroup({ profile: 'simple-example', attributes, is_ready: false }, groupId, true)

// на каждом устройстве, когда игрок готов
agent.setReady(true)
const assignment = await agent.nextAssignment()
```

{% endcode %}

### Возобновление после перезагрузки

Сохраняйте группу при изменении и возобновляйте поиск (или переподключение), когда страница снова загружается:

{% code collapsedlinecount="10" %}

```javascript
agent.initialize(undefined, (group) => {
  if (group.current) localStorage.setItem('edgegap-group', JSON.stringify(group.current))
  else if (group.previous?.status !== 'HOST_ASSIGNED') localStorage.removeItem('edgegap-group')
})

const saved = JSON.parse(localStorage.getItem('edgegap-group'))
if (saved?.status === 'HOST_ASSIGNED') {
  connect(getConnectionUrl(saved.assignment, 'gameport'), saved.ticket_id)
} else if (saved) {
  agent.resumeMatchmaking(saved)
  connect(getConnectionUrl(await agent.nextAssignment(), 'gameport'), saved.ticket_id)
}
```

{% endcode %}

Удаляйте сохранённую группу с помощью `localStorage.removeItem('edgegap-group')` после завершения матча, чтобы игроки не переподключались к завершённому матчу.

### Бэкфилл

Повторно используйте серверные ресурсы и добавляйте игроков в уже запущенные развёртывания. Установите целевой размер команды и дождитесь добавления игроков. Включает автоматический период ожидания подключения и воссоздание истёкших бэкфиллов, см. [#server-agent](#server-agent "mention").

Настройте обработчик сервера для многокомандных или асимметричных составов команд.

## ⚙️ Настройка

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

✅ Handler — безопасно подключайте наблюдателей интерфейса и вносите незначительные дополнения или изменения,

⚠️ Agent — форкните исходный код и изменяйте управление жизненным циклом игрока на свой страх и риск,

⚠️ API — создайте собственную интеграцию с нуля, используя `Api` и тщательно отобранные утилиты.

Обработчики могут наблюдать любые события, генерируемые агентами Server и Group, как описано ниже.

{% hint style="warning" %}
Обязательно ознакомьтесь с [Подробный разбор матчмейкинга](https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md) понятиями перед внесением изменений.
{% endhint %}

{% hint style="info" %}
Если вам нужна помощь, [свяжитесь с нами через Discord](https://discord.gg/MmJf8fWjnt). Для поддержки по играм в реальном времени см. нашу [систему тикетов](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### События клиента

Агент Group генерирует типизированные события, которые обработчики могут наблюдать и использовать.

{% hint style="success" %}
Чтение состояния через обращение к `.current` и `.previous` любому наблюдаемому объекту, и **ветвитесь по `event.code`** поскольку сообщения событий могут меняться между версиями. 🔴 `Ошибка` События также сохраняют полное сообщение об ошибке в `.error` .
{% endhint %}

Предварительный просмотр событий, генерируемых наблюдаемым объектом `monitor` :

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="200">Код события</th><th width="300">Параметры события</th><th>Описание</th></tr></thead><tbody><tr><td>🟢 <code>Обновление</code></td><td><code>исправно</code></td><td>-</td><td>Все системы в порядке.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>неисправно</code></td><td>-</td><td>Неожиданная проблема.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>monitor_failed</code></td><td><code>detail</code></td><td>Неправильная конфигурация или неожиданная проблема.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>beacons_failed</code></td><td><code>detail</code></td><td>Неожиданная проблема.</td></tr></tbody></table>

Предварительный просмотр событий, генерируемых наблюдаемым объектом `group` :

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="200">Код события</th><th width="300">Параметры события</th><th>Описание</th></tr></thead><tbody><tr><td>🟢 <code>Обновление</code></td><td><code>created</code></td><td>-</td><td>Группа успешно создана.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>create_failed</code></td><td><code>detail</code></td><td>Не удалось создать группу.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>joined</code></td><td>-</td><td>Группа успешно присоединена.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>join_failed</code></td><td><code>detail</code></td><td>Не удалось присоединиться к группе.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>resumed</code></td><td>-</td><td>Группа успешно возобновлена.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>not_found</code></td><td><code>detail?</code></td><td>Не является участником группы или группа истекла.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>conflict</code></td><td>-</td><td>Пожалуйста, покиньте текущую группу перед попыткой создать/присоединиться к новой группе или передайте <code>abandon: true</code>.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>member_updated</code></td><td><code>isReady</code></td><td>Участник обновлён с новым значением Ready.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>member_update_failed</code></td><td>-</td><td>Нельзя снять готовность после того, как группа начала поиск матча.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>update_failed</code></td><td><code>detail</code></td><td>Не удалось обновить участника группы.</td></tr><tr><td>🔵 <code>Журнал</code></td><td><code>polling</code></td><td><code>attempt</code>, <code>maxAttempts</code></td><td>Агент инициировал опрос статуса группы. Выводится только с <code>logPollingUpdates: true</code>.</td></tr><tr><td>🔵 <code>Журнал</code></td><td><code>polling_stopped</code></td><td>-</td><td>Агент остановил опрос статуса группы. Выводится только с <code>logPollingUpdates: true</code>.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>polling_failed</code></td><td><code>reason: 'max_retries'</code>, <code>detail</code></td><td>Агент исчерпал максимальное количество последовательных повторных попыток опроса. Проверьте состояние сервиса.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>polling_failed</code></td><td><code>reason: 'error'</code>, <code>detail</code></td><td>Агент получил неретрайабельную ошибку при опросе. Проверьте состояние сервиса.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>updated</code></td><td><code>status</code></td><td>Обнаружено изменение статуса группы во время опроса.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>abandoned</code></td><td>-</td><td>Заявка успешно удалена.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>abandon_failed</code></td><td><code>reason: 'not_found'</code></td><td>Агент не смог найти группу для удаления, возможно, она истекла.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>abandon_failed</code></td><td><code>reason: 'match_found'</code></td><td>Агент не смог удалить сопоставленную группу. Отключите abandonment или <a data-mention href="https://docs.edgegap.com/ru/learn/matchmeiking/matchmaker-in-depth.md#backfill-match">Подробный обзор</a> чтобы заменить игрока.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>abandon_failed</code></td><td><code>reason: 'error'</code>, <code>detail</code></td><td>Не удалось удалить группу или членство.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>restart_skipped</code></td><td>-</td><td>Группа уже сопоставлена, последующее действие после abandonment было пропущено.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>removed</code></td><td>-</td><td>Группа завершена или истекла, локальная ссылка удалена.</td></tr></tbody></table>

### События сервера

Агент Server генерирует типизированные события, которые обработчики могут наблюдать и использовать. Агент Server нужен только для [#backfill](#backfill "mention").

{% hint style="info" %}
Текущие назначенные заявки можно прочитать из свойства агента Server `assignments` в любое время, а время подключения — из `connectedAt` .
{% endhint %}

{% hint style="success" %}
Чтение состояния через обращение к `.current` и `.previous` любому наблюдаемому объекту, и **ветвитесь по `event.code`** поскольку сообщения событий могут меняться между версиями. 🔴 `Ошибка` События также сохраняют полное сообщение об ошибке в `.error` .
{% endhint %}

Предварительный просмотр событий, генерируемых наблюдаемым объектом `monitor` :

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="200">Код события</th><th width="300">Параметры события</th><th>Описание</th></tr></thead><tbody><tr><td>🟢 <code>Обновление</code></td><td><code>исправно</code></td><td>-</td><td>Все системы в порядке.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>неисправно</code></td><td>-</td><td>Неожиданная проблема.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>monitor_failed</code></td><td><code>detail</code></td><td>Неправильная конфигурация или неожиданная проблема.</td></tr></tbody></table>

Предварительный просмотр событий, генерируемых наблюдаемым объектом `backfills` :

<table data-full-width="true"><thead><tr><th width="125">Тип действия</th><th width="200">Код события</th><th width="300">Параметры события</th><th>Описание</th></tr></thead><tbody><tr><td>🟢 <code>Обновление</code></td><td><code>created</code></td><td><code>backfillId</code></td><td>Бэкфилл успешно создан.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>create_failed</code></td><td><code>detail</code></td><td>Неожиданная проблема с бэкфиллом. Проверьте состояние сервиса.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>capacity_reached</code></td><td>-</td><td>Сервер заполнен, бэкфилл не создан.</td></tr><tr><td>🔵 <code>Журнал</code></td><td><code>polling</code></td><td><code>attempt</code>, <code>maxAttempts</code></td><td>Агент инициировал опрос бэкфиллов. Выводится только с <code>logPollingUpdates: true</code>.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>assigned</code></td><td><code>backfillId</code>, <code>ticketId</code></td><td>Заявка успешно назначена бэкфиллу.</td></tr><tr><td>🔵 <code>Журнал</code></td><td><code>polling_stopped</code></td><td>-</td><td>Агент остановил опрос, больше не осталось бэкфиллов для опроса.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'not_found'</code></td><td>Не найдено, ссылка удаляется. Вероятнее всего, бэкфилл истёк.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'max_retries'</code></td><td>Превышено количество повторных попыток, отказ от всех бэкфиллов.</td></tr><tr><td>🔴 <code>Ошибка</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'error'</code>, <code>detail</code></td><td>Неожиданная проблема, отказ от бэкфилла и его замена.</td></tr><tr><td>🔵 <code>Журнал</code></td><td><code>abandoned</code></td><td><code>backfillId</code></td><td>Бэкфилл отменён, ссылка удаляется.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>abandon_failed</code></td><td><code>backfillId</code>, <code>reason: 'not_found'</code></td><td>Бэкфилл не найден, вероятно, истёк или это повторный вызов.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>abandon_failed</code></td><td><code>backfillId</code>, <code>reason: 'error'</code>, <code>detail</code></td><td>Не удалось отменить бэкфилл, ссылка удаляется.</td></tr><tr><td>🟢 <code>Обновление</code></td><td><code>removed</code></td><td><code>backfillId</code></td><td>Ссылка на бэкфилл удалена. Бэкфилл будет автоматически заменён, если его не остановить.</td></tr><tr><td>🟡 <code>Предупреждение</code></td><td><code>remove_failed</code></td><td><code>backfillId</code></td><td>Ссылка на бэкфилл не найдена, вероятно, это повторный вызов.</td></tr></tbody></table>
