Dodaj komentarze na żywo do aplikacji Val Town

Val Town uruchamia TypeScript na Deno, więc val jest prawdziwym serwerem. To sprawia, że jest to dobre dopasowanie do FastComments: widget jest tagiem skryptu na stronie, a wszystko, co wymaga sekretu, jak Secure SSO czy weryfikacja webhooka, może działać po stronie serwera w tym samym val.

Ten przewodnik opisuje dodawanie widgetu komentarzy do HTTP val, wyświetlanie liczby komentarzy na stronie indeksu, logowanie użytkowników przy użyciu konta Val Town, które już posiadają, oraz odbieranie webhooków komentarzy.

Nie potrzebujesz konta, aby to wypróbować. Przykłady używają tenantId: "demo", współdzielonego sandboxu, a krok 2 opisuje przejście na własny.

Krok 1: Dodaj widżet

Widżet to tag skryptu i element kontenera, więc pasuje do tego, co Twoja val już renderuje. Ten przykład używa Hono JSX, czyli tego, czego używają szablony HTTP Val Town.

Widżet komentarzy w val HTTP

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;

Wybierz urlId przed publikacją

urlId decyduje o tym, do którego wątku trafi komentarz. Jeśli go nie ustawisz, domyślnie będzie to oczyszczona wersja adresu URL bieżącej strony — a to dokładnie to, co zmienia się w Val Town: val ma długi hostname *.web.val.run, dopóki nie zajmiesz subdomeny, gałęzie mają własne adresy URL, a zmiana nazwy strony zmienia ścieżkę. Każda wariacja po cichu staje się osobnym, pustym wątkiem, a objaw wygląda jak „moje komentarze zniknęły”.

Ustaw coś stabilnego, czym sterujesz, np. slug posta lub identyfikator z bazy danych, jak powyżej. Przekaż też url, aby e-maile z powiadomieniami i narzędzia moderacji mogły linkować z powrotem do prawdziwej strony.

Zachowywanie komentarzy bez JavaScript

FastComments renderuje cały wątek po stronie serwera, a val może wstawić go do bloku <noscript>:

Rozwiązanie zastępcze bez JavaScript

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>

Zakoduj parametry w URL. Wersja po stronie serwera obsługuje komentowanie anonimowe i zalogowane, SSO oraz zagnieżdżone odpowiedzi.

Krok 2: Użyj własnego konta

tenantId: "demo" jest współdzielonym publicznym sandboxem. Działa bez rejestracji, dlatego przykłady go używają, ale wszyscy inni korzystający z FastComments piszą w tych samych wątkach i każdy może je moderować. Przełącz się, zanim opublikujesz cokolwiek, na czym Ci zależy.

Twój identyfikator najemcy znajduje się na stronie tajnego klucza API.

Identyfikator najemcy jest publiczny i powinien znajdować się w kodzie przeglądarki. Tajny klucz API nie jest publiczny i nic na tej stronie nie wymaga go.

Odczytaj go ze zmiennej środowiskowej

Wartości Val Town są publiczne w darmowym planie, więc ich źródło jest dostępne dla wszystkich. Przechowuj wszelkie wrażliwe dane w zmiennych środowiskowych, odczytując je za pomocą Deno.env.get:

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Only accounts created on eu.fastcomments.com set this, to "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

Ma to większe znaczenie niż zwykle w Val Town z powodu drugiego powodu: przepisanie wartości (remiksowanie) kopiuje klucze zmiennych środowiskowych, ale nie ich wartości. Tajny klucz przechowywany w zmiennej środowiskowej nie podąża za Twoją wartością do konta innej osoby. Tajny klucz zapisany w pliku podąża.

Powrót do "demo" utrzymuje działanie wartości dla każdego, kto ją przepisze przed ustawieniem własnego najemcy.

Konta UE

Konto, jego dane i klucze znajdują się w jednym regionie. Jeśli Twoje zostało utworzone na eu.fastcomments.com, każda konfiguracja widgetu musi również zawierać region: "eu", a skrypty ładują się z cdn-eu.fastcomments.com. W przeciwnym razie pozostaw oba niezmienione.

Liczba komentarzy na stronie indeksu

Na stronie indeksu nie renderuj jednego widżetu liczenia komentarzy na wiersz. To powoduje jedno żądanie na każdy post. Użyj liczenia zbiorczego, które wymaga jednego żądania dla całej strony.

