Добавете живо коментиране към приложенията Val Town

Val Town изпълнява TypeScript върху Deno, така че val е истински сървър. Това го прави подходящ за FastComments: уиджетът е script таг в страницата и всичко, което изисква тайна, като Secure SSO или проверка на webhook, може да се изпълни от сървърната страна в същия val.

Този наръчник обхваща добавянето на уиджета за коментари към HTTP val, показването на броя коментари на индексната страница, влизането на потребителите с акаунта им във Val Town, който вече имат, и получаването на webhook‑и за коментари.

Не ви е необходим акаунт, за да го изпробвате. Примерите използват tenantId: "demo", споделен sandbox, а Стъпка 2 обяснява как да преминете към ваш собствен.

Стъпка 1: Добавете уиджета

Уиджетът е скрипт таг и контейнерен елемент, така че се вмъква в това, което вашият val вече рендира. Този пример използва Hono JSX, което е това, което HTTP шаблоните на Val Town използват.

Коментар уиджет в 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;

Изберете urlId, преди да пуснете

urlId определя в коя нишка попада даден коментар. Ако го оставите непоправен, той по подразбиране е почистена версия на URL адреса на текущата страница, което е точно нещото, което се променя в Val Town: val има дълго *.web.val.run име на хост, докато не заявите поддомейн, клоновете получават собствени URL адреси, а преименуването на страница променя пътя. Всяка вариация тихо става отделна, празна нишка, а симптомът изглежда като „коментарите ми изчезнаха".

Задайте го на нещо стабилно, което контролирате, като slug на публикацията или идентификатор от база данни, както по-горе. Подайте и url, така че имейлите за известия и инструментите за модериране да могат да линкват обратно към реалната страница.

Запазване на коментарите без JavaScript

FastComments рендира пълна нишка от страна на сървъра, която val може да вмъкне в блок <noscript>:

Резервен вариант без 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 encoding. Версията от страна на сървъра поддържа анонимно коментиране и коментиране с влизане, SSO и вложени отговори.

Стъпка 2: Използвайте вашия собствен акаунт

tenantId: "demo" е споделен публичен пясъчник. Работи без регистрация, затова примерите го използват, но всички останали, които използват FastComments, пишат в същите теми и всеки може да ги модерира. Превключете преди да публикувате каквото и да е, което ви е важно.

Вашият tenant ID е на страница за API тайни.

Tenant ID е публичен и принадлежи в кода на браузъра. API тайна не е, и нищо на тази страница не се нуждае от такава.

Прочетете го от променлива на околната среда

Val Town валовете са публични в безплатния слой, затова техният източник е достъпен за всички. Пазете всичко чувствително в променливи на околната среда, прочетете с Deno.env.get:

конфиг.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Само акаунти, създадени на eu.fastcomments.com задават това, на "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

Това е по-важно от обикновено в Val Town поради втора причина: ремиксирането на вал копира ключовете на променливите на околната среда, но не техните стойности. Тайна, съхранена в променлива на околната среда, не следва вашия вал в акаунта на друг човек. Тайна, записана във файл, го прави.

Връщането към "demo" запазва валът работещ за всеки, който го ремиксира, преди да зададе свой собствен tenant.

EU акаунти

Акаунт, неговите данни и ключове живеят в един регион. Ако вашият е създаден на eu.fastcomments.com, всяка конфигурация на уиджет също се нуждае от region: "eu", а скриптовете се зареждат от cdn-eu.fastcomments.com. В противен случай оставете и двете както са.

Брой коментари на индексната страница

На индексна страница не рендерирайте по един widget за брой коментари на ред. Това е една заявка за всяка публикация. Използвайте груповия брой, който изпраща една единствена заявка за цялата страница.

Маркирайте всеки ред с urlId, който използва нишката му, след което заредете груповия widget еднократно:

Групови броячи на коментари в индекс

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>

Скриптът намира всеки елемент .fast-comments-count на страницата и попълва неговия брой.

data-fast-comments-url-id трябва да съвпада с urlId, който използва widget‑ът за коментари на публикацията. Ако widget‑ът използва slug, маркерът използва slug. При несъответствие се показва нула за нишка, която има коментари.

Скриптът проверява наличието на window.FastCommentsBulkCountConfig, затова няма значение дали конфигурацията е зададена преди или след етикета на скрипта.

Сигурен SSO с std/oauth

Ако вашият val вече знае кой е посетителят, Secure SSO предава тази идентичност на уиджета, така че той никога да не вижда второ влизане. Няма нужда от създаване на крайни точки и нищо не се извиква по време на изпълнение: изчислявате три стойности на сървъра и ги предавате в конфигурацията на уиджета.

Val Town предоставя вход без конфигурация с std/oauth, така че посетителят може да влезе с Val Town акаунта, който вече притежава. Заменете това с каквото вашето приложение използва; частта на FastComments остава непроменена.

Създаване на полезния товар на сървъра

Тайната на API подписва полезния товар и никога не трябва да достигне до кода в браузъра. Инсталирайте SDK от npm, което работи директно в Deno средата на 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() връща { userDataJSONBase64, verificationHash, timestamp }. Тези три стойности са всичко, което достига до браузъра. Тайната ги подписва и след това се изхвърля, така че нищо в страницата не позволява на читателя да подправи различен потребител.

Предайте го на уиджета

Конфигурация на уиджет с 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 добавя GET /auth/login, GET /auth/callback и POST /auth/logout за вас. Обърнете внимание, че изходът е POST, докато уиджетът навигира към logoutURL с GET, затова насочете logoutURL към малка ваша рута, която изпраща POST заявка.

