Dodajte live komentarisanje u aplikacije Val Town

Val Town pokreće TypeScript na Deno, pa je val pravi server. To ga čini dobrim izborom za FastComments: widget je script tag na stranici, a sve što zahteva tajnu, poput Secure SSO ili verifikacije webhook‑a, može se izvršavati na serveru u istom val‑u.

Ovaj vodič pokriva dodavanje widgeta za komentare u HTTP val, prikazivanje broja komentara na indeksnoj stranici, prijavljivanje korisnika pomoću Val Town naloga koji već imaju, i primanje webhook‑ova za komentare.

Ne morate imati nalog da biste ga isprobali. Primeri koriste tenantId: "demo", zajednički sandbox, a korak 2 objašnjava kako preći na svoj.

Korak 1: Dodajte vidžet

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 val-u

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;

Izaberite urlId pre nego što objavite

urlId određuje u koju nit komentar ulazi. Ako ga ostavite nepostavljenim, podrazumeva se očišćena verzija trenutnog URL-a stranice, što je upravo ono što se menja na Val Town-u: val ima dugačko *.web.val.run ime hosta dok ne rezervišete poddomen, grane dobijaju svoje URL-ove, a preimenovanje stranice menja put. Svaka varijacija tiho postaje zasebna, prazna nit, i simptom se manifestuje kao „moji komentari su nestali“.

Postavite ga na nešto stabilno što vi kontrolišete, poput slug-a posta ili ID-a iz baze podataka, kao što je gore prikazano. Takođe prosledite url, kako bi e‑mail obaveštenja i alati za moderaciju mogli da se povežu nazad na pravu stranicu.

Čuvanje komentara bez JavaScripta

FastComments renderuje kompletnu nit na serveru, što val može ubaciti u <noscript> blok:

Fallback 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‑enkodujte parametre. Server‑side verzija podržava anonimno i prijavljeno komentarisanje, SSO i ugnježdene odgovore.

Korak 2: Koristite svoj nalog

tenantId: "demo" je zajednički javni sandbox. Radi bez registracije, zbog čega se primeri koriste, ali svi ostali koji probaju FastComments pišu u iste teme i svako može da ih moderira. Prebacite pre nego što objavite bilo šta što vam je važno.

Vaš tenant ID je na API secret page.

Tenant ID je javan i nalazi se u kodu preglednika. API tajna nije, i ništa na ovoj stranici ne zahteva tajnu.

Pročitajte ga iz promenljive okruženja

Val Town val‑ovi su javni na besplatnom nivou, pa je njihov izvor čitljiv svima. Čuvajte sve osetljive podatke u promenljivama 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 nalozi 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 značajnije nego obično na Val Town iz drugog razloga: remiksovanje val‑a kopira ključeve promenljivih okruženja, ali ne i njihove vrednosti. Tajna čuvana u promenljivoj okruženja ne prati vaš val u nečiji drugi nalog. Tajna zapisana u fajl to čini.

Vraćanje na "demo" omogućava da val radi za svakoga ko ga remiksuje pre nego što postavi sopstveni tenant.

EU nalozi

Nalog, njegovi podaci i ključevi žive u jednoj regiji. Ako je vaš kreiran na eu.fastcomments.com, svaka konfiguracija widgeta takođe treba region: "eu", a skripte se učitavaju sa cdn-eu.fastcomments.com. U suprotnom ostavite oba nepromenjena.

Broj komentara na indeksnoj stranici

Na indeksnoj stranici, ne prikazujte po jedan widget za brojanje komentara po redu. To je jedan zahtev po objavi. Koristite grupno brojanje, koje zahteva jedan zahtev za celu stranicu.

Označite svaki red sa urlId koji njegova nit koristi, zatim učitajte bulk widget jednom:

Grupno brojanje komentara 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 da se podudara sa urlId koji widget za komentare objave koristi. Ako widget koristi slug, marker koristi slug. Nepodudaranje prikazuje nulu na niti koja ima komentare.

Skript periodično proverava window.FastCommentsBulkCountConfig, pa nije važno da li konfiguraciju postavite pre ili posle <script> taga.

Sigurni SSO sa 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.

Konfiguracija widgeta sa 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 webhook-ova

A val je prirodni webhook prijemnik: ima stabilan URL, može verifikovati potpis i ima ugrađenu SQLite i blob skladište.

FastComments potpisuje ${timestamp}.${body} tajnim ključem API-ja vašeg naloga i šalje dva zaglavlja:

Zaglavlja webhook-a

Copy

Run

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

Metoda nosi događaj: PUT za kreiran ili ažuriran komentar, DELETE za obrisan komentar.

