Ajouter des commentaires en direct aux applications Val Town

Val Town exécute TypeScript sur Deno, donc un val est un vrai serveur. Cela en fait un bon choix pour FastComments : le widget est une balise script sur la page, et tout ce qui nécessite un secret, comme le SSO sécurisé ou la vérification d’un webhook, peut s’exécuter côté serveur dans le même val.

Ce guide couvre l’ajout du widget de commentaires à un val HTTP, l’affichage du nombre de commentaires sur une page d’index, la connexion des utilisateurs avec le compte Val Town qu’ils possèdent déjà, et la réception des webhooks de commentaires.

Vous n’avez pas besoin de compte pour l’essayer. Les exemples utilisent tenantId: "demo", un bac à sable partagé, et l’étape 2 explique comment passer au vôtre.

Étape 1 : Ajouter le widget

Le widget est une balise script et un élément conteneur, il s’insère donc où que votre val rende déjà. Cet exemple utilise Hono JSX, qui est ce que les modèles HTTP de Val Town utilisent.

Widget de commentaire dans un 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;

Choisissez un urlId avant de déployer

urlId détermine dans quel fil un commentaire atterrit. Laissez‑le non défini et il prendra par défaut une version nettoyée de l’URL de la page actuelle, ce qui correspond exactement à ce qui change sur Val Town : un val possède un long nom d’hôte *.web.val.run jusqu’à ce que vous réclamiez un sous‑domaine, les branches obtiennent leurs propres URL, et le renommage d’une page modifie le chemin. Chaque variation devient silencieusement un fil séparé et vide, et le symptôme apparaît comme « mes commentaires ont disparu ».

Attribuez‑lui quelque chose de stable que vous contrôlez, comme le slug du post ou un identifiant de base de données, comme ci‑dessus. Transmettez également url, afin que les e‑mails de notification et les outils de modération puissent renvoyer à la vraie page.

Conserver les commentaires sans JavaScript

FastComments rend un fil complet côté serveur, qu’un val peut placer dans un bloc <noscript> :

Solution de secours sans 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>

Encodez les paramètres dans l’URL. La version côté serveur prend en charge les commentaires anonymes et connectés, le SSO et les réponses imbriquées.

Étape 2 : Utiliser votre propre compte

tenantId: "demo" est un bac à sable public partagé. Il fonctionne sans inscription, c’est pourquoi les exemples l’utilisent, mais tous les autres utilisateurs de FastComments écrivent dans les mêmes fils et n’importe qui peut les modérer. Changez-le avant de publier quoi que ce soit d’important.

Votre ID de locataire se trouve sur la page des secrets API.

Un ID de locataire est public et doit être présent dans le code du navigateur. Un secret API ne l’est pas, et rien sur cette page n’en a besoin.

Lire depuis une variable d’environnement

Les vals de Val Town sont publiques dans le niveau gratuit, donc leur source est lisible par tous. Conservez tout ce qui est sensible dans des variables d’environnement, lues avec Deno.env.get :

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Seuls les comptes créés sur eu.fastcomments.com définissent cela, à "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

Cela importe plus que d’habitude sur Val Town pour une deuxième raison : remixer un val copie les clés des variables d’environnement, mais pas leurs valeurs. Un secret stocké dans une variable d’environnement ne suit pas votre val dans le compte d’un autre utilisateur. Un secret écrit dans un fichier le fait.

Revenir à "demo" permet au val de fonctionner pour quiconque le remixe avant de définir son propre locataire.

Comptes EU

Un compte, ses données et ses clés résident dans une seule région. Si le vôtre a été créé sur eu.fastcomments.com, chaque configuration de widget doit également contenir region: "eu", et les scripts se chargent depuis cdn-eu.fastcomments.com. Sinon, laissez les deux tels quels.

Nombre de commentaires sur une page d'index

Sur une page d'index, n'affichez pas un widget de compteur de commentaires par ligne. Cela représente une requête par article. Utilisez le comptage en masse, qui ne nécessite qu'une seule requête pour toute la page.

Marquez chaque ligne avec le urlId utilisé par son fil, puis chargez le widget en masse une seule fois :

Comptes de commentaires en masse sur un index

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>

Le script trouve chaque élément .fast-comments-count sur la page et remplit son compteur.

