Dodajte komentarisanje u realnom vremenu 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

Widget je script tag i kontejnerski element, tako da se ubacuje u bilo šta što vaš val već renderuje. Ovaj primer koristi Hono JSX, što je ono što Val Town-ovi HTTP šabloni koriste.

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;

Izaberite urlId pre objavljivanja

urlId određuje u koji thread komentari upadaju. Ako ga ostavite nedefinisan, podrazumevano se koristi očišćena verzija URL-a trenutne stranice, što je upravo ono što se menja na Val Town-u: val ima dugačak *.web.val.run hostname dok ne preuzmete subdomenu, branch-ovi dobijaju svoje URL-ove, a preimenovanje stranice menja putanju. Svaka varijacija tiho postaje poseban, prazan thread, a simptom se čita kao "moji komentari su nestali".

Postavite ga na nešto stabilno što kontrolišete, kao što je slug objave ili database id, kao u primeru iznad. Prosledite i url, kako bi notifikacije mejlom i moderacioni alati mogli da linkuju ka pravoj stranici.

Zadržavanje komentara bez JavaScripta

FastComments renderuje ceo thread server-side, što val može da ubaci 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 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

Ako vaš val već zna ko je posetilac, Secure SSO tu identitetu predaje vidžetu tako da nikad ne vidi drugi login. Nema endpointa koje treba napraviti ni čega što se poziva u runtime-u: tri vrednosti izračunate na serverskoj strani i prosleđujete ih u konfiguraciji vidžeta.

Val Town nudi login bez konfiguracije putem std/oauth, tako da se posetilac može prijaviti Val Town nalogom koji već ima. Zamenite to bilo čime što vaša aplikacija koristi; FastComments deo se ne menja.

Izgradite payload na serveru

API tajna potpisuje payload i nikada ne sme dospeti do koda u pregledaču. Instalirajte SDK sa npm-a, koji radi na Val Town Deno runtime-u bez izmena:

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 vrednosti su sve što dospeva do pregledača. Tajna ih potpisuje i zatim se odbacuje, tako da ništa na stranici ne omogućava čitaocu da lažno predstavi drugog korisnika.

Prosledite ga vidžetu

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 umesto vas. Imajte na umu da je logout POST, dok vidžet navigira na logoutURL GET zahtevom, pa usmerite logoutURL na malu sopstvenu rutu koja šalje POST.

Kada je posetilac odjavljen, prosledite sso samo sa loginURL. Vidžet tada prikazuje upit za prijavu umesto anonimnog polja za komentare.

Stvari koje mogu poći naopako

timestamp je epoch milisekunde, ne sme biti u budućnosti i ne sme biti stariji od dva dana. Generišite ga na serveru u istom zahtevu u kojem se računa hash. Generisanje u pregledaču je klasična greška: vrednost se razlikuje od one koja je heširana i svaki komentar se odbija.

Nikada ne postavljajte isAdmin ili isModerator na osnovu identity provajdera. Prijava Val Town nalogom ne govori ništa o tome ko treba da moderira vaš sajt.

Pogledajte SSO vodič za kompletnu listu polja, teme ograničene grupama i bedževe.

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 Vals

Č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.

Dodajte ankete u vašu Val Town aplikaciju

Jednom kada je FastComments na vašoj Val Town aplikaciji, možete takođe pokretati live ankete direktno u komentarima. Uključite Enable Polls u podešavanjima prilagođavanja widgeta i dugme ankete se pojavljuje u alatnoj traci komentara. Ankete prihvataju od 2 do 10 opcija, rezultati se ažuriraju u realnom vremenu za sve na stranici, i vi birate ko može kreirati ankete i da li glasanje zahteva prijavu. Nema ništa drugo što treba instalirati na Val Town.

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

Jezik 🇷🇸 Srpski (Latinica)

Instalacija Val Town

Ankete

Dodajte komentarisanje u realnom vremenu u aplikacije Val Town

Korak 1: Dodajte vidžet

Izaberite urlId pre objavljivanja

Zadržavanje 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

Izgradite payload na serveru

Prosledite ga vidžetu

Stvari koje mogu poći naopako

Primanje webhook-ova

Dve stvari koje mogu da zagrizu

Obrada događaja

Primer Vals

Greške domena

Dodajte ankete u vašu Val Town aplikaciju