Come mostrare i membri Discord online sul tuo sito web (Widget Discoverse)

Modi per mostrare le statistiche Discord su un sito web

Quando i proprietari vogliono numeri live della community sul proprio sito, di solito scelgono uno di questi tre approcci:

Perché usare il widget Discoverse

• Zero codice applicativo: custom element `<discoverse-card>`.
• Statistiche live dall'API Discoverse (membri online, totale, invito).
• Theming compatibile con CSS (`theme`, `primary-color`, `layout`, `language`).
• Funziona su siti statici, blocchi HTML WordPress, embed Webflow e SPA.
• Stessa fonte dati live dei listing discoverse.net.

Integrazione rapida (copia-incolla)

Sostituisci `YOUR_SERVER_ID` con lo snowflake Discord di un server elencato su Discoverse (bot presente), o con uno slug vanity premium attivo.

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

Carica `embed.js` una volta per pagina. Puoi inserire più elementi `<discoverse-card>` con diversi valori di `server-id`. Ogni card mostra sempre un link di attribuzione Discoverse.

Dove trovare `server-id`

Apri la pagina della tua community su Discoverse (`/discord/servers/...`). L'ID numerico Discord è lo snowflake; le community premium possono usare anche il segmento vanity. L'ID deve corrispondere a una gilda elencata con il bot Discoverse presente.

Attribuzione Discoverse obbligatoria

L'uso gratuito del widget Discoverse richiede un link visibile verso Discoverse. L'embed ufficiale renderizza sempre questo credito; non nasconderlo, coprirlo o rimuoverlo.

• Il widget mostra sempre un link «Powered by Discoverse» che punta al listing della community su discoverse.net (o alla documentazione se la card non si è caricata).
• Non esiste un attributo per disabilitare l'attribuzione. Le UI personalizzate basate sulla Cards API devono includere un link visibile equivalente all'`url` restituito dall'API.
• Rimuovere o oscurare il credito non è consentito secondo i termini del widget gratuito.

Attributi di personalizzazione

Tutti gli attributi sono attributi HTML su `<discoverse-card>`.

Specifica tecnica — Cards REST API

L'embed recupera JSON dalla pubblica Cards API. Puoi chiamare lo stesso endpoint dal tuo backend o edge worker. Se renderizzi la tua UI, devi comunque mostrare un link visibile all'`url` restituito.

URL base

Produzione (stessa origin del sito):
`GET https://discoverse.net/api/v1/cards/{serverId}`

Host API dedicato (riscrive verso lo stesso handler):
`GET https://api.discoverse.net/v1/cards/{serverId}`

Esempio di richiesta

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

Esempio di risposta 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"
}

Campi di risposta

• `id` (string) — snowflake Discord.
• `kind` (string) — attualmente `discord`.
• `name` (string) — nome visualizzato.
• `online_members` (number | null) — conteggio online live quando disponibile.
• `total_members` (number | null) — totale membri quando disponibile.
• `icon_url` (string) — URL icona CDN (avatar di fallback se assente).
• `invite_url` (string | null) — invito Discord se configurato su Discoverse.
• `status` — `online` | `idle` | `offline` | `unknown` (derivato dal conteggio online).
• `url` (string) — URL canonica del listing Discoverse (destinazione attribuzione obbligatoria per UI personalizzate).
• `updated_at` (ISO-8601) — momento di generazione della risposta.

CORS, cache e requisiti

L'endpoint Cards invia `Access-Control-Allow-Origin: *` così i browser possono chiamarlo da siti di terze parti. Le risposte sono cacheabili ~30–60 s (`Cache-Control` / `CDN-Cache-Control`). Tratta l'API come feed pubblico, in sola lettura, best-effort in live — non sostituto delle API privilegiate di Discord.

Requisiti

• Il server Discord deve essere elencato su Discoverse con il bot Discoverse presente.
• Mantieni visibile il link di attribuzione Discoverse del widget (obbligatorio).
• Per un pulsante Unisciti funzionante, configura un URL di invito nella dashboard Discoverse quando possibile.
• Browser moderni con Custom Elements + Shadow DOM (tutti i browser evergreen attuali).

Risposte di errore

`400 invalid_server_id` — id mancante o non valido.
`404 not_found` — nessuna gilda elencata corrisponde (non elencata, in blacklist o bot assente).
Il Web Component mostra lo stato localizzato «Non disponibile» in caso di errore (il link di attribuzione resta visibile).

FAQ

È il widget ufficiale Discord?

No. È l'embed Discoverse. Usa statistiche live Discoverse e temi che controlli tu.

Devo hostare un bot?

No. Discoverse gestisce già l'infrastruttura bot per le community elencate.

Posso nascondere il link Discoverse?

No. L'attribuzione è obbligatoria ed è integrata in `embed.js`. Le UI personalizzate sulla Cards API devono includere un link visibile equivalente a `url`.

Supporta i game server?

La Cards API v1 documenta le community Discord. Le card game server possono riusare lo stesso pattern di embed in una versione API successiva; segui questa pagina docs per gli aggiornamenti.

Quanto spesso si aggiornano i numeri?

Il widget effettua il fetch al mount. La cache HTTP è breve (decine di secondi). Le statistiche live sottostanti si aggiornano tramite la pipeline di attività della piattaforma.