Tilføj live-kommentarer til Val Town-apps

Val Town kører TypeScript på Deno, så en val er en rigtig server. Det gør den velegnet til FastComments: widget'en er et script‑tag på siden, og alt der har brug for en hemmelighed, som Secure SSO eller verifikation af en webhook, kan køre server‑side i den samme val.

Denne guide dækker, hvordan du tilføjer kommentarswidget'en til en HTTP‑val, viser kommentarantal på en indeks‑side, logger brugere ind med den Val Town‑konto, de allerede har, og modtager kommentar‑webhooks.

Du behøver ikke en konto for at prøve det. Eksemplerne bruger tenantId: "demo", en delt sandbox, og trin 2 dækker, hvordan du skifter til din egen.

Trin 1: Tilføj widgeten

The widget er et script‑tag og et container‑element, så den falder ind i hvad din val allerede rendererer. Dette eksempel bruger Hono JSX, som er hvad Val Towns HTTP‑skabeloner bruger.

Kommentar-widget i en 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;

Vælg et urlId før du udgiver

urlId bestemmer, hvilken tråd en kommentar lander i. Lad den stå uindstillet, så falder den tilbage på en renset version af den aktuelle side‑URL, hvilket er præcis det, der ændrer sig på Val Town: en val har et langt *.web.val.run‑hostname indtil du gør krav på et subdomæne, grene får deres egne URL’er, og omdøbning af en side ændrer stien. Hver variation bliver stiltiende en separat, tom tråd, og symptomet læses som “mine kommentarer forsvandt”.

Sæt den til noget stabilt, som du kontrollerer, f.eks. post‑slug’en eller en database‑id, som ovenfor. Send også url med, så notifikations‑e‑mails og moderationsværktøjerne kan linke tilbage til den rigtige side.

Bevare kommentarer uden JavaScript

FastComments rendererer en fuld tråd på server‑siden, som en val kan placere i en <noscript>‑blok:

Ingen JavaScript-tilbagefald

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‑kod de parametre. Server‑side‑versionen understøtter anonyme og loggede kommentarer, SSO og indlejrede svar.

Trin 2: Brug din egen konto

tenantId: "demo" er en delt offentlig sandbox. Den fungerer uden tilmelding, hvilket er grunden til at eksemplerne bruger den, men alle andre der prøver FastComments skriver i de samme tråde, og enhver kan moderere dem. Skift, før du publicerer noget, du har brug for.

Din tenant‑ID er på API‑hemmelighedssiden.

Et tenant‑ID er offentligt og hører hjemme i browserkoden. En API‑hemmelighed gør det ikke, og intet på denne side kræver en.

Læs den fra en miljøvariabel

Val Town‑værdier er offentlige på den gratis plan, så deres kilde er læsbar for alle. Gem alt følsomt i miljøvariabler, læs med 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";

Dette er vigtigere end normalt på Val Town af en anden grund: remixing af en val kopierer miljøvariabel‑nøgler, men ikke deres værdier. En hemmelighed gemt i en miljøvariabel følger ikke din val ind i en andens konto. En hemmelighed skrevet i en fil gør.

At falde tilbage til "demo" holder val’en i funktion for enhver, der remixer den, før de indstiller deres egen tenant.

EU‑konti

En konto, dens data og dens nøgler lever i én region. Hvis din blev oprettet på eu.fastcomments.com, skal hver widget‑konfiguration også have region: "eu", og scriptet indlæses fra cdn-eu.fastcomments.com. Ellers lad begge være uændrede.

Kommentarantal på en indeks-side

På en indeksside skal du ikke gengive én comment-count-widget pr. række. Det er én anmodning pr. opslag. Brug bulk-tællingen, som tager en enkelt anmodning for hele siden.

Markér hver række med den urlId, dens tråd bruger, og indlæs derefter bulk-widgetten én gang:

Bulk-kommentartællinger på en indeksside

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>

Scriptet finder hvert .fast-comments-count-element på siden og udfylder dets tælling.

data-fast-comments-url-id skal matche den urlId, som opslagets kommentarwidget bruger. Hvis widgetten bruger slug'en, bruger markøren slug'en. En uoverensstemmelse viser nul på en tråd, der har kommentarer.

Scriptet poller efter window.FastCommentsBulkCountConfig, så det er ligegyldigt, om du angiver konfigurationen før eller efter script-tagget.

Sikre SSO med std/oauth

Hvis din val allerede ved, hvem den besøgende er, giver Secure SSO denne identitet videre til widget'en, så de aldrig ser en anden login. Der er ingen endpoints at bygge og intet at kalde ved runtime: du beregner tre værdier server-side og sender dem med i widget-konfigurationen.

Val Town leverer zero-config login med std/oauth, så den besøgende kan logge ind med den Val Town-konto, de allerede har. Udskift det med, hvad din app nu bruger; FastComments-delen ændres ikke.

Byg payload'en på serveren

API-secret'en signerer payload'en og må aldrig nå browser-koden. Installer SDK'en fra npm, som virker på Val Towns Deno-runtime som den er:

sso.ts

Copy

Run

import { SecureSSOPayloadBuilder } from "npm:fastcomments-sdk/server";
export function buildSSOPayload(user) {
  // id skal være stabilt for den samme person, ellers får de en ny kommentar-identitet ved hvert login.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // email er påkrævet og skal være unik.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // username er påkrævet og må ikke være en email.
    username: user.username ?? id,
    displayName: user.username ?? undefined,
    avatar: user.links.profileImageUrl ?? undefined,
  }).getPayload();
}

getPayload() returnerer { userDataJSONBase64, verificationHash, timestamp }. Det er de tre værdier, der når browseren. Secret'en signerer dem og smides derefter væk, så intet på siden gør det muligt for en læser at forfalske en anden bruger.

