Live-Kommentare zu Val Town Apps hinzufügen

Val Town führt TypeScript auf Deno aus, sodass ein Val ein echter Server ist. Das macht es zu einer guten Wahl für FastComments: Das Widget ist ein Script‑Tag auf der Seite, und alles, was ein Geheimnis benötigt, wie Secure SSO oder die Verifizierung eines Webhooks, kann serverseitig im selben Val ausgeführt werden.

Dieser Leitfaden behandelt das Hinzufügen des Kommentar‑Widgets zu einem HTTP‑Val, das Anzeigen von Kommentarzahlen auf einer Indexseite, das Anmelden von Benutzern mit dem bereits vorhandenen Val‑Town‑Konto und das Empfangen von Kommentar‑Webhooks.

Sie benötigen kein Konto, um es auszuprobieren. Die Beispiele verwenden tenantId: "demo", eine gemeinsam genutzte Sandbox, und Schritt 2 behandelt das Wechseln zu Ihrem eigenen.

Schritt 1: Widget hinzufügen

Das Widget ist ein Script-Tag und ein Container-Element, daher lässt es sich in alles einfügen, was dein Val bereits rendert. Dieses Beispiel verwendet Hono JSX, was auch die HTTP-Templates von Val Town nutzen.

Kommentar-Widget in einem HTTP val

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;

Wähle eine urlId, bevor du deployst

urlId entscheidet, in welchem Thread ein Kommentar landet. Lässt du es unset, wird standardmäßig eine bereinigte Version der aktuellen Seiten-URL verwendet – genau das, was sich auf Val Town ändert: Ein Val hat einen langen *.web.val.run Hostnamen, bis du eine Subdomain beanspruchst, Branches erhalten eigene URLs, und das Umbenennen einer Seite ändert den Pfad. Jede Variante wird stillschweigend zu einem separaten, leeren Thread, und das Symptom liest sich als „meine Kommentare sind verschwunden".

Setze es auf etwas Stabiles, das du kontrollierst, wie den Post-Slug oder eine Datenbank-ID, wie oben. Übergib auch url, damit Benachrichtigungs-E-Mails und die Moderations-Tools auf die echte Seite verlinken können.

Kommentare ohne JavaScript beibehalten

FastComments rendert einen vollständigen Thread serverseitig, den ein Val in einen <noscript>-Block einfügen kann:

Fallback ohne 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>

URL-encode die Parameter. Die serverseitige Version unterstützt anonymes und eingeloggtes Kommentieren, SSO sowie verschachtelte Antworten.

Schritt 2: Verwenden Sie Ihr eigenes Konto

tenantId: "demo" ist ein gemeinsam genutzter öffentlicher Sandbox. Sie funktioniert ohne Anmeldung, weshalb die Beispiele sie verwenden, aber alle anderen, die FastComments ausprobieren, schreiben in dieselben Threads und jeder kann sie moderieren. Wechseln Sie, bevor Sie etwas veröffentlichen, das Ihnen wichtig ist.

Ihre Tenant-ID finden Sie auf der API-Geheimnis-Seite.

Eine Tenant-ID ist öffentlich und gehört in den Browser‑Code. Ein API‑Geheimnis ist das nicht, und nichts auf dieser Seite benötigt eines.

Aus einer Umgebungsvariable lesen

Val Town Vals sind im kostenlosen Tarif öffentlich, sodass ihr Quellcode weltlesbar ist. Bewahren Sie alles Sensible in Umgebungsvariablen auf, lesen Sie sie mit 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";

Das ist auf Val Town aus einem zweiten Grund wichtiger als üblich: Beim Remix eines Vals werden Umgebungsvariablen‑Schlüssel kopiert, aber nicht deren Werte. Ein in einer Umgebungsvariable aufbewahrtes Geheimnis folgt Ihrem Val nicht in das Konto eines anderen. Ein in einer Datei geschriebenes Geheimnis tut es.

Das Zurückfallen auf "demo" lässt den Val für jeden funktionieren, der ihn remixt, bevor er seinen eigenen Tenant festlegt.

EU-Konten

Ein Konto, seine Daten und seine Schlüssel befinden sich in einer Region. Wenn Ihres auf eu.fastcomments.com erstellt wurde, benötigt jede Widget‑Konfiguration ebenfalls region: "eu", und die Skripte werden von cdn-eu.fastcomments.com geladen. Andernfalls lassen Sie beide unverändert.

Kommentaranzahl auf einer Indexseite

Rendern Sie auf einer Indexseite nicht ein Kommentarzahl-Widget pro Zeile. Das wäre eine Anfrage pro Beitrag. Verwenden Sie die Bulk-Zählung, die eine einzige Anfrage für die gesamte Seite benötigt.

Markieren Sie jede Zeile mit der urlId, die ihr Thread verwendet, und laden Sie dann das Bulk-Widget einmal:

