Val Town Uygulamalarına Canlı Yorum Ekle

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'ı Ekleyin

Widget bir script etiketi ve bir konteyner elemanından oluşur, bu nedenle val'inizin zaten render ettiği her şeye doğrudan yerleştirilebilir. Bu örnek, Val Town'un HTTP şablonlarının kullandığı Hono JSX'i kullanır.

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;

Yayınlamadan önce bir urlId seçin

urlId, bir yorumun hangi konuya düşeceğini belirler. Ayarlanmamış bırakılırsa, geçerli sayfa URL'sinin temizlenmiş bir sürümüne varsayılan olur — bu da tam olarak Val Town'da değişen şeydir: bir val, bir alt alan adı talep edene kadar uzun bir *.web.val.run ana makine adına sahiptir, dallar kendi URL'lerini alır ve bir sayfayı yeniden adlandırmak yolu değiştirir. Her varyasyon sessizce ayrı ve boş bir konu haline gelir ve belirti "yorumlarım kayboldu" şeklinde okunur.

Yukarıdaki gibi, kontrol ettiğiniz sabit bir değere ayarlayın; örneğin yazı slug'ı veya bir veritabanı kimliği. Ayrıca url değerini de iletin, böylece bildirim e-postaları ve moderasyon araçları gerçek sayfaya bağlantı verebilir.

JavaScript olmadan yorumları korumak

FastComments, tam bir konuyu sunucu tarafında render eder; bir val bunu bir <noscript> bloğuna yerleştirebilir:

JavaScript olmadan yedek

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>

Parametreleri URL-encode edin. Sunucu tarafı sürüm, anonim ve oturum açmış yorum yapmayı, SSO'yu ve iç içe yanıtları destekler.

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ında Yorum Sayıları

Bir dizin sayfasında her satır için ayrı bir yorum sayacı widget'ı oluşturmayın. Bu, her gönderi için bir istek demektir. Tüm sayfa için tek bir istek alan toplu sayacı (bulk count) kullanın.

Her satırı, ilgili thread'in kullandığı urlId ile işaretleyin, ardından toplu widget'ı bir kez yükleyin:

Bir dizin sayfasında toplu yorum sayaç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>

Betik, sayfadaki her .fast-comments-count öğesini bulur ve sayacını doldurur.

data-fast-comments-url-id, ilgili gönderinin yorum widget'ının kullandığı urlId ile eşleşmelidir. Widget slug kullanıyorsa, işaretleyici de slug kullanır. Bir uyuşmazlık, yorumları olan bir thread'de sıfır gösterilmesine neden olur.

Betik, window.FastCommentsBulkCountConfig için yoklama yapar, bu nedenle yapılandırmayı script etiketinden önce veya sonra ayarlamanız fark etmez.

std/oauth ile Güvenli SSO

Val'iniz ziyaretçinin kim olduğunu zaten biliyorsa, Secure SSO bu kimliği widget'a aktarır ve ziyaretçi ikinci bir giriş ekranı görmez. Oluşturulacak bir uç nokta yok ve çalışma zamanında çağrılacak bir şey yok: üç değeri sunucu tarafında hesaplar ve widget yapılandırmasına geçirirsiniz.

Val Town, std/oauth ile sıfır yapılandırmalı giriş sunar, böylece ziyaretçi zaten sahip olduğu Val Town hesabıyla oturum açabilir. Bunu uygulamanızın kullandığı herhangi bir şeyle değiştirebilirsiniz; FastComments tarafı değişmez.

Payload'ı sunucuda oluşturun

API gizli anahtarı payload'ı imzalar ve asla tarayıcı koduna ulaşmamalıdır. SDK'yı npm'den yükleyin; Val Town'un Deno çalışma zamanında olduğu gibi çalışır:

sso.ts

Copy

Run

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

getPayload(), { userDataJSONBase64, verificationHash, timestamp } değerlerini döndürür. Tarayıcıya ulaşan yalnızca bu üç değerdir. Gizli anahtar bunları imzalar ve ardından atılır, böylece sayfadaki hiçbir şey bir okuyucunun farklı bir kullanıcı taklit etmesini sağlamaz.

Widget'a geçirin

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

oauthMiddleware, sizin için GET /auth/login, GET /auth/callback ve POST /auth/logout uç noktalarını ekler. Çıkış işleminin bir POST olduğunu, ancak widget'ın logoutURL adresine GET ile gittiğini unutmayın; bu nedenle logoutURL adresini, POST isteğini gönderen kendi küçük bir rotanıza yönlendirin.