Oznacz każdy wiersz urlId, którego używa wątek, a następnie załaduj widżet zbiorczy jednorazowo:

Zbiorcze liczenie komentarzy na indeksie

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>

Skrypt znajduje każdy element .fast-comments-count na stronie i wstawia jego liczbę.

data-fast-comments-url-id musi odpowiadać urlId, którego używa widżet komentarzy posta. Jeśli widżet używa slug, znacznik używa slug. Niezgodność powoduje wyświetlenie zera w wątku, który ma komentarze.

Skrypt nasłuchuje window.FastCommentsBulkCountConfig, więc nie ma znaczenia, czy ustawisz konfigurację przed, czy po znaczniku skryptu.

Bezpieczne SSO z std/oauth

Jeśli Twój val już wie, kim jest odwiedzający, Secure SSO przekazuje tę tożsamość widgetowi, dzięki czemu nigdy nie zobaczy on drugiego ekranu logowania. Nie ma endpointów do zbudowania ani niczego do wywołania w czasie działania: obliczasz trzy wartości po stronie serwera i przekazujesz je w konfiguracji widgetu.

Val Town oferuje logowanie bez konfiguracji dzięki std/oauth, więc odwiedzający może zalogować się kontem Val Town, które już posiada. Zamień to na to, czego używa Twoja aplikacja; część FastComments się nie zmienia.

Zbuduj payload na serwerze

API secret podpisuje payload i nigdy nie może trafić do kodu przeglądarki. Zainstaluj SDK z npm, które działa na runtime Deno Val Town bez zmian:

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() zwraca { userDataJSONBase64, verificationHash, timestamp }. Tylko te trzy wartości trafiają do przeglądarki. Secret podpisuje je, a następnie jest odrzucany, więc nic na stronie nie pozwoli czytelnikowi podrobić innego użytkownika.

Przekaż go do widgetu

Konfiguracja widgetu z 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 za Ciebie GET /auth/login, GET /auth/callback i POST /auth/logout. Zauważ, że logout to POST, podczas gdy widget przechodzi do logoutURL za pomocą GET, więc skieruj logoutURL na małą własną trasę, która wysyła ten POST.

Gdy odwiedzający jest wylogowany, przekaż sso zawierające tylko loginURL. Widget wyświetli wtedy monit o logowanie zamiast anonimowego pola komentarzy.

Rzeczy, które mogą pójść nie tak

timestamp to epoch w milisekundach, nie może być w przyszłości i nie może być starszy niż dwa dni. Generuj go na serwerze w tym samym żądaniu, w którym obliczasz hash. Generowanie go w przeglądarce to klasyczny błąd: wartość różni się od tej, która została podpisana, i każdy komentarz jest odrzucany.

Nigdy nie ustawiaj isAdmin ani isModerator na podstawie dostawcy tożsamości. Zalogowanie się kontem Val Town nie mówi nic o tym, kto powinien moderować Twoją stronę.

Zobacz przewodnik SSO po pełną listę pól, wątki ograniczone grupami oraz odznaki.

Odbieranie webhooków

A val jest naturalnym odbiorcą webhooków: ma stabilny URL, może weryfikować podpis i ma wbudowaną bazę SQLite oraz przechowywanie blobów.

FastComments podpisuje ${timestamp}.${body} przy użyciu sekretu API Twojego konta i wysyła dwa nagłówki:

Nagłówki webhooka

Copy

Run

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

Metoda przenosi zdarzenie: PUT dla utworzonego lub zaktualizowanego komentarza, DELETE dla usuniętego.

Weryfikacja dostawy

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // Dokładne bajty, które nadeszły. Nie używaj c.req.json() i nie serializuj ponownie.
  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 });
  // Odrzuć przestarzałe dostawy, aby przechwycony request nie mógł być odtworzony później.
  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);

Dwie rzeczy, które gryzą

Zweryfikuj surowe bajty. Parsowanie JSON i ponowne serializowanie zmienia kolejność kluczy oraz białe znaki, więc hash się różni i każda dostawa kończy się niepowodzeniem bez oczywistej przyczyny. To najczęstszy powód, dla którego odbiorca webhooka „po prostu nie działa”.

Porównuj w stałym czasie. Zwykłe === na podpisie ujawnia, ile bajtów się zgadza, co wystarczy, aby podrobić jeden bajt naraz.

Obsługa zdarzeń

