Live commentaar toevoegen aan Val Town-apps

Val Town draait TypeScript op Deno, dus een val is een echte server. Dat maakt het een goede match voor FastComments: de widget is een script‑tag op de pagina, en alles wat een geheim nodig heeft, zoals Secure SSO of het verifiëren van een webhook, kan server‑side draaien in dezelfde val.

Deze gids behandelt het toevoegen van de commentaarwidget aan een HTTP val, het tonen van commentaartellingen op een indexpagina, het aanmelden van gebruikers met het Val Town‑account dat ze al hebben, en het ontvangen van commentaar‑webhooks.

Je hebt geen account nodig om het te proberen. De voorbeelden gebruiken tenantId: "demo", een gedeelde sandbox, en Stap 2 behandelt het overschakelen naar je eigen.

Stap 1: Voeg de widget toe

The widget is een script‑tag en een container‑element, dus hij wordt ingevoegd waar jouw val al rendert. Dit voorbeeld gebruikt Hono JSX, wat de HTTP‑templates van Val Town gebruiken.

Commentaarwidget in een 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;

Kies een urlId voordat je publiceert

urlId bepaalt in welke thread een opmerking terechtkomt. Laat je het leeg, dan wordt standaard een opgeschoonde versie van de huidige pagin URL gebruikt, wat precies het element is dat verandert op Val Town: een val heeft een lange *.web.val.run hostnaam totdat je een subdomein claimt, takken krijgen hun eigen URL’s, en het hernoemen van een pagina wijzigt het pad. Elke variatie wordt stilletjes een aparte, lege thread, en het symptoom leest als “mijn opmerkingen zijn verdwenen”.

Stel het in op iets stabiels dat je controleert, zoals de post‑slug of een database‑id, zoals hierboven. Geef ook url door, zodat notificatie‑e‑mails en de moderatietools kunnen linken naar de echte pagina.

Reacties behouden zonder JavaScript

FastComments rendert een volledige thread server‑side, die een val kan invoegen in een <noscript>‑blok:

Fallback zonder 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>

URL‑encode de parameters. De server‑side versie ondersteunt anonieme en ingelogde opmerkingen, SSO, en geneste antwoorden.

Stap 2: Gebruik uw eigen account

tenantId: "demo" is een gedeelde openbare sandbox. Het werkt zonder registratie, daarom gebruiken de voorbeelden het, maar iedereen die FastComments uitprobeert schrijft in dezelfde threads en iedereen kan ze modereren. Wissel vóór je iets publiceert dat je belangrijk vindt.

Je tenant ID staat op de API secret pagina.

Een tenant ID is openbaar en hoort in browsercode thuis. Een API secret niet, en niets op deze pagina heeft er een nodig.

Lees het uit een omgevingsvariabele

Val Town vals zijn openbaar op het gratis tier, dus hun broncode is voor iedereen leesbaar. Bewaar gevoelige informatie in omgevingsvariabelen en lees ze uit met 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";

Dit is op Val Town om een tweede reden extra belangrijk: het remixen van een val kopieert de sleutels van omgevingsvariabelen, maar niet hun waarden. Een secret dat in een omgevingsvariabele staat, volgt je val niet naar iemand anders zijn account. Een secret dat in een bestand is geschreven, wel.

De fallback naar "demo" houdt de val werkend voor iedereen die hem remixt voordat die zijn eigen tenant heeft ingesteld.

EU-accounts

Een account, zijn data en zijn sleutels leven in één regio. Als die van jou is aangemaakt op eu.fastcomments.com, heeft elke widget-config ook region: "eu" nodig, en worden de scripts geladen vanaf cdn-eu.fastcomments.com. Laat in andere gevallen beide met rust.

Reactietellingen op een indexpagina

Op een indexpagina moet je niet per rij één comment-count widget renderen. Dat is één verzoek per bericht. Gebruik de bulk‑telling, die één enkel verzoek voor de hele pagina doet.

Markeer elke rij met de urlId die de thread gebruikt, en laad vervolgens de bulk‑widget één keer:

Bulk commentaartellingen op een index

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>

Het script vindt elk .fast-comments-count‑element op de pagina en vult de telling in.