Ziyaretçi oturum açmamışken, yalnızca bir loginURL içeren sso değerini geçirin. Widget daha sonra anonim yorum kutusu yerine bir giriş istemi gösterir.

Ters gidebilecek şeyler

timestamp epoch milisaniyesi olmalıdır, gelecekte olmamalı ve iki günden eski olmamalıdır. Hash'i hesaplayan aynı istekte sunucu tarafında oluşturun. Bunu tarayıcıda oluşturmak klasik hatadır: değer, hash'lenenden farklı olur ve her yorum reddedilir.

Kimlik sağlayıcıdan asla isAdmin veya isModerator ayarlamayın. Bir Val Town hesabıyla oturum açmak, sitenizi kimin yönetmesi gerektiği hakkında hiçbir şey söylemez.

Alan listesinin tamamı, grup korumalı konular ve rozetler için SSO rehberine bakın.

Webhooks 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

Bu rehberin her bir parçasını kapsayan, remixleyebileceğiniz dört herkese açık val.

Blog with comments (canlı), her gönderinin altında bir yorum dizisi ve ana sayfada toplu yorum sayıları bulunan bir Markdown blogudur. Remixlediğiniz anda çalışır ve tek bir ortam değişkeni onu kendi hesabınıza yönlendirir.

SSO demo (canlı), ziyaretçiyi Val Town hesabıyla oturum açar ve bu kimliği widget'a aktarır; böylece ikinci bir giriş gerekmez.

Webhook receiver (canlı), her teslimatta HMAC imzasını doğrular ve olayları SQLite'ta saklar. Bir test yükünü imzalayıp kendine 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 (canlı), widget, SSO, REST API, moderasyon ve Disqus'tan geçiş konularını kapsayan FastComments agent skill'lerinden oluşan bir kütüphanedir. Remixlediğinizde Val Town'un agent'ı Townie, skill'leri skills/ klasöründen otomatik olarak alır; böylece agent'ınız, dokümantasyonu sohbete yapıştırmanıza gerek kalmadan yorumları nasıl kuracağını bilir.

Aynı skill'ler başka her yerde npx skills add fastcomments/skills ile kurulabilir.

Domain Hataları

demo kiracısından çıktıktan sonra, widget bir yetkilendirme hatasıyla yüklenmeyi reddedebilir. Bunun nedeni, FastComments'un hesabınızın o alan adında kullanılmasına izin verilmesi gerektiğini bilmemesidir.

Sitenizi hesabınıza eklemek için buraya gidin.

Val Town burada ikinci bir bakmaya değer, çünkü bir val birden fazla ana bilgisayar adında erişilebilir olabilir:

Her HTTP val'in uzun bir varsayılan uç noktası vardır: <org>--<id>.web.val.run.
Özel bir alt alan adı talep etmek <name>.val.run ekler.
Özel bir alan adı üçüncüsünü ekler.
Branch'ler kendi URL'lerini alır.

Widget'ı gerçekten hangi ana bilgisayar adlarından sunuyorsanız onları ekleyin. Her şeyi ayarladıktan sonra bir alt alan adı talep ederseniz, onu da ekleyin, aksi takdirde widget eski URL'de çalışır ve yenide başarısız olur.

Val Town Uygulamanıza Anketler Ekleyin

FastComments Val Town uygulamanıza kurulduğunda, yorumlarda doğrudan canlı anketler de çalıştırabilirsiniz. Widget özelleştirme ayarlarınızda Enable Polls seçeneğini açın ve yorum araç çubuğunda bir anket düğmesi görünür. Anketler 2 ile 10 seçenek alabilir, sonuçlar sayfadaki herkes için anlık olarak güncellenir ve kimlerin anket oluşturabileceğini ve oy vermenin oturum açmayı gerektirip gerektirmeyeceğini seçebilirsiniz. Val Town’da başka bir şey kurmanıza gerek yok.

Canlı Anket demo'sını deneyin veya ayarlamak için Anket belgelerini okuyun.

Dil 🇹🇷 Türkçe

Val Town Kurulumu

Anketler

Val Town Uygulamalarına Canlı Yorum Ekle

Adım 1: Widget'ı Ekleyin

Yayınlamadan önce bir urlId seçin

JavaScript olmadan yorumları korumak

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

Bir ortam değişkeninden okuyun

AB hesapları

İndeks Sayfasında Yorum Sayıları

std/oauth ile Güvenli SSO

Payload'ı sunucuda oluşturun

Widget'a geçirin

Ters gidebilecek şeyler

Webhooks Alma

Sorun yaratan iki şey

Olayları işleme

Örnek Vals

Domain Hataları

Val Town Uygulamanıza Anketler Ekleyin