Dodajanje živih komentarjev v aplikacije Val Town

Val Town izvaja TypeScript na Deno, zato je val pravi strežnik. To ga naredi primerno za FastComments: gradnik je oznaka script na strani, in vse, kar potrebuje skrivnost, kot je varna SSO ali preverjanje webhooka, lahko teče na strežniški strani v istem valu.

Ta vodnik pokriva dodajanje gradnika za komentarje v HTTP val, prikaz števila komentarjev na indeksni strani, prijavo uporabnikov s računom Val Town, ki ga že imajo, in prejemanje webhookov za komentarje.

Za preizkus ne potrebujete računa. Primeri uporabljajo tenantId: "demo", skupni sandbox, in korak 2 opisuje preklop na vašega.

Korak 1: Dodaj gradnik

Widget je oznaka skripta in vsebnik, zato se umesti v karkoli že izrisuje vaš val. Ta primer uporablja Hono JSX, kar uporabljajo tudi HTTP predloge Val Town.

Komentarski widget v 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;

Izberite urlId pred objavo

urlId določa, v katero nit pride komentar. Če ga pustite nenastavljen, se privzeto uporabi očiščena različica URL-ja trenutne strani, kar je točno tisto, kar se na Val Town spreminja: val ima dolgo ime gostitelja *.web.val.run, dokler ne prevzamete poddomene, veje dobijo svoje URL-je, preimenovanje strani pa spremeni pot. Vsaka različica tiho postane ločena, prazna nit, simptom pa se kaže kot »moji komentarji so izginili«.

Nastavite ga na nekaj stabilnega, kar nadzorujete, na primer slug prispevka ali ID v podatkovni zbirki, kot zgoraj. Podajte tudi url, da se e-poštna obvestila in orodja za moderiranje lahko povežejo nazaj na pravo stran.

Ohranjanje komentarjev brez JavaScripta

FastComments izrisuje celotno nit na strani strežnika, kar val lahko vstavi v blok <noscript>:

Rezerva brez 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>

Parametre kodirajte v URL. Strežniška različica podpira anonimno in prijavljeno komentiranje, SSO ter ugnezdene odgovore.

Korak 2: Uporabi svoj račun

tenantId: "demo" je javni peskovnik v skupni rabi. Deluje brez registracije, zato ga uporabljajo primeri, a vsi ostali, ki preizkušajo FastComments, pišejo v iste niti in jih lahko kdorkoli moderira. Preklopite, preden objavite karkoli pomembnega.

Vaš ID najemnika (tenant ID) je na strani API skrivnosti.

ID najemnika je javen in spada v kodo brskalnika. API skrivnost pa ne, in nič na tej strani je ne potrebuje.

Preberite ga iz okoljske spremenljivke

Val Town vali so na brezplačnem paketu javni, zato je njihova izvorna koda berljiva za vse. Vse občutljivo hranite v okoljskih spremenljivkah in berite z Deno.env.get:

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// To nastavijo samo računi, ustvarjeni na eu.fastcomments.com, in sicer 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 Town pomembnejše kot običajno še iz enega razloga: remixanje vala kopira ključe okoljskih spremenljivk, ne pa njihovih vrednosti. Skrivnost, shranjena v okoljski spremenljivki, ne sledi vašemu valu v račun nekoga drugega. Skrivnost, zapisana v datoteko, pa.

Zasilna vrednost "demo" ohranja val delujočega za vsakogar, ki ga remixa, preden nastavi svoj ID najemnika.

EU računi

Račun, njegovi podatki in njegovi ključi živijo v eni regiji. Če je bil vaš račun ustvarjen na eu.fastcomments.com, potrebuje vsaka konfiguracija pripomočka tudi region: "eu", skripti pa se nalagajo iz cdn-eu.fastcomments.com. Sicer oboje pustite pri miru.

Število komentarjev na indeksni strani

Na strani z indeksom ne upodabljajte enega gradnika za štetje komentarjev na vsako vrstico. To je ena zahteva na objavo. Uporabite množično štetje, ki za celotno stran vzame eno samo zahtevo.

Vsako vrstico označite z urlId, ki ga uporablja njena nit, nato pa gradnik za množično štetje naložite enkrat:

