Aggiungi commenti live alle app Val Town

Val Town esegue TypeScript su Deno, quindi un val è un server reale. Questo lo rende adatto a FastComments: il widget è un tag script nella pagina, e tutto ciò che richiede un segreto, come Secure SSO o la verifica di un webhook, può essere eseguito lato server nello stesso val.

Questa guida copre l'aggiunta del widget dei commenti a un val HTTP, la visualizzazione dei conteggi dei commenti su una pagina indice, l'accesso degli utenti con l'account Val Town che già possiedono, e la ricezione dei webhook dei commenti.

Non è necessario un account per provarlo. Gli esempi usano tenantId: "demo", un sandbox condiviso, e il Passo 2 spiega come passare al proprio.

Passo 1: Aggiungi il widget

The widget is a script tag and a container element, so it drops into whatever your val already renders. This example uses Hono JSX, which is what Val Town's HTTP templates use.

Widget dei commenti in un valore HTTP

Copy

Run

/** @jsxImportSource npm:hono@4/jsx */
import { Hono } from "npm:hono@4";
const app = new Hono();
app.get("/:slug", (c) => {
  const slug = c.req.param("slug");
  const url = new URL(c.req.path, c.req.url).toString();
  const config = JSON.stringify({
    tenantId: "demo",
    urlId: slug,
    url,
  });
  return c.html(
    <html>
      <body>
        <h1>{slug}</h1>
        <div id="fastcomments-widget"></div>
        <script src="https://cdn.fastcomments.com/js/embed-v2.min.js"></script>
        <script
          dangerouslySetInnerHTML={{
            __html:
              `window.FastCommentsUI(document.getElementById("fastcomments-widget"), ${config});`,
          }}
        />
      </body>
    </html>,
  );
});
export default app.fetch;

Scegli un urlId prima di pubblicare

urlId decide in quale thread atterra un commento. Se lo lasci non impostato, di default usa una versione pulita dell'URL della pagina corrente, che è esattamente la cosa che cambia su Val Town: un val ha un hostname lungo *.web.val.run finché non rivendichi un sottodominio, i rami ottengono i propri URL e rinominare una pagina cambia il percorso. Ogni variazione diventa silenziosamente un thread separato e vuoto, e il sintomo appare come "i miei commenti sono scomparsi".

Impostalo su qualcosa di stabile che controlli, come lo slug del post o un ID del database, come mostrato sopra. Passa anche url, così le email di notifica e gli strumenti di moderazione possono collegarsi alla pagina reale.

Mantenere i commenti senza JavaScript

FastComments rende un thread completo lato server, che un val può inserire in un blocco <noscript>:

Fallback senza JavaScript

Copy

Run

<noscript>
  <iframe src="https://fastcomments.com/ssr/comments?tenantId=demo&urlId=POST_SLUG&url=PAGE_URL"
          title="FastComments" width="100%" height="1500px" frameborder="0"
          style="width: 1px !important; min-width: 100% !important; border: none !important;"></iframe>
</noscript>

Codifica URL i parametri. La versione lato server supporta i commenti anonimi e autenticati, SSO e risposte nidificate.

Passo 2: Usa il tuo account

tenantId: "demo" è un sandbox pubblico condiviso. Funziona senza registrazione, motivo per cui gli esempi lo usano, ma tutti gli altri che provano FastComments scrivono negli stessi thread e chiunque può moderarli. Cambia prima di pubblicare qualsiasi cosa a cui tieni.

Il tuo tenant ID si trova nella pagina del segreto API.

Un tenant ID è pubblico e appartiene al codice del browser. Un segreto API no, e nulla in questa pagina ne richiede uno.

Leggilo da una variabile d'ambiente

I valori di Val Town sono pubblici nel livello gratuito, quindi la loro origine è leggibile da tutti. Conserva tutto ciò che è sensibile nelle variabili d'ambiente, leggile con Deno.env.get:

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Only accounts created on eu.fastcomments.com set this, to "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

Questo è più importante del solito su Val Town per un secondo motivo: remixare un val copia le chiavi delle variabili d'ambiente, ma non i loro valori. Un segreto conservato in una variabile d'ambiente non segue il tuo val nell'account di qualcun altro. Un segreto scritto in un file lo fa.

Tornare a "demo" mantiene il val funzionante per chiunque lo remix prima di impostare il proprio tenant.

Account EU

Un account, i suoi dati e le sue chiavi vivono in una sola regione. Se il tuo è stato creato su eu.fastcomments.com, ogni configurazione del widget necessita anche di region: "eu", e gli script si caricano da cdn-eu.fastcomments.com. Altrimenti lascia entrambi così.

Conteggi dei commenti su una pagina indice

