Agregar Comentarios en Vivo a las Aplicaciones de Val Town

Val Town ejecuta TypeScript en Deno, por lo que un val es un servidor real. Eso lo hace adecuado para FastComments: el widget es una etiqueta script en la página, y cualquier cosa que necesite un secreto, como Secure SSO o la verificación de un webhook, puede ejecutarse del lado del servidor en el mismo val.

Esta guía cubre cómo agregar el widget de comentarios a un val HTTP, mostrar recuentos de comentarios en una página de índice, iniciar sesión de usuarios con la cuenta de Val Town que ya poseen, y recibir webhooks de comentarios.

No necesitas una cuenta para probarlo. Los ejemplos usan tenantId: "demo", un sandbox compartido, y el Paso 2 cubre cómo cambiar a tu propio.

Paso 1: Añadir el Widget

El widget es una etiqueta de script y un elemento contenedor, por lo que se integra en lo que tu val ya renderiza. Este ejemplo usa Hono JSX, que es lo que utilizan las plantillas HTTP de Val Town.

Widget de comentarios en 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;

Elige un urlId antes de publicar

urlId decide en qué hilo aterrizan los comentarios. Si lo dejas sin establecer, se toma por defecto una versión depurada de la URL de la página actual, que es exactamente lo que cambia en Val Town: un val tiene un nombre de host largo *.web.val.run hasta que reclamas un subdominio, las ramas obtienen sus propias URLs y renombrar una página cambia la ruta. Cada variación se convierte silenciosamente en un hilo separado y vacío, y el síntoma se manifiesta como "mis comentarios desaparecieron".

Establécelo en algo estable que tú controles, como el slug de la entrada o un id de base de datos, como en el ejemplo anterior. Pasa también url, para que los correos de notificación y las herramientas de moderación puedan enlazar a la página real.

Mantener los comentarios sin JavaScript

FastComments renderiza un hilo completo del lado del servidor, que un val puede insertar en un bloque <noscript>:

Alternativa sin 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>

Codifica los parámetros en URL. La versión del lado del servidor admite comentarios anónimos y de usuarios autenticados, SSO y respuestas anidadas.

Paso 2: Usa Tu Propia Cuenta

tenantId: "demo" es un sandbox público compartido. Funciona sin registro, por eso los ejemplos lo usan, pero todos los demás que prueban FastComments escriben en los mismos hilos y cualquiera puede moderarlos. Cambia antes de publicar cualquier cosa que te importe.

Tu ID de inquilino está en la página de secretos de API.

Un ID de inquilino es público y pertenece al código del navegador. Un secreto de API no lo es, y nada en esta página necesita uno.

Léelo desde una variable de entorno

Los vals de Val Town son públicos en el nivel gratuito, por lo que su origen es legible por todos. Mantén cualquier cosa sensible en variables de entorno, leídas con 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";

Esto es más importante de lo habitual en Val Town por una segunda razón: remixar un val copia las claves de variables de entorno, pero no sus valores. Un secreto guardado en una variable de entorno no sigue a tu val en la cuenta de otra persona. Un secreto escrito en un archivo sí lo hace.

Revertir a "demo" mantiene el val funcionando para cualquiera que lo remixe antes de establecer su propio inquilino.

Cuentas EU

Una cuenta, sus datos y sus claves viven en una sola región. Si la tuya se creó en eu.fastcomments.com, cada configuración de widget también necesita region: "eu", y los scripts se cargan desde cdn-eu.fastcomments.com. De lo contrario, déjalos tal cual.

Recuento de Comentarios en una Página de Índice

En una página de índice, no renderices un widget de recuento de comentarios por fila. Eso es una solicitud por publicación. Usa el recuento masivo, que realiza una única solicitud para toda la página.

Marca cada fila con el urlId que usa su hilo, y luego carga el widget masivo una sola vez:

Recuentos masivos de comentarios en un índice

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>

El script busca cada elemento .fast-comments-count en la página y completa su recuento.