data-fast-comments-url-id moet overeenkomen met de urlId die de commentaarwidget van het bericht gebruikt. Als de widget de slug gebruikt, gebruikt de marker de slug. Een mismatch toont nul op een thread die wel reacties heeft.

Het script pollt naar window.FastCommentsBulkCountConfig, dus het maakt niet uit of je de configuratie vóór of na de script‑tag instelt.

Beveiligde SSO met std/oauth

Als je val al weet wie de bezoeker is, geeft Secure SSO die identiteit door aan de widget zodat deze nooit een tweede login te zien krijgt. Er zijn geen endpoints om te bouwen en niets om tijdens runtime aan te roepen: je berekent drie waarden server-side en geeft ze door in de widget-config.

Val Town levert zero-config login mee met std/oauth, zodat de bezoeker kan inloggen met het Val Town-account dat hij al heeft. Vervang dat door wat jouw app gebruikt; het FastComments-gedeelte verandert niet.

Bouw de payload op de server

De API secret ondertekent de payload en mag nooit in browsercode terechtkomen. Installeer de SDK vanaf npm, die op Val Town's Deno-runtime direct werkt:

sso.ts

Copy

Run

import { SecureSSOPayloadBuilder } from "npm:fastcomments-sdk/server";
export function buildSSOPayload(user) {
  // id moet stabiel zijn voor dezelfde persoon, anders krijgt die bij elke login een nieuwe comment-identiteit.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // email is verplicht en moet uniek zijn.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // username is verplicht en mag geen e-mailadres zijn.
    username: user.username ?? id,
    displayName: user.username ?? undefined,
    avatar: user.links.profileImageUrl ?? undefined,
  }).getPayload();
}

getPayload() geeft { userDataJSONBase64, verificationHash, timestamp } terug. Die drie waarden zijn alles wat de browser bereikt. De secret ondertekent ze en wordt daarna weggegooid, dus niets op de pagina stelt een lezer in staat om een andere gebruiker te vervalsen.

Widget config met 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 de widget met deze config
});
export default oauthMiddleware(app.fetch);

oauthMiddleware voegt GET /auth/login, GET /auth/callback en POST /auth/logout voor je toe. Let op: logout is een POST, terwijl de widget naar logoutURL navigeert met een GET, dus laat logoutURL wijzen naar een eigen kleine route die de POST verstuurt.

Wanneer de bezoeker is uitgelogd, geef je sso door met alleen een loginURL. De widget toont dan een login-prompt in plaats van een anoniem commentaarvak.

Dingen die misgaan

timestamp is epoch in milliseconden, mag niet in de toekomst liggen en mag niet ouder zijn dan twee dagen. Genereer het op de server in dezelfde request waarin de hash wordt berekend. Het in de browser genereren is de klassieke fout: de waarde verschilt van degene die gehasht is en elk commentaar wordt geweigerd.

Zet isAdmin of isModerator nooit op basis van de identity provider. Inloggen met een Val Town-account zegt niets over wie jouw site moet modereren.

Zie de SSO-gids voor de volledige lijst met velden, threads met groepstoegang en badges.

Webhooks ontvangen

A val is een natuurlijke webhook‑ontvanger: het heeft een stabiele URL, het kan een handtekening verifiëren, en het heeft SQLite en blob‑opslag ingebouwd.

FastComments ondertekent ${timestamp}.${body} met het API‑geheim van uw account en stuurt twee headers:

Webhook-headers

Copy

Run

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

De methode draagt het evenement: PUT voor een aangemaakt of bijgewerkt commentaar, DELETE voor een verwijderd commentaar.

Levering verifiëren

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);

Twee dingen die bijten

Verifieer de ruwe bytes. Het parseren van de JSON en opnieuw serialiseren verandert de sleutelvolgorde en witruimte, waardoor de hash verschilt en elke levering faalt zonder duidelijke oorzaak. Dit is de gebruikelijke reden waarom een webhook‑ontvanger “gewoon niet werkt”.

Vergelijk in constante tijd. Een eenvoudige === op de handtekening lekt hoeveel bytes overeenkomen, wat genoeg is om één byte per keer te vervalsen.

Gebeurtenissen afhandelen

Antwoord snel. FastComments probeert opnieuw bij een non-2xx, en een endpoint die blijft falen wordt uiteindelijk automatisch uitgeschakeld, dus voer het echte werk uit na het beantwoorden in plaats van inline.

