Adicionar Comentários ao Vivo aos Apps Val Town

Val Town executa TypeScript no Deno, então um val é um servidor real. Isso o torna uma boa escolha para o FastComments: o widget é uma tag script na página, e qualquer coisa que precise de um segredo, como Secure SSO ou verificação de webhook, pode ser executada no lado do servidor no mesmo val.

Este guia cobre a adição do widget de comentários a um val HTTP, a exibição de contagens de comentários em uma página de índice, o login de usuários com a conta Val Town que eles já possuem e o recebimento de webhooks de comentários.

Você não precisa de uma conta para experimentá-lo. Os exemplos usam tenantId: "demo", um sandbox compartilhado, e o Passo 2 cobre a troca para o seu próprio.

Passo 1: Adicionar o Widget

O widget é uma tag de script e um elemento contêiner, portanto ele se insere em qualquer coisa que seu val já renderiza. Este exemplo usa Hono JSX, que é o que os templates HTTP do Val Town utilizam.

Widget de comentário em um 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;

Escolha um urlId antes de enviar

urlId decide em qual thread um comentário será colocado. Se deixá-lo sem definição, ele padrão para uma versão limpa da URL da página atual, que é exatamente o que muda no Val Town: um val tem um hostname longo *.web.val.run até que você reivindique um subdomínio, ramificações recebem suas próprias URLs, e renomear uma página altera o caminho. Cada variação silenciosamente se torna um thread separado e vazio, e o sintoma aparece como "meus comentários desapareceram".

Defina-o para algo estável que você controla, como o slug da postagem ou um ID de banco de dados, como acima. Também passe url, para que os e‑mails de notificação e as ferramentas de moderação possam linkar de volta à página real.

Mantendo comentários sem JavaScript

FastComments renderiza um thread completo no lado do servidor, que um val pode inserir em um bloco <noscript>:

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

Codifique os parâmetros em URL. A versão server‑side suporta comentários anônimos e autenticados, SSO e respostas aninhadas.

Passo 2: Use sua própria conta

tenantId: "demo" é um sandbox público compartilhado. Ele funciona sem cadastro, por isso os exemplos o utilizam, mas todos os outros que experimentam o FastComments escrevem nas mesmas discussões e qualquer pessoa pode moderá‑las. Troque antes de publicar algo que lhe importe.

Seu ID de locatário está na página de segredo da API.

Um ID de locatário é público e deve estar no código do navegador. Um segredo de API não é, e nada nesta página requer um.

Leia-a a partir de uma variável de ambiente

Os vals do Val Town são públicos no plano gratuito, portanto sua origem é legível por todos. Mantenha tudo que for sensível em variáveis de ambiente, lidas com 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";

Isso é ainda mais importante no Val Town por um segundo motivo: remixar um val copia as chaves das variáveis de ambiente, mas não seus valores. Um segredo mantido em uma variável de ambiente não acompanha seu val para a conta de outra pessoa. Um segredo escrito em um arquivo acompanha.

Recuar para "demo" mantém o val funcionando para quem o remixa antes de definir seu próprio locatário.

Contas da UE

Uma conta, seus dados e suas chaves residem em uma única região. Se a sua foi criada em eu.fastcomments.com, toda configuração de widget também precisa de region: "eu", e os scripts são carregados de cdn-eu.fastcomments.com. Caso contrário, deixe ambos como estão.

Contagem de Comentários em uma Página de Índice

Em uma página de índice, não renderize um widget de contagem de comentários por linha. Isso gera uma solicitação por postagem. Use a contagem em massa, que faz uma única solicitação para a página inteira.

Marque cada linha com o urlId que seu thread usa e, em seguida, carregue o widget em massa uma única vez:

Contagens de comentários em massa em um í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>

O script encontra cada elemento .fast-comments-count na página e preenche sua contagem.

data-fast-comments-url-id deve corresponder ao urlId que o widget de comentários da postagem usa. Se o widget usar o slug, o marcador usará o slug. Uma incompatibilidade exibirá zero em um thread que tem comentários.

O script verifica window.FastCommentsBulkCountConfig, portanto não importa se você definir a configuração antes ou depois da tag de script.

SSO Seguro com std/oauth

Se o seu val já sabe quem é o visitante, o Secure SSO entrega essa identidade ao widget para que ele nunca veja um segundo login. Não há endpoints para construir e nada para chamar em tempo de execução: você calcula três valores no servidor e os passa na configuração do widget.

O Val Town oferece login sem configuração com std/oauth, então o visitante pode entrar com a conta Val Town que já possui. Troque isso por qualquer autenticação que seu app use; a parte do FastComments não muda.

Construa o payload no servidor

O segredo da API assina o payload e nunca deve chegar ao código do navegador. Instale o SDK do npm, que funciona no runtime Deno do Val Town como está:

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() retorna { userDataJSONBase64, verificationHash, timestamp }. Esses três valores são tudo o que chega ao navegador. O segredo os assina e é então descartado, então nada na página permite que um leitor falsifique um usuário diferente.

Configuração do widget com 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 adiciona GET /auth/login, GET /auth/callback e POST /auth/logout para você. Note que o logout é um POST, enquanto o widget navega para logoutURL com um GET, então aponte logoutURL para uma pequena rota sua que submeta o POST.

Quando o visitante está deslogado, passe sso com apenas um loginURL. O widget então exibirá um prompt de login em vez de uma caixa de comentários anônima.

Coisas que dão errado

timestamp está em milissegundos de época, não deve estar no futuro e não deve ter mais de dois dias. Gere-o no servidor na mesma requisição que calcula o hash. Gerá-lo no navegador é a falha clássica: o valor difere daquele que foi assinado e todo comentário é rejeitado.