data-fast-comments-url-id debe coincidir con el urlId que usa el widget de comentarios de esa publicación. Si el widget usa el slug, el marcador usa el slug. Una discrepancia muestra cero en un hilo que tiene comentarios.

El script sondea window.FastCommentsBulkCountConfig, por lo que no importa si configuras la configuración antes o después de la etiqueta del script.

SSO Seguro con std/oauth

Si tu val ya sabe quién es el visitante, Secure SSO le pasa esa identidad al widget para que nunca vea un segundo inicio de sesión. No hay endpoints que construir ni nada que llamar en tiempo de ejecución: calculas tres valores en el servidor y los pasas en la configuración del widget.

Val Town incluye inicio de sesión sin configuración con std/oauth, así que el visitante puede iniciar sesión con la cuenta de Val Town que ya tiene. Cámbialo por el que use tu aplicación; la parte de FastComments no cambia.

Construye el payload en el servidor

El API secret firma el payload y nunca debe llegar al código del navegador. Instala el SDK desde npm, que funciona en el runtime Deno de Val Town tal cual:

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() devuelve { userDataJSONBase64, verificationHash, timestamp }. Esos tres valores son todo lo que llega al navegador. El secret los firma y luego se descarta, así que nada en la página permite a un lector suplantar a otro usuario.

Configuración del widget con 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 añade GET /auth/login, GET /auth/callback y POST /auth/logout por ti. Ten en cuenta que el logout es un POST, mientras que el widget navega a logoutURL con un GET, así que apunta logoutURL a una pequeña ruta propia que envíe el POST.

Cuando el visitante ha cerrado sesión, pasa sso con solo un loginURL. El widget mostrará entonces un mensaje de inicio de sesión en lugar de un cuadro de comentarios anónimo.

Cosas que salen mal

timestamp está en milisegundos de época, no debe estar en el futuro y no debe tener más de dos días de antigüedad. Genéralo en el servidor en la misma petición que calcula el hash. Generarlo en el navegador es el fallo clásico: el valor difiere del que se firmó con el hash y cada comentario es rechazado.

Nunca establezcas isAdmin o isModerator a partir del proveedor de identidad. Iniciar sesión con una cuenta de Val Town no dice nada sobre quién debería moderar tu sitio.

Consulta la guía de SSO para ver la lista completa de campos, los hilos restringidos por grupos y las insignias.

Recibiendo Webhooks

A val es un receptor de webhook natural: tiene una URL estable, puede verificar una firma y tiene SQLite y almacenamiento de blobs incorporados.

FastComments firma ${timestamp}.${body} con el secreto API de tu cuenta y envía dos encabezados:

Encabezados del webhook

Copy

Run

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

El método lleva el evento: PUT para un comentario creado o actualizado, DELETE para uno eliminado.

Verificando una entrega

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

Dos cosas que muerden

Verifica los bytes crudos. Analizar el JSON y volver a serializarlo cambia el orden de las claves y los espacios en blanco, por lo que el hash difiere y cada entrega falla sin una causa evidente. Esta es la razón habitual por la que un receptor de webhook "simplemente no funciona".

Compara en tiempo constante. Un simple === sobre la firma revela cuántos bytes coinciden, lo que es suficiente para falsificar un byte a la vez.

Manejo de eventos

Responde rápidamente. FastComments reintenta en caso de una respuesta que no sea 2xx, y un endpoint que sigue fallando se desactiva automáticamente al final, así que realiza el trabajo real después de responder en lugar de hacerlo en línea.

Haz que ese trabajo sea idempotente respecto al id del comentario. Un reintento se vuelve a firmar con una marca de tiempo nueva, y el mismo id de comentario llega de nuevo en la edición y eliminación, por lo que no hay nada estable sobre lo que deduplicar.

Ejemplo Vals

Cuatro vals públicos que puedes remezclar, cada uno cubriendo una parte de esta guía.