Когато посетителят е излязъл, предайте sso само с loginURL. Уиджетът тогава показва прозорец за вход вместо анонимен кутия за коментари.

Неочаквани проблеми

timestamp е епоха в милисекунди, не трябва да бъде в бъдещето и не трябва да е по-стар от два дни. Генерирайте го на сървъра в същата заявка, която изчислява хеша. Генерирането му в браузъра е класическа грешка: стойността се различава от тази, която е била хеширана, и всеки коментар се отхвърля.

Никога не задавайте isAdmin или isModerator от доставчика на идентичност. Влизането с Val Town акаунт не казва нищо за това кой трябва да модерира вашия сайт.

Вижте ръководството за SSO за пълен списък на полетата, нишки с групово ограничение и значки.

Получаване на уебкуки

A val е естествен получател на уебхук: има стабилен URL, може да проверява подпис и има вградено SQLite и съхранение на блобове.

FastComments подписва ${timestamp}.${body} с API тайната на вашия акаунт и изпраща две заглавки:

Заглавки на уебхук

Copy

Run

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

Методът носи събитието: PUT за създаден или актуализиран коментар, DELETE за изтрит.

Проверка на доставката

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // Точните байтове, които пристигнаха. НЕ използвайте c.req.json() и повторно сериализиране.
  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 });
  // Отхвърляне на остарели доставки, за да не може прихванатата заявка да бъде повторно изпълнена по-късно.
  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 });
  }
  // ...обработете JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Две неща, които късат

Проверете суровите байтове. Парсирането на JSON и повторното му сериализиране променя реда на ключовете и whitespace, така че хешът се различава и всяка доставка се проваля без очевидна причина. Това е обичайната причина уебхук получателят „просто не работи“.

Сравнявайте в константно време. Обикновен === върху подписа разкрива колко байта съвпадат, което е достатъчно за фалшифициране по един байт наведнъж.

Обработка на събития

Отговаряйте бързо. FastComments прави повторни опити при не‑2xx отговор, а крайна точка, която продължава да се проваля, в крайна сметка се изключва автоматично, затова извършвайте реалната работа след отговора, а не вмъкната.

Направете тази работа идемпотентна спрямо ID‑то на коментара. При повторен опит подписът се генерира отново с нов timestamp, а същото ID на коментара се получава отново при редактиране и изтриване, така че няма стабилна стойност за дедупликация.

Примерни стойности

Четири публични vals, които можете да ремиксирате, всяка от тях обхваща една част от това ръководство.

Blog with comments (live) е Markdown блог с нишка под всяка публикация и общи броячи на коментари в индекса. Работи веднага след като го ремиксирате, а една променлива на средата го насочва към вашия собствен акаунт.

SSO demo (live) вписва посетителя с техния Val Town акаунт и предава тази идентичност на уиджета, така че няма второ влизане.

Webhook receiver (live) проверява HMAC подписа при всяка доставка и съхранява събития в SQLite. Има бутон, който подписва тестово натоварване и го изпраща към себе си, така че можете да видите проверката да успее преди да конфигурирате истински webhook.

Agent skills (live) е библиотека от FastComments агентски умения, обхващащи уиджета, SSO, REST API, модериране и миграция от Disqus. Ремиксирайте я и агентът на Val Town, Townie, автоматично взема уменията от skills/, така че вашият агент знае как да настрои коментарите без да копирате документацията в чата.

Същите умения се инсталират навсякъде другаде с npx skills add fastcomments/skills.

Грешки в домейна

След като изключите demo наемателя, уиджетът може да откаже да зареди с грешка при оторизация. Това е, защото FastComments не знае, че трябва да разреши вашия акаунт да се използва на този домейн.

Отидете тук, за да добавите сайта си към акаунта си.

Val Town заслужава втори поглед тук, защото val може да бъде достъпен на повече от един hostname:

Всеки HTTP val има дълъг endpoint по подразбиране, <org>--<id>.web.val.run.
Задействането на персонализиран поддомейн добавя <name>.val.run.
А персонализиран домейн добавя трети.
Клоновете (branches) получават собствени URL адреси.

Добавете всички hostnames, от които наистина сервирайте уиджета. Ако заявите поддомейн след като сте настроили всичко, добавете и него, в противен случай уиджетът работи на стария URL и се проваля на новия.

Добавете анкети към вашето приложение Val Town

След като FastComments е в приложението ви Val Town, можете също да провеждате живи анкети директно в коментарите. Включете Enable Polls в настройките за персонализиране на вашия уиджет и бутон за анкета се появява в лентата с инструменти на коментара. Анкетите имат от 2 до 10 опции, резултатите се актуализират в реално време за всички на страницата, и вие избирате кой може да създава анкети и дали гласуването изисква влизане. Няма нищо друго, което да се инсталира в Val Town.

Опитайте демото за живи анкети или прочетете документацията за анкети, за да ги настроите.

Език 🇧🇬 Български

Инсталиране на Val Town

Анкети

Добавете живо коментиране към приложенията Val Town

Стъпка 1: Добавете уиджета

Изберете urlId, преди да пуснете

Запазване на коментарите без JavaScript

Стъпка 2: Използвайте вашия собствен акаунт

Прочетете го от променлива на околната среда

EU акаунти

Брой коментари на индексната страница

Сигурен SSO с std/oauth

Създаване на полезния товар на сървъра

Предайте го на уиджета

Неочаквани проблеми

Получаване на уебкуки

Две неща, които късат

Обработка на събития

Примерни стойности

Грешки в домейна

Добавете анкети към вашето приложение Val Town