Val Town Uygulamalarına Canlı Yorum Ekleme

Val Town Deno üzerinde TypeScript çalıştırır, bu yüzden bir val gerçek bir sunucudur. Bu, FastComments için iyi bir uyum sağlar: widget sayfada bir script etiketi olarak bulunur ve Secure SSO gibi bir gizli bilgiye ya da bir webhook doğrulamaya ihtiyaç duyan her şey aynı val içinde sunucu tarafında çalıştırılabilir.

Bu kılavuz, yorum widget'ını bir HTTP val'ına eklemeyi, bir indeks sayfasında yorum sayılarını göstermeyi, kullanıcıları zaten sahip oldukları Val Town hesabı ile oturum açtırmayı ve yorum webhook'larını almayı kapsar.

Bunu denemek için bir hesaba ihtiyacınız yok. Örnekler tenantId: "demo" adlı paylaşılan bir sandbox kullanır ve Adım 2, kendi sandbox'ınıza geçişi kapsar.

Adım 1: Widget'ı Ekle

The widget is a script tag and a container element, so it drops into whatever your val already renders. This example uses Hono JSX, which is what Val Town's HTTP templates use.

HTTP val içinde yorum widget'ı

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;

Göndermeden önce bir urlId seçin

urlId decides which thread a comment lands in. Leave it unset and it defaults to a cleaned version of the current page URL, which is exactly the thing that changes on Val Town: a val has a long *.web.val.run hostname until you claim a subdomain, branches get their own URLs, and renaming a page changes the path. Each variation silently becomes a separate, empty thread, and the symptom reads as "my comments disappeared".

Set it to something stable that you control, like the post slug or a database id, as above. Pass url too, so notification emails and the moderation tools can link back to the real page.

JavaScript olmadan yorumları koruma

FastComments renders a full thread server-side, which a val can drop into a <noscript> block:

JavaScript'siz geri dönüş

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-encode the parameters. The server-side version supports anonymous and logged-in commenting, SSO, and nested replies.

Adım 2: Kendi Hesabınızı Kullanın

tenantId: "demo" ortak bir halka açık sandbox'tur. Kayıt olmadan çalışır, bu yüzden örneklerde kullanılır, ancak FastComments deneyen diğer herkes aynı konulara yazar ve herkes bunları denetleyebilir. Önemli bir şeyi yayınlamadan önce değiştirin.

Kiracı kimliğiniz API gizli sayfasında bulunur.

Bir kiracı kimliği herkese açıktır ve tarayıcı kodunda bulunur. API gizli anahtarı böyle değildir ve bu sayfadaki hiçbir şey ona ihtiyaç duymaz.

Bir ortam değişkeninden okuyun

Val Town değerleri ücretsiz katmanda herkese açıktır, bu yüzden kaynakları herkes tarafından okunabilir. Hassas tüm verileri ortam değişkenlerinde tutun, Deno.env.get ile okuyun:

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

Bu, Val Town'da ikinci bir neden dolayı genellikle olduğundan daha önemlidir: bir değeri yeniden karıştırmak ortam değişkeni anahtarlarını kopyalar, ancak değerlerini kopyalamaz. Ortam değişkeninde tutulan bir gizli anahtar, değerinizi başka birinin hesabına taşımaz. Bir dosyaya yazılan bir gizli anahtar ise taşır.

"demo"'ya geri dönmek, değeri kendi kiracısını ayarlamadan önce yeniden karıştıran herkes için çalışır durumda tutar.

AB hesapları

Bir hesap, verileri ve anahtarları tek bir bölgede bulunur. Eğer hesabınız eu.fastcomments.com üzerinde oluşturulduysa, her widget yapılandırması da region: "eu" gerektirir ve betikler cdn-eu.fastcomments.com adresinden yüklenir. Aksi takdirde ikisini de olduğu gibi bırakın.

İndeks Sayfasındaki Yorum Sayıları

On an index page, don't render one comment-count widget per row. That is one request per post. Use the bulk count, which takes a single request for the whole page.

Mark each row with the urlId its thread uses, then load the bulk widget once:

Dizin üzerindeki toplu yorum sayıları

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>