Množično štetje komentarjev na indeksu

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 poišče vse elemente .fast-comments-count na strani in izpolni njihove številke.

data-fast-comments-url-id se mora ujemati z urlId, ki ga uporablja gradnik komentarjev te objave. Če gradnik uporablja slug, oznaka uporablja slug. Neujemljenost prikaže nič pri niti, ki ima komentarje.

Skript anketira window.FastCommentsBulkCountConfig, zato ni pomembno, ali nastavite konfiguracijo pred ali za oznako skripta.

Zavarovano SSO s std/oauth

Če vaš val že ve, kdo je obiskovalec, Secure SSO ta identiteto prenese na pripomoček, tako da obiskovalec nikoli ne vidi druge prijave. Ni vtičnic za izdelavo in ničesar ni treba klicati med izvajanjem: tri vrednosti izračunate na strežniški strani in jih podate v konfiguracijo pripomočka.

Val Town ponuja prijavo brez konfiguracije prek std/oauth, tako da se obiskovalec lahko prijavi z računom Val Town, ki ga že ima. To zamenjajte s tem, kar uporablja vaša aplikacija; del FastComments se ne spremeni.

Izdelava podatkovne vsebine na strežniku

API skrivnost podpiše podatkovno vsebino in nikoli ne sme priti do kode v brskalniku. Namestite SDK iz npm, ki deluje na Val Town's Deno runtime tak, kot je:

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() vrne { userDataJSONBase64, verificationHash, timestamp }. Te tri vrednosti so vse, kar pride do brskalnika. Skrivnost jih podpiše in se nato zavrže, tako da nič na strani ne omogoča bralcu, da bi ponarejil drugega uporabnika.

Posredovanje pripomočku

Konfiguracija pripomočka 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 doda GET /auth/login, GET /auth/callback in POST /auth/logout namesto vas. Upoštevajte, da je odjava POST, medtem ko se pripomoček navigira na logoutURL z GET, zato usmerite logoutURL na majhno lastno pot, ki pošlje POST.

Ko je obiskovalec odjavljen, posredujte sso samo z loginURL. Pripomoček nato namesto anonimnega okvirja za komentarje prikaže poziv za prijavo.

Stvari, ki gredo narobe

timestamp je epoha v milisekundah, ne sme biti v prihodnosti in ne sme biti starejši od dveh dni. Ustvarite ga na strežniku v isti zahtevi, ki izračuna zgoščevalni izvleček. Ustvarjanje v brskalniku je klasična napaka: vrednost se razlikuje od tiste, ki je bila zgoščena, in vsak komentar je zavrnjen.

Nikoli ne nastavite isAdmin ali isModerator iz ponudnika identitete. Prijava z računom Val Town ne pove nič o tem, kdo naj moderatorira vaše spletno mesto.

Za celoten seznam polj, niti, omejene na skupine, in značke si oglejte vodnik SSO.

Prejemanje webhookov

A val je naravni prejemnik webhookov: ima stabilen URL, lahko preveri podpis in ima vgrajeno SQLite ter shranjevanje blobov.

FastComments podpiše ${timestamp}.${body} z API skrivnostjo vašega računa in pošlje dva glavi:

Glave webhooka

Copy

Run

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

Metoda prenaša dogodek: PUT za ustvarjen ali posodobljen komentar, DELETE za izbrisan komentar.

Preverjanje dostave

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // Natančni bajti, ki so prispeli. NE uporabljajte c.req.json() in ponovno serijalizirajte.
  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 });
  // Zavrnite zastarele dostave, da zajetega zahtevka ne morete kasneje ponovno predvajati.
  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 });
  }
  // ...obdelajte JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Dve stvari, ki povzročata težave

Preverite surove bajte. Parsiranje JSON-a in ponovno serijaliziranje spremeni vrstni red ključev in presledke, zato se hash razlikuje in vsaka dostava spodleti brez očitnega vzroka. To je običajen razlog, da prejemnik webhooka "preprosto ne deluje".

Primerjajte v konstantnem času. Preprosto === na podpisu razkrije, koliko bajtov se ujema, kar je dovolj za podvajanje enega bajta naenkrat.

