Dodajte live komentiranje u Val Town aplikacije

Val Town pokreće TypeScript na Deno-u, pa je val pravi poslužitelj. To ga čini dobrim izborom za FastComments: widget je script tag na stranici, a sve što treba tajnu, poput Secure SSO ili provjere webhooka, može se izvoditi na poslužiteljskoj strani u istom valu.

Ovaj vodič pokriva dodavanje widgeta za komentare u HTTP val, prikaz broja komentara na indeksnoj stranici, prijavu korisnika pomoću Val Town računa koji već imaju i primanje webhookova za komentare.

Ne trebate račun za probu. Primjeri koriste tenantId: "demo", zajednički sandbox, a korak 2 opisuje prebacivanje na vlastiti.

Korak 1: Dodajte 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 za komentare u HTTP valu

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;

Odaberite urlId prije objave

urlId određuje u koju nit komentar ulazi. Ako ga ne postavite, zadano je očišćena verzija trenutnog URL-a stranice, što je upravo ono što se mijenja na Val Townu: val ima dugo *.web.val.run ime hosta dok ne zatražite poddomen, grane dobivaju svoje URL-ove, a preimenovanje stranice mijenja put. Svaka varijacija tiho postaje zasebna, prazna nit, a simptom se očituje kao "moji komentari su nestali".

Postavite ga na nešto stabilno što kontrolirate, poput slug-a posta ili ID-a iz baze podataka, kao u gornjem primjeru. Proslijedite i url, kako bi e‑mail obavijesti i alati za moderaciju mogli voditi natrag na stvarnu stranicu.

Zadržavanje komentara bez JavaScripta

FastComments prikazuje cijelu nit na poslužitelju, što val može ubaciti u <noscript> blok:

Rezervna opcija bez JavaScripta

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‑kodirajte parametre. Verzija na poslužitelju podržava anonimno i prijavljeno komentiranje, SSO i ugniježdene odgovore.

Korak 2: Koristite svoj račun

tenantId: "demo" je zajednički javni sandbox. Radi bez registracije, zbog čega primjeri koriste njega, ali svi ostali koji probaju FastComments pišu u iste teme i svatko ih može moderirati. Prebacite prije nego što objavite bilo što što vam je važno.

Your tenant ID is on the API secret page.

A tenant ID je javan i pripada kodu u pregledniku. API tajna nije, i ništa na ovoj stranici ne treba jednu.

Read it from an environment variable

Val Town valovi su javni na besplatnoj razini, pa je njihov izvor čitljiv svima. Čuvajte sve osjetljive podatke u varijablama okruženja, čitajte ih pomoću Deno.env.get:

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Samo računi kreirani na eu.fastcomments.com postavljaju ovo na "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

Ovo je važnije nego inače na Val Town iz drugog razloga: remiksanje val-a kopira ključeve varijabli okruženja, ali ne njihove vrijednosti. Tajna pohranjena u varijabli okruženja ne prati vaš val u račun drugog korisnika. Tajna zapisana u datoteku to čini.

Povratak na "demo" omogućuje da val radi za svakoga tko ga remiksira prije postavljanja vlastitog tenanta.

EU accounts

Račun, njegovi podaci i ključevi nalaze se u jednoj regiji. Ako je vaš kreiran na eu.fastcomments.com, svaka konfiguracija widgeta također treba region: "eu", a skripte se učitavaju s cdn-eu.fastcomments.com. U suprotnom ostavite oba nepromijenjena.

Broj komentara na indeksnoj stranici

Na indeksnoj stranici, nemojte prikazivati jedan widget za broj komentara po retku. To je jedan zahtjev po objavi. Koristite grupni broj, koji uzima jedan zahtjev za cijelu stranicu.

Označite svaki redak s urlId koji njegova nit koristi, zatim učitajte grupni widget jednom:

Broj komentara u grupi na indeksnoj stranici

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>

Skript pronalazi svaki element .fast-comments-count na stranici i popunjava njegov broj.

data-fast-comments-url-id mora odgovarati urlId koji widget za komentare objave koristi. Ako widget koristi slug, marker koristi slug. Neslaganje prikazuje nulu na niti koja ima komentare.

Skript provjerava window.FastCommentsBulkCountConfig, pa nije važno postaviti li konfiguraciju prije ili nakon skript taga.