The script finds every .fast-comments-count element on the page and fills in its count.

data-fast-comments-url-id has to match the urlId that post's comment widget uses. If the widget uses the slug, the marker uses the slug. A mismatch shows zero on a thread that has comments.

The script polls for window.FastCommentsBulkCountConfig, so it does not matter whether you set the config before or after the script tag.

std/oauth ile Güvenli SSO

If your val already knows who the visitor is, Secure SSO hands that identity to the widget so they never see a second login. There are no endpoints to build and nothing to call at runtime: you compute three values server-side and pass them in the widget config.

Val Town ships zero-config login with std/oauth, so the visitor can sign in with the Val Town account they already have. Swap that for whatever your app uses; the FastComments half does not change.

Build the payload on the server

The API secret signs the payload and must never reach browser code. Install the SDK from npm, which works on Val Town's Deno runtime as-is:

sso.ts

Copy

Run

import { SecureSSOPayloadBuilder } from "npm:fastcomments-sdk/server";
export function buildSSOPayload(user) {
  // id aynı kişi için sabit olmalı, aksi takdirde her oturum açmada yeni bir yorum kimliği alırlar.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // email gereklidir ve benzersiz olmalıdır.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // kullanıcı adı gereklidir ve bir email olamaz.
    username: user.username ?? id,
    displayName: user.username ?? undefined,
    avatar: user.links.profileImageUrl ?? undefined,
  }).getPayload();
}

getPayload() returns { userDataJSONBase64, verificationHash, timestamp }. Those three values are all that reach the browser. The secret signs them and is then dropped, so nothing in the page lets a reader forge a different user.

SSO ile Widget yapılandırması

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" } }),
  };
  // ...bu yapılandırma ile widget'ı render edin
});
export default oauthMiddleware(app.fetch);

oauthMiddleware adds GET /auth/login, GET /auth/callback and POST /auth/logout for you. Note that logout is a POST, while the widget navigates to logoutURL with a GET, so point logoutURL at a small route of your own that submits the POST.

When the visitor is logged out, pass sso with only a loginURL. The widget then shows a login prompt instead of an anonymous comment box.

Things that go wrong

timestamp is epoch milliseconds, must not be in the future, and must not be more than two days old. Generate it on the server in the same request that computes the hash. Generating it in the browser is the classic failure: the value differs from the one that was hashed and every comment is rejected.

Never set isAdmin or isModerator from the identity provider. Signing in with a Val Town account says nothing about who should moderate your site.

See the SSO guide for the full field list, group-gated threads, and badges.

Webhook'ları Alma

A val, doğal bir webhook alıcısıdır: sabit bir URL'ye sahiptir, bir imzayı doğrulayabilir ve SQLite ile blob depolama yerleşiktir.

FastComments, ${timestamp}.${body} ifadesini hesabınızın API gizli anahtarıyla imzalar ve iki başlık gönderir:

Webhook başlıkları

Copy

Run

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

Yöntem olayı taşır: oluşturulan veya güncellenen bir yorum için PUT, silinen bir yorum için DELETE.

Teslimatı doğrulama

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

Sorun yaratan iki şey

Ham baytları doğrulayın. JSON'u ayrıştırıp yeniden serileştirmek, anahtar sırasını ve boşlukları değiştirir, bu yüzden hash farklı olur ve her teslimat belirgin bir neden olmadan başarısız olur. Bu, bir webhook alıcısının “sadece çalışmıyor” olmasının yaygın nedenidir.

Sabit zamanlı karşılaştırma yapın. İmza üzerinde basit bir === ifadesi, kaç baytın eşleştiğini sızdırır ve bu, tek tek bir baytı taklit etmek için yeterlidir.

Olayları işleme

Hızlı yanıt verin. FastComments, 2xx olmayan bir yanıt alındığında yeniden deneme yapar ve sürekli başarısız olan bir uç nokta sonunda otomatik olarak devre dışı bırakılır, bu yüzden gerçek işi yanıt verdikten sonra yapın, satır içinde değil.