Blog con comentarios (live) es un blog en Markdown con un hilo bajo cada publicación y recuentos de comentarios en bloque en el índice. Funciona en el momento en que lo remezclas, y una variable de entorno lo apunta a tu propia cuenta.

Demo SSO (live) inicia sesión al visitante con su cuenta de Val Town y entrega esa identidad al widget, por lo que no hay un segundo inicio de sesión.

Receptor de Webhook (live) verifica la firma HMAC en cada entrega y almacena los eventos en SQLite. Tiene un botón que firma una carga de prueba y la entrega a sí mismo, para que puedas observar la verificación exitosa antes de configurar un webhook real.

Habilidades de agente (live) es una biblioteca de habilidades de agente de FastComments que cubren el widget, SSO, la API REST, la moderación y la migración desde Disqus. Remezcla esto y el agente de Val Town, Townie, recoge automáticamente las habilidades de skills/, de modo que tu agente sepa cómo integrar los comentarios sin que tengas que pegar la documentación en el chat.

Las mismas habilidades se instalan en cualquier otro lugar con npx skills add fastcomments/skills.

Errores de Dominio

Una vez que desactives el inquilino demo, el widget puede negarse a cargarse con un error de autorización. Esto se debe a que FastComments no sabe que debe permitir que tu cuenta se use en ese dominio.

Ve aquí para agregar tu sitio a tu cuenta.

Val Town merece una segunda mirada aquí, porque un val puede ser accesible en más de un nombre de host:

Cada val HTTP tiene un endpoint predeterminado largo, <org>--<id>.web.val.run.
Reclamar un subdominio personalizado agrega <name>.val.run.
Un dominio personalizado agrega un tercero.
Las ramas obtienen sus propias URLs.

Agrega los nombres de host desde los que realmente sirvas el widget. Si reclamas un subdominio después de configurar todo, agrégalo también, de lo contrario el widget funcionará en la URL antigua y fallará en la nueva.

Agregar Encuestas a Tu Aplicación Val Town

Una vez que FastComments está en tu aplicación Val Town, también puedes ejecutar encuestas en vivo directamente en los comentarios. Activa Enable Polls en la configuración de personalización de tu widget y aparecerá un botón de encuesta en la barra de herramientas de los comentarios. Las encuestas pueden tener de 2 a 10 opciones, los resultados se actualizan en tiempo real para todos en la página, y tú decides quién puede crear encuestas y si la votación requiere iniciar sesión. No hay nada más que instalar en Val Town.

Prueba la demostración de encuestas en vivo o lee la documentación de encuestas para configurarlas.

Instalación de Val Town

Encuestas

Agregar Comentarios en Vivo a las Aplicaciones de Val Town

Paso 1: Añadir el Widget

Elige un urlId antes de publicar

Mantener los comentarios sin JavaScript

Paso 2: Usa Tu Propia Cuenta

Léelo desde una variable de entorno

Cuentas EU

Recuento de Comentarios en una Página de Índice

SSO Seguro con std/oauth

Construye el payload en el servidor

Pásalo al widget

Cosas que salen mal

Recibiendo Webhooks

Dos cosas que muerden

Manejo de eventos

Ejemplo Vals

Errores de Dominio

Agregar Encuestas a Tu Aplicación Val Town

Idioma 🇪🇸 Español

Instalación de Val Town

Encuestas

Agregar Comentarios en Vivo a las Aplicaciones de Val Town

Paso 1: Añadir el Widget

Elige un urlId antes de publicar

Mantener los comentarios sin JavaScript

Paso 2: Usa Tu Propia Cuenta

Léelo desde una variable de entorno

Cuentas EU

Recuento de Comentarios en una Página de Índice

SSO Seguro con std/oauth

Construye el payload en el servidor

Pásalo al widget

Cosas que salen mal

Recibiendo Webhooks

Dos cosas que muerden

Manejo de eventos

Ejemplo Vals

Errores de Dominio

Agregar Encuestas a Tu Aplicación Val Town