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

Il widget è uno script tag e un elemento contenitore, quindi si inserisce in qualsiasi cosa il tuo val già renderizzi. Questo esempio usa Hono JSX, che è ciò che usano i template HTTP di Val Town.

Widget dei commenti in un HTTP val

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 determina in quale thread finirà un commento. Se lo lasci non impostato, assume come valore predefinito una versione ripulita 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 branch ottengono URL propri, e rinominare una pagina cambia il percorso. Ogni variazione diventa silenziosamente un thread separato e vuoto, e il sintomo si manifesta come "i miei commenti sono spariti".

Impostalo su qualcosa di stabile che controlli tu, come lo slug del post o un id del database, come 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 renderizza 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 i parametri in URL. La versione lato server supporta commenti anonimi e da utenti autenticati, SSO e risposte annidate.

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

Se il tuo val già conosce l'identità del visitatore, Secure SSO passa quell'identità al widget, così non vedrà mai un secondo login. Non ci sono endpoint da costruire e nulla da chiamare a runtime: calcoli tre valori lato server e li passi nella configurazione del widget.

Val Town offre login zero-config con std/oauth, quindi il visitatore può accedere con l'account Val Town che già possiede. Sostituiscilo con quello che usa la tua app; la parte FastComments non cambia.

Costruisci il payload sul server

L'API secret firma il payload e non deve mai finire nel codice del browser. Installa l'SDK da npm, che funziona sul runtime Deno di Val Town così com'è:

sso.ts

Copy

Run

import { SecureSSOPayloadBuilder } from "npm:fastcomments-sdk/server";
export function buildSSOPayload(user) {
  // id must be stable for the same person, or they get a new comment identity on every login.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // email is required and must be unique.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // username is required and cannot be an email.
    username: user.username ?? id,
    displayName: user.username ?? undefined,
    avatar: user.links.profileImageUrl ?? undefined,
  }).getPayload();
}

getPayload() restituisce { userDataJSONBase64, verificationHash, timestamp }. Quei tre valori sono tutto ciò che arriva al browser. Il secret li firma e viene poi scartato, quindi nulla nella pagina permette a un lettore di falsificare un utente diverso.

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" } }),
  };
  // ...render the widget with this config
});
export default oauthMiddleware(app.fetch);

oauthMiddleware aggiunge per te GET /auth/login, GET /auth/callback e POST /auth/logout. Nota che il logout è una POST, mentre il widget naviga verso logoutURL con una GET, quindi punta logoutURL a una piccola route tua che invia la POST.

Quando il visitatore non è autenticato, passa sso con solo un loginURL. Il widget mostrerà quindi un prompt di login invece della casella dei commenti anonima.

Cose che vanno storte

timestamp è in millisecondi epoch, non deve essere nel futuro e non deve essere più vecchio di due giorni. Genera lato server nella stessa richiesta che calcola l'hash. Generarlo nel browser è l'errore classico: il valore differisce da quello firmato e ogni commento viene rifiutato.

Non impostare mai isAdmin o isModerator dall'identity provider. Accedere con un account Val Town non dice nulla su chi dovrebbe moderare il tuo sito.

Consulta la guida SSO per l'elenco completo dei campi, i thread con accesso a gruppi e i badge.

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.

Aggiungi sondaggi alla tua app Val Town

Una volta che FastComments è nella tua app Val Town, puoi anche eseguire sondaggi live direttamente nei commenti. Attiva Enable Polls nelle impostazioni di personalizzazione del widget e un pulsante per i sondaggi appare nella barra degli strumenti dei commenti. I sondaggi accettano da 2 a 10 opzioni, i risultati si aggiornano in tempo reale per tutti gli utenti sulla pagina, e puoi scegliere chi può creare sondaggi e se il voto richiede l'accesso. Non c'è nient'altro da installare su Val Town.

Prova la demo dei sondaggi live oppure leggi la Documentazione sui sondaggi per configurarli.

Installazione Val Town

Sondaggi

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

Costruisci il payload sul server

Passalo al widget

Cose che vanno storte

Ricezione dei webhook

Due cose che mordono

Gestione degli eventi

Esempi di Vals

Errori di dominio

Aggiungi sondaggi alla tua app Val Town

Lingua 🇮🇹 Italiano

Installazione Val Town

Sondaggi

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

Costruisci il payload sul server

Passalo al widget

Cose che vanno storte

Ricezione dei webhook

Due cose che mordono

Gestione degli eventi

Esempi di Vals

Errori di dominio

Aggiungi sondaggi alla tua app Val Town