Bu işlemi yorum kimliği üzerinde idempotent (tekrarlanabilir) hâle getirin. Bir yeniden deneme, yeni bir zaman damgası ile yeniden imzalanır ve aynı yorum kimliği düzenleme ve silme sırasında tekrar gelir, bu yüzden tutarlı bir şekilde yinelenenleri ayıklamak için sabit bir şey yoktur.

Örnek Vals

Four public vals you can remix, each covering one piece of this guide.

Blog with comments (live) bir Markdown blogudur, her gönderinin altında bir konu başlığı ve indeksde toplu yorum sayıları bulunur. Karıştırdığınız anda çalışır ve bir ortam değişkeni onu kendi hesabınıza yönlendirir.

SSO demo (live) ziyaretçiyi Val Town hesabıyla oturum açtırır ve bu kimliği widget'a verir, böylece ikinci bir oturum açma gerekmez.

Webhook receiver (live) her teslimatta HMAC imzasını doğrular ve olayları SQLite'da saklar. Test bir yük imzalayan ve kendisine teslim eden bir düğmesi vardır, böylece gerçek bir webhook yapılandırmadan önce doğrulamanın başarılı olduğunu izleyebilirsiniz.

Agent skills (live) FastComments ajan becerilerini içeren bir kütüphanedir; widget, SSO, REST API, moderasyon ve Disqus'tan geçişi kapsar. Bunu karıştırdığınızda Val Town'un ajanı Townie, skills/ içindeki becerileri otomatik olarak alır, böylece ajanınız sohbet içine belge yapıştırmadan yorumları nasıl bağlayacağını bilir.

Aynı beceriler, `npx skills add fastcomments/skills` komutuyla başka bir yerde de kurulabilir.

Alan Adı Hataları

Once you switch off the demo tenant, the widget may refuse to load with an authorization error. This is because FastComments doesn't know it's supposed to allow your account to be used on that domain.

Hesabınıza sitenizi eklemek için buraya gidin.

Val Town burada ikinci bir bakışa değer, çünkü bir val birden fazla ana bilgisayar adından erişilebilir:

Her HTTP val, uzun bir varsayılan uç noktaya sahiptir, <org>--<id>.web.val.run.
Özel bir alt alan adı talep etmek <name>.val.run ekler.
Bir özel alan adı üçüncüsünü ekler.
Şubeler kendi URL'lerini alır.

Widget'ı hizmet verdiğiniz tüm ana bilgisayar adlarını ekleyin. Ayarları yaptıktan sonra bir alt alan adı talep ederseniz, onu da ekleyin; aksi takdirde widget eski URL'de çalışır ve yeni URL'de başarısız olur.

Val Town Kurulumu

Val Town Uygulamalarına Canlı Yorum Ekleme

Adım 1: Widget'ı Ekle

Göndermeden önce bir urlId seçin

JavaScript olmadan yorumları koruma

Adım 2: Kendi Hesabınızı Kullanın

Bir ortam değişkeninden okuyun

AB hesapları

İndeks Sayfasındaki Yorum Sayıları

std/oauth ile Güvenli SSO

Build the payload on the server

Pass it to the widget

Things that go wrong

Webhook'ları Alma

Sorun yaratan iki şey

Olayları işleme

Örnek Vals

Aynı beceriler, `npx skills add fastcomments/skills` komutuyla başka bir yerde de kurulabilir.

Alan Adı Hataları

Dil 🇹🇷 Türkçe

Val Town Kurulumu

Val Town Uygulamalarına Canlı Yorum Ekleme

Adım 1: Widget'ı Ekle

Göndermeden önce bir urlId seçin

JavaScript olmadan yorumları koruma

Adım 2: Kendi Hesabınızı Kullanın

Bir ortam değişkeninden okuyun

AB hesapları

İndeks Sayfasındaki Yorum Sayıları

std/oauth ile Güvenli SSO

Build the payload on the server

Pass it to the widget

Things that go wrong

Webhook'ları Alma

Sorun yaratan iki şey

Olayları işleme

Örnek Vals

Aynı beceriler, npx skills add fastcomments/skills komutuyla başka bir yerde de kurulabilir.

Alan Adı Hataları

Aynı beceriler, `npx skills add fastcomments/skills` komutuyla başka bir yerde de kurulabilir.