Obdelava dogodkov

Odgovorite hitro. FastComments ponavlja poizvedbe pri ne-2xx odgovoru, in končna točka, ki stalno odpoveduje, je na koncu samodejno onemogočena, zato opravite dejansko delo po odgovoru, namesto v isti zahtevi.

Poskrbite, da bo delo idempotentno glede na ID komentarja. Ponovna poizvedba je ponovno podpisana s svežim časovnim žigom, in isti ID komentarja ponovno prispe pri urejanju in brisanju, zato ni nič stabilnega, na čemer bi se lahko deduplikiralo.

Primer Vals

Štiri javne vals, ki jih lahko remiksate, vsaka pokriva en del tega vodnika.

Blog s komentarji (živo) je Markdown blog z nitjo pod vsakim objavom in skupnimi števci komentarjev na indeksu. Deluje takoj, ko ga remiksate, in ena spremenljivka okolja ga usmeri na vaš račun.

SSO demo (živo) prijavi obiskovalca s svojim računom Val Town in to identiteto predaja gradniku, tako da ni drugega prijavljanja.

Prejemnik Webhook (živo) preveri HMAC podpis pri vsaki dostavi in shranjuje dogodke v SQLite. Ima gumb, ki podpiše testni paket podatkov in ga pošlje samemu sebi, tako da lahko opazujete uspešno preverjanje, preden konfigurirate pravi webhook.

Spretnosti agenta (živo) je knjižnica spretnosti agenta FastComments, ki pokrivajo gradnik, SSO, REST API, moderacijo in migracijo iz Disqus. Remiksajte jo in agent Val Town, Townie, samodejno prebere spretnosti iz skills/, tako da vaš agent ve, kako nastaviti komentarje, ne da bi morali lepljivo vstavljati dokumentacijo v klepet.

Enake spretnosti lahko namestite kjerkoli drugje z npx skills add fastcomments/skills.

Napake domene

Ko izklopite najemnika demo, se lahko widget noče naložiti zaradi napake pri avtorizaciji. To je zato, ker FastComments ne ve, da naj dovoli uporabo vašega računa na tej domeni.

Za dodajanje vašega spletnega mesta v vaš račun pojdite sem.

Val Town je vreden drugega pogleda, ker je val lahko dosegljiv na več kot enem imenu gostitelja:

Vsak HTTP val ima dolgo privzeto končno točko, <org>--<id>.web.val.run.
Prevzem lastne poddomene doda <name>.val.run.
Lastna domena doda tretjo.
Veje imajo svoje URL-je.

Dodajte vsa imena gostiteljev, s katerih dejansko strežete widget. Če poddomeno prevzamete po nastavitvi, jo dodajte tudi, sicer widget deluje na starem URL-ju in odpove na novega.

Dodaj ankete v svojo aplikacijo Val Town

Ko je FastComments v vaši aplikaciji Val Town, lahko tudi izvajate ankete v živo neposredno v komentarjih. V nastavitvah prilagajanja gradnika vklopite Enable Polls in gumb ankete se prikaže v orodni vrstici komentarjev. Ankete sprejmejo od 2 do 10 možnosti, rezultati se posodabljajo v živo za vse na strani, vi pa izberete, kdo lahko ustvarja ankete in ali glasovanje zahteva prijavo. Nič drugega ni potrebno namestiti v Val Town.

Preizkusite demo ankete v živo ali preberite Dokumentacijo o anketah za nastavitev.

Jezik 🇸🇮 Slovenščina

Namestitev Val Town

Ankete

Dodajanje živih komentarjev v aplikacije Val Town

Korak 1: Dodaj gradnik

Izberite urlId pred objavo

Ohranjanje komentarjev brez JavaScripta

Korak 2: Uporabi svoj račun

Preberite ga iz okoljske spremenljivke

EU računi

Število komentarjev na indeksni strani

Zavarovano SSO s std/oauth

Izdelava podatkovne vsebine na strežniku

Posredovanje pripomočku

Stvari, ki gredo narobe

Prejemanje webhookov

Dve stvari, ki povzročata težave

Obdelava dogodkov

Primer Vals

Napake domene

Dodaj ankete v svojo aplikacijo Val Town