Nunca defina isAdmin ou isModerator a partir do provedor de identidade. Entrar com uma conta Val Town não diz nada sobre quem deve moderar seu site.

Consulte o guia de SSO para a lista completa de campos, threads restritas a grupos e badges.

Recebendo Webhooks

Um val é um receptor de webhook natural: ele tem uma URL estável, pode verificar uma assinatura e inclui SQLite e armazenamento de blobs embutidos.

FastComments assina ${timestamp}.${body} com o segredo da API da sua conta e envia dois cabeçalhos:

Cabeçalhos do webhook

Copy

Run

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

O método transporta o evento: PUT para um comentário criado ou atualizado, DELETE para um comentário excluído.

Verificando uma entrega

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // Os bytes exatos que chegaram. NÃO use c.req.json() e reserialize.
  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 });
  // Rejeitar entregas antigas para que uma solicitação capturada não possa ser reproduzida mais tarde.
  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 });
  }
  // ...tratar JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Duas coisas que dão dor

Verifique os bytes brutos. Analisar o JSON e reserializá‑lo altera a ordem das chaves e os espaços em branco, portanto o hash difere e cada entrega falha sem causa óbvia. Essa é a razão usual de um receptor de webhook "simplesmente não funciona".

Compare em tempo constante. Um simples === na assinatura vaza quantos bytes coincidem, o que é suficiente para forjar um byte de cada vez.

Manipulando eventos

Responda rapidamente. FastComments tenta novamente em caso de resposta não‑2xx, e um endpoint que continua falhando é eventualmente desativado automaticamente, portanto faça o trabalho real após responder, em vez de inline.

Torne esse trabalho idempotente com base no ID do comentário. Uma nova tentativa é assinada novamente com um timestamp novo, e o mesmo ID de comentário chega novamente em edição e exclusão, portanto não há nada estável para desduplicar.

Vals de Exemplo

Quatro vals públicos que você pode remixar, cada um cobrindo uma parte deste guia.

Blog com comentários (live) é um blog em Markdown com um tópico sob cada post e contagens de comentários em massa no índice. Ele funciona no momento em que você o remixar, e uma variável de ambiente aponta para sua própria conta.

Demo SSO (live) autentica o visitante com a conta do Val Town dele e entrega essa identidade ao widget, de modo que não há um segundo login.

Receptor de Webhook (live) verifica a assinatura HMAC em cada entrega e armazena os eventos em SQLite. Ele possui um botão que assina uma carga de teste e a entrega a si mesmo, para que você possa observar a verificação ser bem‑sucedida antes de configurar um webhook real.

Habilidades de agente (live) é uma biblioteca de habilidades de agente FastComments que cobre o widget, SSO, a API REST, moderação e migração do Disqus. Remix‑a e o agente da Val Town, Townie, carrega as habilidades de skills/ automaticamente, de modo que seu agente saiba como integrar comentários sem que você precise colar a documentação no chat.

As mesmas habilidades podem ser instaladas em qualquer outro lugar com npx skills add fastcomments/skills.

Erros de Domínio

Ao desativar o locatário demo, o widget pode recusar o carregamento com um erro de autorização. Isso ocorre porque o FastComments não sabe que deve permitir que sua conta seja usada naquele domínio.

Vá aqui para adicionar seu site à sua conta.

Val Town vale a pena observar novamente aqui, pois um val pode ser acessível por mais de um nome de host:

Todo val HTTP tem um endpoint padrão longo, <org>--<id>.web.val.run.
Reivindicar um subdomínio personalizado adiciona <name>.val.run.
Um domínio personalizado adiciona um terceiro.
Ramos obtêm seus próprios URLs.

Adicione os nomes de host a partir dos quais você realmente serve o widget. Se você reivindicar um subdomínio depois de configurar tudo, adicione‑o também, caso contrário o widget funcionará na URL antiga e falhará na nova.

Adicionar Enquetes ao seu App Val Town

Uma vez que o FastComments está no seu aplicativo Val Town, você também pode executar enquetes ao vivo diretamente nos comentários. Ative Enable Polls nas configurações de personalização do widget e um botão de enquete aparecerá na barra de ferramentas do comentário. As enquetes aceitam de 2 a 10 opções, os resultados são atualizados ao vivo para todos na página, e você escolhe quem pode criar enquetes e se a votação requer login. Não há mais nada para instalar no Val Town.

Experimente a demonstração de Enquetes ao Vivo ou leia a documentação de Enquetes para configurá‑las.

Instalação Val Town

Enquetes

Adicionar Comentários ao Vivo aos Apps Val Town

Passo 1: Adicionar o Widget

Escolha um urlId antes de enviar

Mantendo comentários sem JavaScript

Passo 2: Use sua própria conta

Leia-a a partir de uma variável de ambiente

Contas da UE

Contagem de Comentários em uma Página de Índice

SSO Seguro com std/oauth

Construa o payload no servidor

Passe-o ao widget

Coisas que dão errado

Recebendo Webhooks

Duas coisas que dão dor

Manipulando eventos

Vals de Exemplo

Erros de Domínio

Adicionar Enquetes ao seu App Val Town

Idioma 🇧🇷 Português (Brasil)

Instalação Val Town

Enquetes

Adicionar Comentários ao Vivo aos Apps Val Town

Passo 1: Adicionar o Widget

Escolha um urlId antes de enviar

Mantendo comentários sem JavaScript

Passo 2: Use sua própria conta

Leia-a a partir de uma variável de ambiente

Contas da UE

Contagem de Comentários em uma Página de Índice

SSO Seguro com std/oauth

Construa o payload no servidor

Passe-o ao widget

Coisas que dão errado

Recebendo Webhooks

Duas coisas que dão dor

Manipulando eventos

Vals de Exemplo

Erros de Domínio

Adicionar Enquetes ao seu App Val Town