Su una pagina indice, non visualizzare un widget di conteggio dei commenti per riga. Questo comporta una richiesta per ogni post. Usa il conteggio in blocco, che richiede una singola richiesta per l'intera pagina.

Marca ogni riga con il urlId che utilizza il suo thread, quindi carica il widget in blocco una sola volta:

Conteggi dei commenti in blocco su una pagina indice

Copy

Run

<ul>
  {posts.map((post) => (
    <li>
      <a href={post.slug}>{post.title}</a>{" "}
      <span class="fast-comments-count" data-fast-comments-url-id={post.slug}></span>
    </li>
  ))}
</ul>
<script
  dangerouslySetInnerHTML={{
    __html: `window.FastCommentsBulkCountConfig = ${
      JSON.stringify({ tenantId: TENANT_ID })
    };`,
  }}
/>
<script src="https://cdn.fastcomments.com/js/embed-widget-comment-count-bulk.min.js"></script>

Lo script trova ogni elemento .fast-comments-count nella pagina e ne riempie il conteggio.

data-fast-comments-url-id deve corrispondere al urlId utilizzato dal widget dei commenti del post. Se il widget utilizza lo slug, il marcatore utilizza lo slug. Una mancata corrispondenza mostra zero su un thread che ha commenti.

Lo script controlla window.FastCommentsBulkCountConfig, quindi non importa se imposti la configurazione prima o dopo il tag script.

SSO sicuro con std/oauth

If your val already knows who the visitor is, Secure SSO hands that identity to the widget so they never see a second login. There are no endpoints to build and nothing to call at runtime: you compute three values server-side and pass them in the widget config.

Val Town ships zero-config login with std/oauth, so the visitor can sign in with the Val Town account they already have. Swap that for whatever your app uses; the FastComments half does not change.

Build the payload on the server

The API secret signs the payload and must never reach browser code. Install the SDK from npm, which works on Val Town's Deno runtime as-is:

sso.ts

Copy

Run

import { SecureSSOPayloadBuilder } from "npm:fastcomments-sdk/server";
export function buildSSOPayload(user) {
  // l'id deve essere stabile per la stessa persona, altrimenti ottengono una nuova identità di commento ad ogni login.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // l'email è obbligatoria e deve essere unica.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // il nome utente è obbligatorio e non può essere un'email.
    username: user.username ?? id,
    displayName: user.username ?? undefined,
    avatar: user.links.profileImageUrl ?? undefined,
  }).getPayload();
}

getPayload() returns { userDataJSONBase64, verificationHash, timestamp }. Those three values are all that reach the browser. The secret signs them and is then dropped, so nothing in the page lets a reader forge a different user.

Configurazione del widget con SSO

Copy

Run

import { getOAuthUserData, oauthMiddleware } from "https://esm.town/v/std/oauth/middleware.ts";
app.get("/", async (c) => {
  const session = await getOAuthUserData(c.req.raw);
  const user = session?.user;
  const config = {
    tenantId: TENANT_ID,
    urlId: "my-thread",
    ...(user
      ? { sso: { ...buildSSOPayload(user), logoutURL: "/logout" } }
      : { sso: { loginURL: "/auth/login" } }),
  };
  // ...renderizza il widget con questa configurazione
});
export default oauthMiddleware(app.fetch);

oauthMiddleware adds GET /auth/login, GET /auth/callback and POST /auth/logout for you. Note that logout is a POST, while the widget navigates to logoutURL with a GET, so point logoutURL at a small route of your own that submits the POST.

When the visitor is logged out, pass sso with only a loginURL. The widget then shows a login prompt instead of an anonymous comment box.

Things that go wrong

timestamp is epoch milliseconds, must not be in the future, and must not be more than two days old. Generate it on the server in the same request that computes the hash. Generating it in the browser is the classic failure: the value differs from the one that was hashed and every comment is rejected.

Never set isAdmin or isModerator from the identity provider. Signing in with a Val Town account says nothing about who should moderate your site.

See the SSO guide for the full field list, group-gated threads, and badges.

Ricezione dei webhook

A val è un ricevitore webhook naturale: ha un URL stabile, può verificare una firma e include SQLite e storage blob integrati.

FastComments firma ${timestamp}.${body} con il segreto API del tuo account e invia due intestazioni:

Intestazioni webhook

Copy

Run

X-FastComments-Timestamp: 1789004710        unix seconds, not milliseconds
X-FastComments-Signature: sha256=<hex>

Il metodo trasporta l'evento: PUT per un commento creato o aggiornato, DELETE per uno eliminato.

