Как показать участников Discord онлайн на вашем сайте (виджет Discoverse)

Способы показать статистику Discord на сайте

Когда владельцы хотят живые цифры сообщества на своём сайте, обычно выбирают один из трёх подходов:

Зачем виджет Discoverse

• Нулевой прикладной код: custom element `<discoverse-card>`.
• Живая статистика из API Discoverse (online, всего, приглашение).
• Темизация через CSS (`theme`, `primary-color`, `layout`, `language`).
• Работает на статических сайтах, HTML-блоках WordPress, embed Webflow и SPA.
• Тот же источник live-данных, что и листинги discoverse.net.

Быстрая интеграция (копировать-вставить)

Замените `YOUR_SERVER_ID` на Discord snowflake сервера из листинга Discoverse (бот на месте) или на активный premium vanity slug.

<discoverse-card
  server-id="YOUR_SERVER_ID"
  theme="dark"
  show-members="true"
  show-online="true"
  show-join="true"
  layout="card"
  language="ru"
  primary-color="#5865F2"
></discoverse-card>
<script src="https://discoverse.net/widget/v1/embed.js" async></script>

Загружайте `embed.js` один раз на страницу. Можно разместить несколько `<discoverse-card>` с разными `server-id`. На каждой карточке всегда показывается ссылка атрибуции Discoverse.

Где взять `server-id`

Откройте страницу сообщества на Discoverse (`/discord/servers/...`). Числовой Discord ID — это snowflake; premium-сообщества могут использовать vanity-сегмент. ID должен соответствовать листинговой гильдии с ботом Discoverse.

Обязательная атрибуция Discoverse

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

• Виджет всегда показывает ссылку «Powered by Discoverse» на листинг сообщества на discoverse.net (или на документацию, если карточка не загрузилась).
• Нет атрибута для отключения атрибуции. Свои UI на Cards API должны включать эквивалентную видимую ссылку на `url`, возвращаемый API.
• Удаление или сокрытие кредита запрещено условиями бесплатного виджета.

Атрибуты настройки

Все атрибуты — HTML-атрибуты на `<discoverse-card>`.

Техническая спецификация — Cards REST API

Embed запрашивает JSON из публичного Cards API. Тот же endpoint можно вызывать из своего бэкенда или edge worker. Если рендерите свою UI, всё равно нужна видимая ссылка на возвращаемый `url`.

Базовые URL

Production (тот же origin, что у сайта):
`GET https://discoverse.net/api/v1/cards/{serverId}`

Отдельный API-хост (переписывает на тот же handler):
`GET https://api.discoverse.net/v1/cards/{serverId}`

Пример запроса

GET /api/v1/cards/123456789012345678 HTTP/1.1
Host: discoverse.net
Accept: application/json

Пример JSON-ответа

{
  "id": "123456789012345678",
  "kind": "discord",
  "name": "Example Community",
  "online_members": 142,
  "total_members": 8120,
  "icon_url": "https://cdn.discordapp.com/icons/.../icon.png?size=128",
  "invite_url": "https://discord.gg/xxxxxx",
  "status": "online",
  "url": "https://discoverse.net/discord/servers/123456789012345678",
  "updated_at": "2026-09-18T18:00:00.000Z"
}

Поля ответа

• `id` (string) — Discord snowflake.
• `kind` (string) — сейчас `discord`.
• `name` (string) — отображаемое имя.
• `online_members` (number | null) — live online, когда доступно.
• `total_members` (number | null) — всего участников, когда доступно.
• `icon_url` (string) — URL иконки CDN (fallback-аватар при отсутствии).
• `invite_url` (string | null) — Discord invite, если настроен в Discoverse.
• `status` — `online` | `idle` | `offline` | `unknown` (из online-счётчика).
• `url` (string) — канонический URL листинга Discoverse (обязательная цель атрибуции для своих UI).
• `updated_at` (ISO-8601) — время генерации ответа.

CORS, кэш и требования

Endpoint Cards отправляет `Access-Control-Allow-Origin: *`, чтобы браузеры вызывали его со сторонних сайтов. Ответы кэшируются ~30–60 с (`Cache-Control` / `CDN-Cache-Control`). Считайте API публичным read-only live-фидом best-effort — не заменой привилегированных API Discord.

Требования

• Discord-сервер должен быть в листинге Discoverse с ботом Discoverse.
• Держите видимой ссылку атрибуции Discoverse на виджете (обязательно).
• Для рабочей кнопки «Присоединиться» по возможности настройте invite URL в dashboard Discoverse.
• Современные браузеры с Custom Elements + Shadow DOM (все актуальные evergreen-браузеры).

Ответы об ошибках

`400 invalid_server_id` — отсутствует или неверный id.
`404 not_found` — нет подходящей листинговой гильдии (не в листинге, в чёрном списке или нет бота).
Web Component при сбое показывает локализованное «Недоступно» (ссылка атрибуции остаётся).

FAQ

Это официальный виджет Discord?

Нет. Это embed Discoverse. Он использует live-статистику Discoverse и темы, которыми вы управляете.

Нужно ли хостить бота?

Нет. Discoverse уже ведёт bot-инфраструктуру для листинговых сообществ.

Можно ли скрыть ссылку Discoverse?

Нет. Атрибуция обязательна и встроена в `embed.js`. Свои UI на Cards API должны включать эквивалентную видимую ссылку на `url`.

Поддерживаются ли game servers?

Cards API v1 документирует Discord-сообщества. Карточки game server смогут использовать тот же embed-паттерн в следующей версии API; следите за обновлениями на этой странице docs.

Как часто обновляются цифры?

Виджет запрашивает данные при монтировании. HTTP-кэш короткий (десятки секунд). Базовая live-статистика Discoverse обновляется через activity-пайплайн платформы.