Verifikacija isporuke

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // Tačni bajtovi koji su stigli. Nemojte koristiti c.req.json() i ponovo serijalizovati.
  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 });
  // Odbaci zastarele isporuke kako uhvaćeni zahtev ne bi mogao biti ponovo reprodukovan kasnije.
  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 });
  }
  // ...obradi JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Dve stvari koje mogu da zagrizu

Verifikujte sirove bajtove. Parsiranje JSON-a i njegovo ponovo serijalizovanje menja redosled ključeva i razmake, pa se hash razlikuje i svaka isporuka ne uspeva bez očiglednog uzroka. Ovo je uobičajen razlog da webhook prijemnik „jednostavno ne radi“.

Uporedite u konstantnom vremenu. Obična === operacija na potpisu otkriva koliko bajtova se podudara, što je dovoljno da se falsifikuje po jedan bajt odjednom.

Obrada događaja

Odgovorite brzo. FastComments ponovo pokušava na ne‑2xx odgovoru, a krajnja tačka koja stalno ne uspeva se na kraju automatski onemogućava, zato obavite stvarni rad nakon odgovora, a ne inline.

Učinite da rad bude idempotentan po ID‑u komentara. Ponovni pokušaj se ponovo potpisuje svežim timestamp‑om, a isti ID komentara dolazi ponovo pri izmeni i brisanju, pa nema stabilnog podatka za deduplikaciju.

Primer vrednosti

Četiri javna vala koja možete remixovati, svako pokriva jedan deo ovog vodiča.

Blog sa komentarima (uživo) je Markdown blog sa nitima ispod svakog posta i grupnim brojem komentara na indeksu. Radi odmah kada ga remixujete, a jedna promenljiva okruženja usmerava ga na vaš sopstveni nalog.

SSO demo (uživo) prijavljuje posetioca pomoću njihovog Val Town naloga i predaje taj identitet widgetu, tako da nema drugog prijavljivanja.

Webhook prijemnik (uživo) verifikuje HMAC potpis na svakoj isporuci i čuva događaje u SQLite. Ima dugme koje potpisuje testni payload i šalje ga samom sebi, tako da možete videti da verifikacija uspe pre podešavanja pravog webhook‑a.

Veštine agenta (uživo) je biblioteka FastComments veština agenta koja pokriva widget, SSO, REST API, moderaciju i migraciju sa Disqus‑a. Remixujte je i agent Val Town‑a, Townie, automatski preuzima veštine iz skills/, tako da vaš agent zna kako da postavi komentare bez da vi lepite dokumentaciju u ćaskanje.

Iste veštine se instaliraju bilo gde drugde pomoću npx skills add fastcomments/skills.

Greške domena

Jednom kada isključite demo tenant, widget može odbiti učitavanje sa greškom autorizacije. To je zato što FastComments ne zna da treba da dozvoli da se vaš nalog koristi na tom domenu.

Idite ovde da dodate svoj sajt na vaš nalog.

Val Town vredi još jednom pogledati, jer se val može pristupiti sa više od jednog host imena:

Svaki HTTP val ima dugačak podrazumevani endpoint, <org>--<id>.web.val.run.
Rezervisanje prilagođenog poddomena dodaje <name>.val.run.
A custom domain adds a third.
Grane dobijaju svoje URL‑ove.

Dodajte ona host imena sa kojih zaista servirate widget. Ako potražite poddomen nakon što ste postavili stvari, dodajte i to, inače widget radi na starom URL‑u i ne uspeva na novom.

Instalacija Val Town

Dodajte live komentarisanje u aplikacije Val Town

Korak 1: Dodajte vidžet

Izaberite urlId pre nego što objavite

Čuvanje komentara bez JavaScripta

Korak 2: Koristite svoj nalog

Pročitajte ga iz promenljive okruženja

EU nalozi

Broj komentara na indeksnoj stranici

Sigurni SSO sa std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Primanje webhook-ova

Dve stvari koje mogu da zagrizu

Obrada događaja

Primer vrednosti

Greške domena

Jezik 🇷🇸 Srpski (Latinica)

Instalacija Val Town

Dodajte live komentarisanje u aplikacije Val Town

Korak 1: Dodajte vidžet

Izaberite urlId pre nego što objavite

Čuvanje komentara bez JavaScripta

Korak 2: Koristite svoj nalog

Pročitajte ga iz promenljive okruženja

EU nalozi

Broj komentara na indeksnoj stranici

Sigurni SSO sa std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Primanje webhook-ova

Dve stvari koje mogu da zagrizu

Obrada događaja

Primer vrednosti

Greške domena