Verifica di una consegna

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // The exact bytes that arrived. Do NOT use c.req.json() and re-serialize.
  const rawBody = await c.req.raw.text();
  const timestamp = c.req.raw.headers.get("X-FastComments-Timestamp");
  const signature = c.req.raw.headers.get("X-FastComments-Signature");
  if (!timestamp || !signature) return new Response("Missing headers", { status: 400 });
  // Reject stale deliveries so a captured request cannot be replayed later.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) {
    return new Response("Timestamp outside window", { status: 400 });
  }
  const expected = "sha256=" + createHmac("sha256", Deno.env.get("FASTCOMMENTS_API_SECRET"))
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const a = new TextEncoder().encode(signature);
  const b = new TextEncoder().encode(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return new Response("Signature mismatch", { status: 401 });
  }
  // ...handle JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Due cose che mordono

Verifica i byte grezzi. L'analisi del JSON e la sua riserializzazione cambiano l'ordine delle chiavi e gli spazi, quindi l'hash differisce e ogni consegna fallisce senza una causa evidente. Questo è il motivo più comune per cui un ricevitore webhook "semplicemente non funziona".

Confronta in tempo costante. Un semplice === sulla firma rivela quanti byte corrispondono, il che è sufficiente per forgiarne uno alla volta.

Gestione degli eventi

Rispondi rapidamente. FastComments riprova in caso di risposta non 2xx, e un endpoint che continua a fallire viene disabilitato automaticamente, quindi esegui il lavoro reale dopo aver risposto anziché inline.

Rendi quel lavoro idempotente sull'ID del commento. Un retry viene firmato nuovamente con un timestamp nuovo, e lo stesso ID del commento arriva di nuovo in caso di modifica o eliminazione, quindi non c'è nulla di stabile su cui deduplicare.

Esempi di Vals

Quattro vals pubblici che puoi remixare, ognuno coprendo una parte di questa guida.

Blog con commenti (live) è un blog Markdown con un thread sotto ogni post e conteggi di commenti in blocco nella pagina indice. Funziona nel momento in cui lo remixi, e una variabile d'ambiente lo punta al tuo account.

Demo SSO (live) accede il visitatore con il suo account Val Town e passa quell'identità al widget, così non c'è un secondo login.

Ricevitore Webhook (live) verifica la firma HMAC su ogni consegna e memorizza gli eventi in SQLite. Ha un pulsante che firma un payload di test e lo invia a se stesso, così puoi vedere la verifica riuscire prima di configurare un webhook reale.

Competenze agente (live) è una libreria di competenze dell'agente FastComments che copre il widget, SSO, la REST API, la moderazione e la migrazione da Disqus. Remixala e l'agente di Val Town, Townie, carica automaticamente le competenze dalla cartella skills/, così il tuo agente sa come integrare i commenti senza che tu debba incollare la documentazione nella chat.

Le stesse competenze si installano ovunque altro con npx skills add fastcomments/skills.

Errori di dominio

Una volta disattivato il tenant demo, il widget potrebbe rifiutarsi di caricarsi con un errore di autorizzazione. Questo accade perché FastComments non sa che dovrebbe consentire l'uso del tuo account su quel dominio.

Vai qui per aggiungere il tuo sito al tuo account.

Val Town merita un secondo sguardo qui, perché un val può essere raggiungibile da più di un nome host:

Ogni val HTTP ha un endpoint predefinito lungo, <org>--<id>.web.val.run.
Reclamare un sottodominio personalizzato aggiunge <name>.val.run.
Un dominio personalizzato ne aggiunge un terzo.
I rami ottengono i propri URL.

Aggiungi i nomi host da cui effettivamente servi il widget. Se reclami un sottodominio dopo aver configurato tutto, aggiungilo anche, altrimenti il widget funziona sull'URL vecchio e fallisce su quello nuovo.

Installazione Val Town

Aggiungi commenti live alle app Val Town

Passo 1: Aggiungi il widget

Scegli un urlId prima di pubblicare

Mantenere i commenti senza JavaScript

Passo 2: Usa il tuo account

Leggilo da una variabile d'ambiente

Account EU

Conteggi dei commenti su una pagina indice

SSO sicuro con std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Ricezione dei webhook

Due cose che mordono

Gestione degli eventi

Esempi di Vals

Errori di dominio

Lingua 🇮🇹 Italiano

Installazione Val Town

Aggiungi commenti live alle app Val Town

Passo 1: Aggiungi il widget

Scegli un urlId prima di pubblicare

Mantenere i commenti senza JavaScript

Passo 2: Usa il tuo account

Leggilo da una variabile d'ambiente

Account EU

Conteggi dei commenti su una pagina indice

SSO sicuro con std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Ricezione dei webhook

Due cose che mordono

Gestione degli eventi

Esempi di Vals

Errori di dominio