Maak dat werk idempotent op basis van de commentaar‑id. Een retry wordt opnieuw ondertekend met een verse timestamp, en dezelfde commentaar‑id komt opnieuw terug bij bewerken en verwijderen, dus er is niets stabiels om te dedupliceren op.

Voorbeeld Vals

Vier openbare vals die je kunt remixen, die elk één onderdeel van deze gids behandelen.

Blog met reacties (live) is een Markdown-blog met een thread onder elke post en bulkreactietellingen op de index. Het werkt zodra je het remixt, en één omgevingsvariabele wijst het naar je eigen account.

SSO-demo (live) logt de bezoeker in met hun Val Town-account en geeft die identiteit door aan de widget, dus er is geen tweede login nodig.

Webhook-ontvanger (live) verifieert de HMAC-handtekening bij elke levering en slaat events op in SQLite. Het heeft een knop die een testpayload ondertekent en aan zichzelf levert, zodat je kunt zien dat verificatie slaagt voordat je een echte webhook configureert.

Agent skills (live) is een bibliotheek met FastComments agent skills die de widget, SSO, de REST API, moderatie en migreren van Disqus beslaan. Remix het en Val Town's agent, Townie, pakt de skills automatisch op uit skills/, zodat je agent weet hoe hij reacties moet opzetten zonder dat je documentatie in de chat plakt.

Dezelfde skills installeren overal elders met npx skills add fastcomments/skills.

Domeinfouten

Zodra je de demo tenant uitschakelt, kan de widget weigeren te laden met een autorisatiefout. Dit komt omdat FastComments niet weet dat jouw account op dat domein gebruikt mag worden.

Ga hierheen om je site aan je account toe te voegen.

Val Town verdient hier een tweede blik, omdat een val op meer dan één hostnaam bereikbaar kan zijn:

Elke HTTP-val heeft een lang standaard endpoint, <org>--<id>.web.val.run.
Het claimen van een aangepast subdomein voegt <name>.val.run toe.
Een custom domain voegt een derde toe.
Branches krijgen hun eigen URL's.

Voeg alle hostnames toe waarvan je de widget daadwerkelijk serveert. Als je na de initiële configuratie een subdomein claimt, voeg die dan ook toe, anders werkt de widget op de oude URL en faalt deze op de nieuwe.

Polls toevoegen aan uw Val Town-app

Zodra FastComments op je Val Town‑app staat, kun je ook live polls uitvoeren direct in de reacties. Schakel Enable Polls in je widget‑aanpassingsinstellingen in en er verschijnt een poll‑knop in de commentaarwerkbalk. Polls kunnen 2 tot 10 opties bevatten, de resultaten worden live bijgewerkt voor iedereen op de pagina, en je bepaalt wie polls kan maken en of stemmen een login vereist. Er is verder niets te installeren op Val Town.

Probeer de Live Polls‑demo of lees de Polls‑documentatie om ze in te stellen.

Val Town Installatie

Polls

Live commentaar toevoegen aan Val Town-apps

Stap 1: Voeg de widget toe

Kies een urlId voordat je publiceert

Reacties behouden zonder JavaScript

Stap 2: Gebruik uw eigen account

Lees het uit een omgevingsvariabele

EU-accounts

Reactietellingen op een indexpagina

Beveiligde SSO met std/oauth

Bouw de payload op de server

Geef het door aan de widget

Dingen die misgaan

Webhooks ontvangen

Twee dingen die bijten

Gebeurtenissen afhandelen

Voorbeeld Vals

Domeinfouten

Polls toevoegen aan uw Val Town-app

Taal 🇳🇱 Nederlands

Val Town Installatie

Polls

Live commentaar toevoegen aan Val Town-apps

Stap 1: Voeg de widget toe

Kies een urlId voordat je publiceert

Reacties behouden zonder JavaScript

Stap 2: Gebruik uw eigen account

Lees het uit een omgevingsvariabele

EU-accounts

Reactietellingen op een indexpagina

Beveiligde SSO met std/oauth

Bouw de payload op de server

Geef het door aan de widget

Dingen die misgaan

Webhooks ontvangen

Twee dingen die bijten

Gebeurtenissen afhandelen

Voorbeeld Vals

Domeinfouten

Polls toevoegen aan uw Val Town-app