Sigurni SSO s 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) {
  // 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() 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.

Widget konfiguracija s 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 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.

Primanje webhookova

A val je prirodni primatelj webhooka: ima stabilan URL, može provjeriti potpis i ima ugrađenu SQLite i blob pohranu.

FastComments potpisuje ${timestamp}.${body} tajnom API-ja vašeg računa i šalje dva zaglavlja:

Zaglavlja webhooka

Copy

Run

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

Metoda nosi događaj: PUT za kreirani ili ažurirani komentar, DELETE za izbrisani.

Provjera isporuke

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

Dvije stvari koje grizu

Provjerite sirove bajtove. Parsiranje JSON-a i ponovno serijaliziranje mijenja redoslijed ključeva i razmake, pa se hash razlikuje i svaka isporuka ne uspijeva bez očiglednog uzroka. Ovo je uobičajeni razlog da primatelj webhooka „just doesn't work“.

Usporedite u konstantnom vremenu. Obični === na potpis otkriva koliko bajtova se podudara, što je dovoljno za falsificiranje jednog bajta po jedan.

Obrada događaja

Odgovorite brzo. FastComments ponavlja pokušaje kod ne‑2xx odgovora, a krajnja točka koja stalno ne uspijeva na kraju se automatski onemogućuje, stoga stvarni rad obavite nakon odgovora, a ne inline.

Učinite da rad bude idempotentan po ID‑u komentara. Ponovni pokušaj se ponovno potpisuje s novim vremenskim žigom, a isti ID komentara ponovno dolazi pri uređivanju i brisanju, pa nema ničeg stabilnog na čemu se može deduplicirati.

Primjeri Vals

Četiri javna val-a koja možete remixati, svako pokriva jedan dio ovog vodiča.

Blog with comments (live) je Markdown blog s nitima ispod svakog posta i grupiranim brojem komentara na indeksu. Radi odmah nakon što ga remixate, a jedna varijabla okruženja usmjerava ga na vaš vlastiti račun.

SSO demo (live) prijavljuje posjetitelja s njihovim Val Town računom i predaje taj identitet widgetu, tako da nema drugog prijavljivanja.

Webhook receiver (live) provjerava HMAC potpis na svakoj isporuci i pohranjuje događaje u SQLite. Ima gumb koji potpisuje testni payload i isporučuje ga samom sebi, tako da možete vidjeti da je provjera uspješna prije konfiguriranja pravog webhooka.

Agent skills (live) je biblioteka FastComments agenata vještina koje pokrivaju widget, SSO, REST API, moderaciju i migraciju s Disqus‑a. Remixajte ga i Val Townov agent, Townie, automatski preuzima vještine iz skills/, tako da vaš agent zna kako postaviti komentare bez da vi lijepite dokumentaciju u chat.

Iste vještine instaliraju se bilo gdje drugdje pomoću npx skills add fastcomments/skills.

Greške domene

Kad isključite demo najam, widget može odbiti učitavanje s greškom autorizacije. To je zato što FastComments ne zna da bi trebao dopustiti da se vaš račun koristi na toj domeni.

Idite ovdje da dodate svoju stranicu na svoj račun.

Val Town zaslužuje još jedan pogled ovdje, jer se val može pristupiti s više od jednog host imena:

Svaki HTTP val ima dugačak zadani endpoint, <org>--<id>.web.val.run.
Rezerviranje prilagođenog poddomena dodaje <name>.val.run.
A custom domain adds a third.
Granice dobivaju svoje URL-ove.

Dodajte sve host imena s kojih stvarno poslužujete widget. Ako rezervirate poddomen nakon što ste postavili sve, dodajte i to, inače widget radi na starom URL-u i ne uspijeva na novom.

Instalacija Val Town

Dodajte live komentiranje u Val Town aplikacije

Korak 1: Dodajte widget

Odaberite urlId prije objave

Zadržavanje komentara bez JavaScripta

Korak 2: Koristite svoj račun

Read it from an environment variable

EU accounts

Broj komentara na indeksnoj stranici

Sigurni SSO s std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Primanje webhookova

Dvije stvari koje grizu

Obrada događaja

Primjeri Vals

Greške domene

Jezik 🇭🇷 Hrvatski

Instalacija Val Town

Dodajte live komentiranje u Val Town aplikacije

Korak 1: Dodajte widget

Odaberite urlId prije objave

Zadržavanje komentara bez JavaScripta

Korak 2: Koristite svoj račun

Read it from an environment variable

EU accounts

Broj komentara na indeksnoj stranici

Sigurni SSO s std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Primanje webhookova

Dvije stvari koje grizu

Obrada događaja

Primjeri Vals

Greške domene