Send det til widget'en

Widget-konfiguration med 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 widget'en med denne konfiguration
});
export default oauthMiddleware(app.fetch);

oauthMiddleware tilføjer GET /auth/login, GET /auth/callback og POST /auth/logout for dig. Bemærk, at logout er en POST, mens widget'en navigerer til logoutURL med en GET, så peg logoutURL på en lille route hos dig selv, som sender POST'en.

Når den besøgende er logget ud, sendes sso med kun en loginURL. Widget'en viser så en login-prompt i stedet for en anonym kommentarboks.

Ting der går galt

timestamp er i epoch-millisekunder, må ikke ligge i fremtiden og må ikke være mere end to dage gammel. Generér den på serveren i samme request, som beregner hashen. At generere den i browseren er den klassiske fejl: værdien afviger fra den, der blev hashet, og hver kommentar afvises.

Sæt aldrig isAdmin eller isModerator ud fra identitetsudbyderen. At logge ind med en Val Town-konto siger intet om, hvem der bør moderere dit site.

Se SSO-guiden for den fulde feltliste, gruppebegrænsede tråde og badges.

Modtag webhooks

En val er en naturlig webhook-modtager: den har en stabil URL, den kan verificere en signatur, og den har SQLite og blob-lagring indbygget.

FastComments signerer ${timestamp}.${body} med din kontos API-hemmelighed og sender to headers:

Webhook-overskrifter

Copy

Run

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

Metoden bærer hændelsen: PUT for en oprettet eller opdateret kommentar, DELETE for en slettet.

Verificering af en levering

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

To ting der bider

Verificer de rå bytes. Parsing af JSON og gen-serialisering ændrer nøgleordren og mellemrum, så hash'en er forskellig, og hver levering fejler uden en åbenlys årsag. Dette er den sædvanlige grund til, at en webhook-modtager "bare ikke virker".

Sammenlign i konstant tid. En simpel === på signaturen lækker hvor mange bytes der matchede, hvilket er nok til at forfalske en byte ad gangen.

Håndtering af hændelser

Svar hurtigt. FastComments forsøger igen ved et svar, der ikke er 2xx, og et endpoint, der fortsat fejler, deaktiveres til sidst automatisk, så udfør reelt arbejde efter at have svaret i stedet for inline.

Gør arbejdet idempotent på kommentar-id'et. Et retry bliver gen-signeret med en frisk tidsstempel, og det samme kommentar-id ankommer igen ved redigering og sletning, så der er intet stabilt at deduplere på.

Eksempel Vals

Fire offentlige vals, du kan remixe, som hver især dækker en del af denne guide.

Blog med kommentarer (live) er en Markdown-blog med en tråd under hvert opslag og samlede kommentartællinger på indekssiden. Den virker, så snart du remixer den, og én miljøvariabel peger den på din egen konto.

SSO-demo (live) logger besøgende ind med deres Val Town-konto og giver denne identitet videre til widgetten, så der ikke er behov for et andet login.

Webhook-modtager (live) verificerer HMAC-signaturen ved hver levering og gemmer events i SQLite. Den har en knap, der signerer en test-payload og leverer den til sig selv, så du kan se verifikationen lykkes, før du konfigurerer en rigtig webhook.

Agent skills (live) er et bibliotek af FastComments agent skills, der dækker widgetten, SSO, REST API'et, moderation og migrering væk fra Disqus. Remix den, og Val Towns agent, Townie, henter automatisk skills fra skills/, så din agent ved, hvordan man sætter kommentarer op, uden at du skal indsætte dokumentation i chatten.

De samme skills kan installeres andre steder med npx skills add fastcomments/skills.

Domænefejl

Når du slår demo-tenanten fra, kan widgetten nægte at indlæse med en autorisationsfejl. Det skyldes, at FastComments ikke ved, at din konto skal have lov til at blive brugt på det domæne.

Gå hertil for at tilføje dit site til din konto.

Val Town er et andet blik værd her, fordi en val kan være tilgængelig på mere end ét hostname:

Hver HTTP-val har et langt standardendpoint, <org>--<id>.web.val.run.
At gøre krav på et brugerdefineret subdomæne tilføjer <name>.val.run.
Et brugerdefineret domæne tilføjer et tredje.
Branches får deres egne URL'er.

Tilføj de hostnames, du faktisk serverer widgetten fra. Hvis du gør krav på et subdomæne, efter du har sat tingene op, så tilføj det også, ellers virker widgetten på den gamle URL og fejler på den nye.

Tilføj afstemninger til din Val Town-app

Når FastComments er på din Val Town-app, kan du også køre live‑afstemninger direkte i kommentarerne. Slå Enable Polls til i dine widget‑tilpasningsindstillinger, så vises en afstemningsknap i kommentarværktøjslinjen. Afstemninger kan have 2 til 10 muligheder, resultater opdateres live for alle på siden, og du kan vælge, hvem der kan oprette afstemninger, og om afstemning kræver login. Der er intet andet at installere på Val Town.

Prøv Live Polls‑demoen eller læs Polls‑dokumentationen for at sætte dem op.

Sprog 🇩🇰 Dansk

Val Town Installation

Afstemninger

Tilføj live-kommentarer til Val Town-apps

Trin 1: Tilføj widgeten

Vælg et urlId før du udgiver

Bevare kommentarer uden JavaScript

Trin 2: Brug din egen konto

Læs den fra en miljøvariabel

EU‑konti

Kommentarantal på en indeks-side

Sikre SSO med std/oauth

Byg payload'en på serveren

Send det til widget'en

Ting der går galt

Modtag webhooks

To ting der bider

Håndtering af hændelser

Eksempel Vals

Domænefejl

Tilføj afstemninger til din Val Town-app