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

Widget je script tag i container element, pa se uklapa u ono što vaš val već renderira. Ovaj primjer koristi Hono JSX, što koriste Val Town HTTP predlošci.

Comment widget 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 komentari padaju. Ako ga ostavite nedefiniranim, zadano se koristi očišćena verzija URL-a trenutne stranice, što je upravo ono što se mijenja na Val Town: val ima dugački *.web.val.run hostname dok ne zatražite subdomenu, grane dobivaju vlastite URL-ove, a preimenovanje stranice mijenja putanju. Svaka varijacija tiho postaje zasebna, prazna nit, a simptom se čita kao "moji su komentari nestali".

Postavite ga na nešto stabilno što kontrolirate, poput sluga objave ili ID-a iz baze podataka, kao gore. Proslijedite i url, kako bi notifikacijski emailovi i moderacijski alati mogli povezati natrag na stvarnu stranicu.

Zadržavanje komentara bez JavaScripta

FastComments renderira cijelu nit server-side, š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-enkodirajte parametre. Server-side verzija podržava anonimno i prijavljeno komentiranje, SSO i ugniježđene odgovore.

Korak 2: Koristite svoj vlastiti račun

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

Vaš tenant ID nalazi se na API secret stranici.

Tenant ID je javan i pripada u kod u pregledniku. API secret nije, i ništa na ovoj stranici ne treba jedan.

Pročitajte ga iz varijable okruženja

Val Town valovi su javni na besplatnom planu, pa je njihov izvor čitljiv svima. Sve osjetljivo držite u varijablama okruženja, čitajte s Deno.env.get:

config.ts

Copy

Run

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

To je na Val Townu važnije nego obično iz još jednog razloga: remixanje vala kopira ključeve varijabli okruženja, ali ne i njihove vrijednosti. Tajna u varijabli okruženja ne prati vaš val u tuđi račun. Tajna zapisana u datoteku prati.

Povratak na "demo" održava val funkcionalnim za svakoga tko ga remixira prije postavljanja vlastitog tenanta.

EU računi

Račun, njegovi podaci i njegovi ključevi žive u jednoj regiji. Ako je vaš stvoren na eu.fastcomments.com, svaka konfiguracija widgeta također treba region: "eu", a skripte se učitavaju s cdn-eu.fastcomments.com. Inače ostavite oboje na miru.

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

Ako vaš val već zna tko je posjetitelj, Secure SSO predaje taj identitet widgetu tako da posjetitelj nikada ne vidi drugu prijavu. Nema endpointa koje treba izgraditi ni ničega što treba pozvati u runtimeu: tri vrijednosti izračunate su na strani servera i prosljeđuju se u konfiguraciji widgeta.

Val Town nudi prijavu bez konfiguracije putem std/oauth, tako da se posjetitelj može prijaviti Val Town računom koji već ima. Zamijenite to onim što koristi vaša aplikacija; FastComments dio se ne mijenja.

Izgradnja payloada na serveru

API tajna potpisuje payload i nikada ne smije dospjeti u kod preglednika. Instalirajte SDK s npm-a, koji radi na Val Town Deno runtimeu bez izmjena:

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() vraća { userDataJSONBase64, verificationHash, timestamp }. Te tri vrijednosti su sve što dospijeva u preglednik. Tajna ih potpisuje i zatim se odbacuje, tako da ništa na stranici ne omogućuje čitatelju da krivotvori drugog korisnika.

Prosljeđivanje widgetu

Widget config with 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 dodaje GET /auth/login, GET /auth/callback i POST /auth/logout umjesto vas. Imajte na umu da je odjava POST, dok widget navigira na logoutURL GET zahtjevom, pa usmjerite logoutURL na malu vlastitu rutu koja šalje POST zahtjev.

Kada je posjetitelj odjavljen, proslijedite sso samo s loginURL. Widget tada prikazuje upit za prijavu umjesto anonimnog okvira za komentare.

Stvari koje mogu poći po krivom

timestamp je u epoch milisekundama, ne smije biti u budućnosti i ne smije biti stariji od dva dana. Generirajte ga na serveru u istom zahtjevu u kojem se računa hash. Generiranje u pregledniku klasična je greška: vrijednost se razlikuje od one koja je potpisana i svaki komentar se odbacuje.

Nikada ne postavljajte isAdmin ili isModerator na temelju davatelja identiteta. Prijava Val Town računom ne govori ništa o tome tko treba moderirati vašu stranicu.

Pogledajte SSO vodič za potpuni popis polja, threadove ograničene grupama i bedževe.

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.

Dodajte ankete u svoju Val Town aplikaciju

Jednom kada je FastComments na vašoj Val Town aplikaciji, možete također pokrenuti live ankete izravno u komentarima. Uključite Enable Polls u postavkama prilagodbe widgeta i gumb ankete pojavljuje se u alatnoj traci komentara. Ankete prihvaćaju od 2 do 10 opcija, rezultati se ažuriraju uživo za sve na stranici, a vi odaberete tko može stvarati ankete i zahtijeva li glasanje prijavu. Nema ništa drugo što treba instalirati na Val Town.

Isprobajte demo Live anketa ili pročitajte Dokumentacija anketa da ih postavite.

Jezik 🇭🇷 Hrvatski

Instalacija Val Town

Ankete

Dodajte live komentiranje u Val Town aplikacije

Korak 1: Dodajte widget

Odaberite urlId prije objave

Zadržavanje komentara bez JavaScripta

Korak 2: Koristite svoj vlastiti račun

Pročitajte ga iz varijable okruženja

EU računi

Broj komentara na indeksnoj stranici

Sigurni SSO s std/oauth

Izgradnja payloada na serveru

Prosljeđivanje widgetu

Stvari koje mogu poći po krivom

Primanje webhookova

Dvije stvari koje grizu

Obrada događaja

Primjeri Vals

Greške domene

Dodajte ankete u svoju Val Town aplikaciju