Odpowiadaj szybko. FastComments ponawia próbę przy kodzie innym niż 2xx, a endpoint, który ciągle zawodzi, zostaje ostatecznie automatycznie wyłączony, więc wykonuj rzeczywistą pracę po odpowiedzi, a nie w linii.

Uczyń to działanie idempotentnym względem identyfikatora komentarza. Ponowna próba jest podpisywana ponownie z nowym znacznikiem czasu, a ten sam identyfikator komentarza pojawia się ponownie przy edycji i usunięciu, więc nie ma nic stabilnego, na czym można by deduplikować.

Przykładowe Vals

Cztery publiczne valy do remiksu, z których każdy obejmuje jeden element tego przewodnika.

Blog with comments (live) to blog w Markdown z wątkiem komentarzy pod każdym wpisem i zbiorczymi licznikami komentarzy na stronie głównej. Działa od razu po remiksie, a jedna zmienna środowiskowa wskazuje go na Twoje własne konto.

SSO demo (live) loguje odwiedzającego za pomocą konta Val Town i przekazuje tę tożsamość do widgetu, więc nie ma drugiego logowania.

Webhook receiver (live) weryfikuje podpis HMAC przy każdej dostawie i zapisuje zdarzenia w SQLite. Ma przycisk, który podpisuje testowy payload i dostarcza go do samego siebie, więc możesz zobaczyć, jak weryfikacja działa, zanim skonfigurujesz prawdziwy webhook.

Agent skills (live) to biblioteka umiejętności agenta FastComments obejmująca widget, SSO, REST API, moderację i migrację z Disqus. Zremiksuj ją, a agent Val Town, Townie, automatycznie pobierze umiejętności z skills/, więc Twój agent będzie wiedział, jak podłączyć komentarze, bez wklejania dokumentacji do czatu.

Te same umiejętności można zainstalować gdziekolwiek indziej za pomocą npx skills add fastcomments/skills.

Błędy domeny

Gdy wyłączysz najemcę demo, widget może odmówić załadowania z błędem autoryzacji. Dzieje się tak, ponieważ FastComments nie wie, że powinien zezwolić na użycie Twojego konta na tej domenie.

Przejdź tutaj, aby dodać swoją witrynę do konta.

Val Town zasługuje na ponowne spojrzenie, ponieważ val może być dostępny pod więcej niż jedną nazwą hosta:

Każdy HTTP val ma długi domyślny punkt końcowy, <org>--<id>.web.val.run.
Zarezerwowanie niestandardowej subdomeny dodaje <name>.val.run.
Niestandardowa domena dodaje trzecią.
Gałęzie otrzymują własne adresy URL.

Dodaj wszystkie nazwy hostów, z których rzeczywiście serwujesz widget. Jeśli zarezerwujesz subdomenę po skonfigurowaniu wszystkiego, dodaj ją również, w przeciwnym razie widget będzie działał na starym URL i nie zadziała na nowym.

Dodaj ankiety do swojej aplikacji Val Town

Po zainstalowaniu FastComments w aplikacji Val Town, możesz także uruchamiać ankiety na żywo bezpośrednio w komentarzach. Włącz Enable Polls w ustawieniach personalizacji widgetu, a przycisk ankiety pojawi się na pasku narzędzi komentarza. Ankiety mogą mieć od 2 do 10 opcji, wyniki aktualizują się na żywo dla wszystkich na stronie, a Ty decydujesz, kto może tworzyć ankiety i czy głosowanie wymaga logowania. Nie musisz instalować niczego dodatkowego w Val Town.

Wypróbuj demo ankiet na żywo lub przeczytaj dokumentację ankiet, aby je skonfigurować.

Język 🇵🇱 Polski

Instalacja Val Town

Ankiety

Dodaj komentarze na żywo do aplikacji Val Town

Krok 1: Dodaj widżet

Wybierz urlId przed publikacją

Zachowywanie komentarzy bez JavaScript

Krok 2: Użyj własnego konta

Odczytaj go ze zmiennej środowiskowej

Konta UE

Liczba komentarzy na stronie indeksu

Bezpieczne SSO z std/oauth

Zbuduj payload na serwerze

Przekaż go do widgetu

Rzeczy, które mogą pójść nie tak

Odbieranie webhooków

Dwie rzeczy, które gryzą

Obsługa zdarzeń

Przykładowe Vals

Błędy domeny

Dodaj ankiety do swojej aplikacji Val Town