Dodajte live komentarisanje u Val Town aplikacije

Val Town извршава TypeScript на Deno, тако да је вал прави сервер. То га чини добрим избором за FastComments: виџет је script ознака на страници, а све што захтева тајну, као што су Secure SSO или верификација вебхука, може да се изврши на серверу у истом валу.

Овај водич обухвата додавање виџета за коментаре у HTTP вал, приказ броја коментара на индекс страници, пријављивање корисника помоћу постојећег Val Town налога, и примање вебхукова за коментаре.

Не треба вам налог да бисте пробали. Примери користе tenantId: "demo", заједничку песочницу, а корак 2 објашњава како да пређете на ваш сопствени.

Korak 1: Dodajte widget

Виџет је script таг и контејнер елемент, тако да се уклапа у било шта ваш val већ приказује. Овај пример користи Hono JSX, који користе Val Town HTTP шаблони.

Коментар виџет у 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 hostname док не заузмете subdomain, гране добијају сопствене URL-ове, а преименовање странице мења путању. Свака варијација тихо постаје посебна, празна нит, а симптом изгледа као „моји коментари су нестали".

Поставите га на нешто стабилно што контролишете, као што је slug објаве или id из базе података, као у примеру изнад. Проследите и 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-енкодирајте параметре. Серверска верзија подржава анонимно и пријављено коментарисање, SSO и угнежђене одговоре.

Korak 2: Koristite svoj nalog

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

Ваш tenant ID је на страници за API тајну.

Tenant ID је јаван и треба да буде у коду у прегледачу. API тајна није, и ништа на овој страници не захтева једну.

Прочитајте га из променљиве окружења

Val Town валови су јавни у бесплатном слоју, тако да је њихов извор читљив свима. Чувајте све осетљиво у променљивим окружења, читајте их помоћу 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";

Ово је важније него обично на Val Town из другог разлога: ремиксовање вал‑а копира кључеве променљивих окружења, али не и њихове вредности. Тајна сачувана у променљивој окружења не прати ваш вал у налог друге особе. Тајна уписана у датотеку то чини.

Враћање на "demo" одржава вал у раду за свакога ко га ремиксује пре него што постави сопствени tenant.

EU налози

Налог, његови подаци и кључеви живе у једној региони. Ако је ваш креиран на eu.fastcomments.com, свака конфигурација виџета такође треба region: "eu", а скрипте се учитавају са cdn-eu.fastcomments.com. У супротном оставите оба нетакнута.

Broj komentara na indeksnoj stranici

На индекс страници, немојте да рендерујете један 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, па није битно да ли постављате конфигурацију пре или после script таг‑а.

Sigurni SSO sa std/oauth

Ако ваш val већ зна ко је посетилац, Secure SSO предаје тај идентитет виџету тако да посетилац никада не види другу пријаву. Нема крајњих тачака за изградњу и нема ничега за позивати у току рада: израчунавате три вредности на серверу и прослеђујете их у конфигурацију виџета.

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

Изградите payload на серверу

API тајна потписује payload и никада не сме да доспе до кода у прегледачу. Инсталирајте SDK са npm-а, који ради на Val Town Deno runtime-у какав јесте:

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 водич за потпуну листу поља, теме ограничене групама и значке.

Primanje webhook-ova

A val је природни прималац вебхука: има стабилну URL адресу, може да верификује потпис, и има уграђену SQLite и blob складиште.

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-а и поновно серијализовање мења редослед кључева и размаке, па хеш буде различит и свака испорука не успе без очигледног разлога. Ово је уобичајен разлог зашто прималац вебхука "само не ради".

Упореди у константном времену. Обичан === над потписом открива колико бајтова се поклапа, што је довољно за фалсификовање једног бајта појединачно.

Обрада догађаја

Одговори брзо. FastComments поново покушава на не‑2xx одговор, а крајња тачка која стално не успева се на крају аутоматски онемогућава, па изврши прави посао након одговора уместо унутар.