Bulk-Kommentarzahlen auf einer Indexseite

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>

Das Skript findet jedes .fast-comments-count-Element auf der Seite und füllt dessen Anzahl aus.

data-fast-comments-url-id muss mit der urlId übereinstimmen, die das Kommentar-Widget dieses Beitrags verwendet. Wenn das Widget den Slug verwendet, verwendet der Marker den Slug. Eine Nichtübereinstimmung zeigt null bei einem Thread an, der Kommentare hat.

Das Skript fragt window.FastCommentsBulkCountConfig ab, daher spielt es keine Rolle, ob Sie die Konfiguration vor oder nach dem Skript-Tag setzen.

Sichere SSO mit std/oauth

Wenn dein Val bereits weiß, wer der Besucher ist, übergibt Secure SSO diese Identität an das Widget, sodass der Nutzer nie eine zweite Anmeldung sieht. Es gibt keine Endpunkte zu bauen und nichts zur Laufzeit aufzurufen: Du berechnest drei Werte serverseitig und übergibst sie in der Widget-Konfiguration.

Val Town bietet Login ohne Konfiguration mit std/oauth, sodass sich der Besucher mit dem Val Town-Konto anmelden kann, das er bereits hat. Tausche das gegen alles aus, was deine App verwendet; der FastComments-Teil ändert sich nicht.

Payload auf dem Server erstellen

Der API-Schlüssel signiert den Payload und darf niemals Browser-Code erreichen. Installiere das SDK von npm, das auf Val Towns Deno-Runtime unverändert funktioniert:

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() gibt { userDataJSONBase64, verificationHash, timestamp } zurück. Diese drei Werte sind alles, was den Browser erreicht. Der Schlüssel signiert sie und wird dann verworfen, sodass nichts auf der Seite einem Leser ermöglicht, einen anderen Benutzer zu fälschen.

Widget-Konfiguration mit 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 fügt GET /auth/login, GET /auth/callback und POST /auth/logout für dich hinzu. Beachte, dass Logout ein POST ist, während das Widget mit einem GET zu logoutURL navigiert, also richte logoutURL auf eine kleine eigene Route, die den POST absendet.

Wenn der Besucher ausgeloggt ist, übergib sso nur mit einer loginURL. Das Widget zeigt dann eine Login-Aufforderung anstelle eines anonymen Kommentarfelds.

Häufige Probleme

timestamp ist in Epoch-Millisekunden, darf nicht in der Zukunft liegen und darf nicht älter als zwei Tage sein. Generiere es auf dem Server in derselben Anfrage, die den Hash berechnet. Die Generierung im Browser ist der klassische Fehler: Der Wert unterscheidet sich vom gehashten Wert und jeder Kommentar wird abgelehnt.

Setze niemals isAdmin oder isModerator vom Identity-Provider. Die Anmeldung mit einem Val Town-Konto sagt nichts darüber aus, wer deine Seite moderieren sollte.

Siehe den SSO-Leitfaden für die vollständige Feldliste, gruppenbeschränkte Threads und Abzeichen.

Empfangen von Webhooks

Ein val ist ein natürlicher Webhook‑Empfänger: Er hat eine stabile URL, kann eine Signatur verifizieren und hat SQLite‑ und Blob‑Speicher integriert.

FastComments signiert ${timestamp}.${body} mit dem API‑Geheimnis Ihres Kontos und sendet zwei Header:

Webhook-Header

Copy

Run

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

Die Methode überträgt das Ereignis: PUT für einen erstellten oder aktualisierten Kommentar, DELETE für einen gelöschten.

Verifizierung einer Zustellung

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);

Zwei Dinge, die Probleme verursachen

Verifiziere die rohen Bytes. Das Parsen des JSON und das erneute Serialisieren ändert die Schlüsselreihenfolge und Leerzeichen, sodass der Hash abweicht und jede Zustellung fehlschlägt, ohne offensichtlichen Grund. Das ist der übliche Grund, warum ein Webhook‑Empfänger „einfach nicht funktioniert“.

Vergleiche in konstanter Zeit. Ein einfaches === auf die Signatur leckt, wie viele Bytes übereinstimmen, was ausreicht, um Byte für Byte zu fälschen.

Ereignisse verarbeiten

Antworte schnell. FastComments versucht es bei einem Nicht‑2xx‑Status erneut, und ein Endpunkt, der ständig fehlschlägt, wird schließlich automatisch deaktiviert. Führe daher die eigentliche Arbeit erst nach der Antwort aus, nicht inline.

Stelle sicher, dass die Verarbeitung anhand der Kommentar‑ID idempotent ist. Ein Retry wird mit einem neuen Zeitstempel erneut signiert, und dieselbe Kommentar‑ID kommt bei Bearbeitung und Löschung erneut, sodass es nichts Stabiles zum Deduplizieren gibt.

Beispielwerte

Vier öffentliche Vals, die Sie remixen können, jede deckt einen Teil dieses Leitfadens ab.