data-fast-comments-url-id doit correspondre au urlId utilisé par le widget de commentaires du post. Si le widget utilise le slug, le marqueur utilise le slug. Un décalage affiche zéro sur un fil qui possède des commentaires.

Le script interroge window.FastCommentsBulkCountConfig, il n'importe donc pas si vous définissez la configuration avant ou après la balise script.

SSO sécurisé avec std/oauth

Si votre val connaît déjà l'identité du visiteur, Secure SSO transmet cette identité au widget afin qu'il ne voie jamais un second écran de connexion. Il n'y a aucun endpoint à construire et rien à appeler à l'exécution : vous calculez trois valeurs côté serveur et les passez dans la configuration du widget.

Val Town propose une connexion sans configuration avec std/oauth, afin que le visiteur puisse se connecter avec le compte Val Town qu'il possède déjà. Remplacez cela par ce que votre application utilise ; la partie FastComments ne change pas.

Construire le payload côté serveur

Le secret d'API signe le payload et ne doit jamais atteindre le code du navigateur. Installez le SDK depuis npm, qui fonctionne tel quel sur le runtime Deno de Val Town :

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() renvoie { userDataJSONBase64, verificationHash, timestamp }. Ces trois valeurs sont tout ce qui atteint le navigateur. Le secret les signe puis est abandonné, de sorte que rien dans la page ne permet à un lecteur de falsifier un autre utilisateur.

Configuration du widget avec 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 ajoute GET /auth/login, GET /auth/callback et POST /auth/logout pour vous. Notez que la déconnexion est un POST, tandis que le widget navigue vers logoutURL avec un GET ; faites donc pointer logoutURL vers une petite route de votre cru qui soumet le POST.

Lorsque le visiteur est déconnecté, passez sso avec uniquement un loginURL. Le widget affiche alors une invite de connexion au lieu d'une boîte de commentaires anonyme.

Ce qui peut mal tourner

timestamp est en millisecondes epoch, ne doit pas être dans le futur et ne doit pas dater de plus de deux jours. Générez-le côté serveur dans la même requête que celle qui calcule le hash. Le générer dans le navigateur est l'erreur classique : la valeur diffère de celle qui a été signée et chaque commentaire est rejeté.

Ne définissez jamais isAdmin ou isModerator à partir du fournisseur d'identité. Se connecter avec un compte Val Town ne dit rien de qui devrait modérer votre site.

Consultez le guide SSO pour la liste complète des champs, les fils restreints par groupe et les badges.

Réception des webhooks

A val est un récepteur de webhook naturel : il possède une URL stable, il peut vérifier une signature, et il intègre SQLite et le stockage de blobs.

FastComments signe ${timestamp}.${body} avec le secret API de votre compte et envoie deux en‑têtes :

En‑têtes du webhook

Copy

Run

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

La méthode transporte l'événement : PUT pour un commentaire créé ou mis à jour, DELETE pour un commentaire supprimé.

Vérification d'une livraison

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // Les octets exacts reçus. N'utilisez PAS c.req.json() et ne les re‑sérialisez pas.
  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 });
  // Rejeter les livraisons obsolètes afin qu'une requête capturée ne puisse pas être rejouée plus tard.
  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 });
  }
  // ...traiter JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Deux choses qui posent problème

Vérifier les octets bruts. Analyser le JSON et le re‑sérialiser modifie l'ordre des clés et les espaces, ainsi le hachage diffère et chaque livraison échoue sans cause évidente. C’est la raison habituelle pour laquelle un récepteur de webhook « ne fonctionne tout simplement pas ».

Comparer en temps constant. Un simple === sur la signature révèle le nombre d'octets correspondants, ce qui suffit à falsifier un octet à la fois.

Gestion des événements

Répondez rapidement. FastComments réessaye en cas de réponse non‑2xx, et un point de terminaison qui échoue continuellement est finalement désactivé automatiquement, il faut donc effectuer le vrai travail après avoir répondu plutôt qu’en ligne.

Rendez cela idempotent sur l'ID du commentaire. Un nouveau essai est re‑signé avec un nouveau horodatage, et le même ID de commentaire arrive de nouveau lors d'une modification ou d'une suppression, il n’y a donc rien de stable sur quoi dédupliquer.