Учини да рад буде идемпотентан по ID-ју коментара. Поновни покушај се поново потписује са свежим временским жигом, а исти ID коментара се поново пошиље приликом измене и брисања, тако да нема стабилног атрибута за дедаупликацију.

Primer Vals

Четири јавна vals-а које можете ремиксовати, сваки покрива по један део овог водича.

Блог са коментарима (уживо) је Markdown блог са нитима коментара испод сваког поста и укупним бројевима коментара на индексу. Ради чим га ремиксујете, а једна променљива окружења усмерава га на ваш налог.

SSO демо (уживо) пријављује посетиоца преко његовог Val Town налога и предаје тај идентитет виџету, тако да нема друге пријаве.

Пријемник webhook-ова (уживо) верификује HMAC потпис на свакој достави и чува догађаје у SQLite. Има дугме које потписује тестни payload и доставља га самом себи, тако да можете видети успешну верификацију пре него што конфигуришете стварни webhook.

Agent skills (уживо) је библиотека FastComments agent skills-ова који покривају виџет, SSO, REST API, модерацију и миграцију са Disqus-а. Ремиксујте га и Val Town-ов агент, Townie, аутоматски преузима skills-ове из skills/, тако да ваш агент зна како да повеже коментаре без тога да лепите документацију у ћаскање.

Исти skills-ови се инсталирају било где другде са npx skills add fastcomments/skills.

Greške domena

Када искључите demo tenant, виџет може одбити учитавање са грешком ауторизације. То је зато што FastComments не зна да треба да дозволи ваш налог да се користи на том домену.

Идите овде да додате ваш сајт у ваш налог.

Val Town заслужује поновно разматрање, јер се вал може приступити преко више од једног хост имена:

Сваки HTTP вал има дуги подразумевани крајњи тачку, <org>--<id>.web.val.run.
Потраживање прилагођеног поддомена додаје <name>.val.run.
Прилагођени домен додаје трећи.
Гране добијају своје URL-ове.

Додајте све хост имене са којих заправо служите виџет. Ако затражите поддомен након што сте подесили све, додајте га такође, иначе ће виџет радити на старом URL-у, а не успевати на новом.

Dodajte ankete u vašu Val Town aplikaciju

Када је FastComments на вашој Val Town апликацији, можете такође покретати живе анкете директно у коментарима. Укључите Enable Polls у подешавањима прилагођавања вашег виџета и дугме за анкету ће се појавити у траци са алаткама за коментаре. Анкете подржавају 2 до 10 опција, резултати се ажурирају уживо за све на страници, а ви бираете ко може креирати анкете и да ли гласање захтева пријављивање. Ништа друго није потребно инсталирати на Val Town.

Пробајте демо живих анкета или прочитајте документацију о анкетама да их подесите.

Instalacija Val Town

Ankete

Dodajte live komentarisanje u Val Town aplikacije

Korak 1: Dodajte widget

Изаберите urlId пре објављивања

Задржавање коментара без JavaScript-а

Korak 2: Koristite svoj nalog

Прочитајте га из променљиве окружења

EU налози

Broj komentara na indeksnoj stranici

Sigurni SSO sa std/oauth

Изградите payload на серверу

Проследите га виџету

Ствари које крену наопако

Primanje webhook-ova

Две ствари које гризу

Обрада догађаја

Primer Vals

Greške domena

Dodajte ankete u vašu Val Town aplikaciju

Језик 🇷🇸 Српски

Instalacija Val Town

Ankete

Dodajte live komentarisanje u Val Town aplikacije

Korak 1: Dodajte widget

Изаберите urlId пре објављивања

Задржавање коментара без JavaScript-а

Korak 2: Koristite svoj nalog

Прочитајте га из променљиве окружења

EU налози

Broj komentara na indeksnoj stranici

Sigurni SSO sa std/oauth

Изградите payload на серверу

Проследите га виџету

Ствари које крену наопако

Primanje webhook-ova

Две ствари које гризу

Обрада догађаја

Primer Vals

Greške domena

Dodajte ankete u vašu Val Town aplikaciju