Blog mit Kommentaren (live) ist ein Markdown‑Blog mit einem Thread unter jedem Beitrag und einer Gesamtsumme der Kommentare im Index. Er funktioniert sofort, wenn Sie ihn remixen, und eine Umgebungsvariable verweist auf Ihr eigenes Konto.

SSO‑Demo (live) meldet den Besucher mit seinem Val‑Town‑Konto an und übergibt diese Identität an das Widget, sodass kein zweiter Login nötig ist.

Webhook‑Empfänger (live) prüft die HMAC‑Signatur bei jeder Zustellung und speichert Ereignisse in SQLite. Er hat einen Button, der eine Test‑Payload signiert und an sich selbst liefert, sodass Sie die erfolgreiche Verifizierung beobachten können, bevor Sie einen echten Webhook konfigurieren.

Agent‑Skills (live) ist eine Bibliothek von FastComments‑Agent‑Skills, die das Widget, SSO, die REST‑API, Moderation und die Migration von Disqus abdecken. Remixen Sie sie und der Agent von Val Town, Townie, übernimmt die Skills automatisch aus skills/, sodass Ihr Agent weiß, wie Kommentare eingerichtet werden, ohne dass Sie Dokumentation in den Chat einfügen müssen.

Die gleichen Skills können überall sonst mit npx skills add fastcomments/skills installiert werden.

Domain-Fehler

Sobald Sie den demo-Mandanten ausschalten, kann das Widget mit einem Autorisierungsfehler die Ladeverweigerung zeigen. Das liegt daran, dass FastComments nicht weiß, dass Ihr Konto auf dieser Domain verwendet werden darf.

Gehen Sie hier, um Ihre Site zu Ihrem Konto hinzuzufügen.

Val Town lohnt hier einen zweiten Blick, weil ein Val über mehr als einen Hostnamen erreichbar sein kann:

Jeder HTTP-Val hat einen langen Standard-Endpunkt, <org>--<id>.web.val.run.
Das Beanspruchen einer benutzerdefinierten Subdomain fügt <name>.val.run hinzu.
Eine benutzerdefinierte Domain fügt eine dritte hinzu.
Branches erhalten eigene URLs.

Fügen Sie die Hostnamen hinzu, von denen Sie das Widget tatsächlich bereitstellen. Wenn Sie nach der Einrichtung eine Subdomain beanspruchen, fügen Sie diese ebenfalls hinzu, sonst funktioniert das Widget nur mit der alten URL und schlägt bei der neuen fehl.

Umfragen zu Ihrer Val Town App hinzufügen

Sobald FastComments in Ihrer Val Town‑App ist, können Sie auch Live‑Umfragen direkt in den Kommentaren durchführen. Aktivieren Sie Enable Polls in Ihren Widget‑Anpassungseinstellungen und ein Umfrage‑Button erscheint in der Kommentar‑Symbolleiste. Umfragen unterstützen 2 bis 10 Optionen, die Ergebnisse werden live für alle auf der Seite aktualisiert, und Sie wählen, wer Umfragen erstellen darf und ob das Abstimmen eine Anmeldung erfordert. Es gibt nichts Weiteres zu installieren auf Val Town.

Probieren Sie die Live‑Umfragen‑Demo oder lesen Sie die Umfragen‑Dokumentation, um sie einzurichten.

Val Town Installation

Umfragen

Live-Kommentare zu Val Town Apps hinzufügen

Schritt 1: Widget hinzufügen

Wähle eine urlId, bevor du deployst

Kommentare ohne JavaScript beibehalten

Schritt 2: Verwenden Sie Ihr eigenes Konto

Aus einer Umgebungsvariable lesen

EU-Konten

Kommentaranzahl auf einer Indexseite

Sichere SSO mit std/oauth

Payload auf dem Server erstellen

An das Widget übergeben

Häufige Probleme

Empfangen von Webhooks

Zwei Dinge, die Probleme verursachen

Ereignisse verarbeiten

Beispielwerte

Domain-Fehler

Umfragen zu Ihrer Val Town App hinzufügen

Sprache 🇩🇪 Deutsch

Val Town Installation

Umfragen

Live-Kommentare zu Val Town Apps hinzufügen

Schritt 1: Widget hinzufügen

Wähle eine urlId, bevor du deployst

Kommentare ohne JavaScript beibehalten

Schritt 2: Verwenden Sie Ihr eigenes Konto

Aus einer Umgebungsvariable lesen

EU-Konten

Kommentaranzahl auf einer Indexseite

Sichere SSO mit std/oauth

Payload auf dem Server erstellen

An das Widget übergeben

Häufige Probleme

Empfangen von Webhooks

Zwei Dinge, die Probleme verursachen

Ereignisse verarbeiten

Beispielwerte

Domain-Fehler

Umfragen zu Ihrer Val Town App hinzufügen