Exemples de Vals

Quatre vals publics que vous pouvez remixer, chacun couvrant une partie de ce guide.

Blog avec commentaires (en direct) est un blog Markdown avec un fil de discussion sous chaque article et des comptes de commentaires en masse sur l'index. Il fonctionne dès que vous le remixer, et une variable d'environnement le pointe vers votre propre compte.

Démo SSO (en direct) connecte le visiteur avec son compte Val Town et transmet cette identité au widget, de sorte qu'il n'y ait pas de deuxième connexion.

Récepteur de webhook (en direct) vérifie la signature HMAC à chaque livraison et stocke les événements dans SQLite. Il possède un bouton qui signe une charge utile de test et la délivre à lui-même, vous permettant de voir la vérification réussir avant de configurer un vrai webhook.

Compétences d'agent (en direct) est une bibliothèque de compétences d'agent FastComments couvrant le widget, le SSO, l'API REST, la modération et la migration depuis Disqus. Remixez-le et l'agent de Val Town, Townie, récupère automatiquement les compétences dans skills/, de sorte que votre agent sache comment configurer les commentaires sans que vous ayez à coller la documentation dans le chat.

Les mêmes compétences s'installent partout ailleurs avec npx skills add fastcomments/skills.

Erreurs de domaine

Une fois que vous désactivez le locataire demo, le widget peut refuser de se charger avec une erreur d'autorisation. Cela est dû au fait que FastComments ne sait pas qu'il doit autoriser votre compte à être utilisé sur ce domaine.

Allez ici pour ajouter votre site à votre compte.

Val Town mérite un second examen ici, car un val peut être accessible à partir de plusieurs noms d'hôte :

Chaque val HTTP possède un point de terminaison par défaut long, <org>--<id>.web.val.run.
Revendiquer un sous-domaine personnalisé ajoute <name>.val.run.
Un domaine personnalisé ajoute un troisième.
Les branches obtiennent leurs propres URL.

Ajoutez les noms d'hôte depuis lesquels vous servez réellement le widget. Si vous revendiquez un sous-domaine après avoir configuré les choses, ajoutez-le également, sinon le widget fonctionnera sur l'ancienne URL et échouera sur la nouvelle.

Ajouter des sondages à votre application Val Town

Une fois que FastComments est installé sur votre application Val Town, vous pouvez également lancer des sondages en direct directement dans les commentaires. Activez Enable Polls dans les paramètres de personnalisation de votre widget et un bouton de sondage apparaît dans la barre d’outils des commentaires. Les sondages acceptent de 2 à 10 options, les résultats se mettent à jour en temps réel pour tous les visiteurs de la page, et vous décidez qui peut créer des sondages et si le vote nécessite une connexion. Il n’y a rien d’autre à installer sur Val Town.

Essayez la démo des sondages en direct ou lisez la documentation des sondages pour les configurer.

Installation de Val Town

Sondages

Ajouter des commentaires en direct aux applications Val Town

Étape 1 : Ajouter le widget

Choisissez un urlId avant de déployer

Conserver les commentaires sans JavaScript

Étape 2 : Utiliser votre propre compte

Lire depuis une variable d’environnement

Comptes EU

Nombre de commentaires sur une page d'index

SSO sécurisé avec std/oauth

Construire le payload côté serveur

Le passer au widget

Ce qui peut mal tourner

Réception des webhooks

Deux choses qui posent problème

Gestion des événements

Exemples de Vals

Erreurs de domaine

Ajouter des sondages à votre application Val Town

Langue 🇫🇷 Français (France)

Installation de Val Town

Sondages

Ajouter des commentaires en direct aux applications Val Town

Étape 1 : Ajouter le widget

Choisissez un urlId avant de déployer

Conserver les commentaires sans JavaScript

Étape 2 : Utiliser votre propre compte

Lire depuis une variable d’environnement

Comptes EU

Nombre de commentaires sur une page d'index

SSO sécurisé avec std/oauth

Construire le payload côté serveur

Le passer au widget

Ce qui peut mal tourner

Réception des webhooks

Deux choses qui posent problème

Gestion des événements

Exemples de Vals

Erreurs de domaine

Ajouter des sondages à votre application Val Town