Val Town アプリにライブコメントを追加

Val Town は Deno 上で TypeScript を実行するため、val は実際のサーバーです。これにより FastComments に適しています：ウィジェットはページ上の script タグで、Secure SSO や webhook の検証など、シークレットが必要な処理は同じ val 内でサーバーサイドとして実行できます。

このガイドでは、HTTP val にコメントウィジェットを追加し、インデックスページにコメント数を表示し、既に持っている Val Town アカウントでユーザーをサインインさせ、コメント webhook を受信する方法を説明します。

試すためにアカウントは必要ありません。例では tenantId: "demo" を使用した共有サンドボックスを利用し、ステップ 2 で自分のものに切り替える方法を説明します。

ステップ 1: ウィジェットを追加

ウィジェットは 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 ホスト名を持ち、ブランチはそれぞれ独自の URL を持ち、ページの名前を変更するとパスが変わります。各バリエーションは静かに別々の空スレッドとなり、結果として「コメントが消えた」と感じます。

上記のように、投稿スラッグやデータベース ID など、あなたが管理できる安定した値に設定してください。また url も渡すことで、通知メールやモデレーションツールが実際のページへリンクできるようになります。

JavaScript なしでコメントを保持する

No-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、そして入れ子返信をサポートしています。

ステップ 2: 自分のアカウントを使用

tenantId: "demo" は共有のパブリックサンドボックスです。サインアップ不要で動作するため、例で使用されていますが、FastComments を試す他のすべてのユーザーは同じスレッドに書き込み、誰でもそれらをモデレートできます。重要なものを公開する前に切り替えてください。

テナント ID は API シークレットページにあります。

テナント ID は公開情報で、ブラウザコードに含めるべきものです。API シークレットはそうではなく、このページの何もそれを必要としません。

環境変数から読み取る

Val Town の val は無料プランで公開されているため、ソースは全世界から読み取れます。機密情報は環境変数に保存し、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 で通常より重要です。理由は二つ目に、val をリミックスすると環境変数のキーはコピーされますが、値はコピーされません。 環境変数に保存されたシークレットは、あなたの val が他人のアカウントに移行しても引き継がれません。ファイルに書かれたシークレットは引き継がれます。

"demo" にフォールバックすることで、独自のテナントを設定する前にリミックスした人でも val が動作し続けます。

EU アカウント

アカウント、そのデータ、キーはすべて同一リージョンに存在します。もし eu.fastcomments.com で作成した場合、すべてのウィジェット設定にも region: "eu" が必要で、スクリプトは cdn-eu.fastcomments.com からロードされます。そうでなければ、両方ともそのままにしてください。

インデックスページのコメント数

インデックスページでは、行ごとにコメントカウントウィジェットを1つずつレンダリングしないでください。これは投稿ごとに1リクエストになります。ページ全体で1回のリクエストで済む一括カウントを使用してください。

urlId（スレッドが使用する）で各行にマークし、まとめてウィジェットを1回だけロードします:

インデックスページの一括コメント数

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 と一致する必要があります。ウィジェットがスラッグを使用する場合、マーカーもスラッグを使用します。不一致の場合、コメントがあるスレッドでも0が表示されます。

スクリプトは window.FastCommentsBulkCountConfig をポーリングするため、設定をスクリプトタグの前に置くか後に置くかは関係ありません。

std/oauth による安全なシングルサインオン

すでに訪問者が誰であるかを val が把握している場合、Secure SSO はその ID をウィジェットに渡すため、訪問者は2回目のログインを目にすることはありません。構築すべきエンドポイントも、実行時に呼び出すべき API もありません。3つの値をサーバー側で計算し、ウィジェットの設定に渡すだけです。

Val Town は std/oauth による設定不要のログインを提供しているため、訪問者は既に持っている Val Town アカウントでサインインできます。これをお使いのアプリで使用している認証方式に差し替えても、FastComments 側は変更不要です。

サーバーでペイロードを構築する

API シークレットはペイロードに署名するためのもので、ブラウザーコードに到達してはいけません。npm から SDK をインストールしてください。Val Town の Deno ランタイムでそのまま動作します:

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 } を返します。ブラウザーに到達するのはこの3つの値だけです。シークレットはこれらに署名した後で破棄されるため、ページ内のどの情報を使っても別のユーザーを偽装することはできません。

ウィジェットに渡す

Widget config with 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 を送信する小さな独自ルートを指定してください。

訪問者がログアウトしている場合は、loginURL のみを含む sso を渡します。するとウィジェットは匿名コメントボックスの代わりにログインプロンプトを表示します。

よくある問題

timestamp はエポックミリ秒であり、未来の時刻であってはならず、2日以上古くてもいけません。ハッシュを計算するのと同じリクエスト内でサーバー側で生成してください。ブラウザー側で生成するのが典型的な失敗パターンです。その場合、値がハッシュ化されたものと異なり、すべてのコメントが拒否されます。

ID プロバイダーから isAdmin や isModerator を設定してはいけません。Val Town アカウントでのサインインは、誰があなたのサイトをモデレートすべきかを示すものではありません。

フィールドの一覧、グループ制限付きスレッド、バッジの詳細については、SSO ガイドを参照してください。

Webhook の受信

A val は自然な Webhook 受信者です。安定した URL を持ち、署名を検証でき、SQLite と BLOB ストレージが組み込まれています。

FastComments は ${timestamp}.${body} にアカウントの API シークレットで署名し、2 つのヘッダーを送信します。

Webhook ヘッダー

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

問題となる2つの点

生バイトを検証する。 JSON を解析して再シリアライズするとキーの順序や空白が変わり、ハッシュが一致せず、明確な原因なしにすべての配信が失敗します。これが Webhook 受信者が「うまく動かない」一般的な理由です。

一定時間で比較する。 署名に対して単純な === を使用すると、何バイト一致したかが漏洩し、1 バイトずつ偽造するのに十分です。

イベントの処理

迅速に応答してください。FastComments は 2xx 以外のステータスで再試行し、失敗が続くエンドポイントは最終的に自動で無効化されます。そのため、インラインで処理せずにレスポンスを返した後に実際の作業を行ってください。

コメント ID に対して冪等に動作させてください。再試行時には新しいタイムスタンプで再署名され、編集や削除時に同じコメント ID が再度届くため、重複排除できる安定した情報はありません。

サンプル Vals

リミックスできる公開valが4つあり、それぞれこのガイドの一部をカバーしています。

コメント付きブログ (ライブ) は、各投稿の下にコメントスレッドがあり、インデックスページにはコメント数が一括表示されるMarkdownブログです。リミックスした瞬間に動作し、環境変数を1つ設定するだけで自分のアカウントに向けられます。

SSOデモ (ライブ) は、訪問者をVal Townアカウントでサインインさせ、そのIDをウィジェットに渡すため、2度目のログインは不要です。

Webhookレシーバー (ライブ) は、すべての配信でHMAC署名を検証し、イベントをSQLiteに保存します。テストペイロードに署名して自分自身に配信するボタンが付いているため、実際のwebhookを設定する前に検証が成功する様子を確認できます。

エージェントスキル (ライブ) は、ウィジェット、SSO、REST API、モデレーション、Disqusからの移行をカバーするFastCommentsエージェントスキルのライブラリです。リミックスすると、Val TownのエージェントであるTownieがskills/から自動的にスキルを取り込むため、ドキュメントをチャットに貼り付けることなく、エージェントがコメントの設定方法を把握できます。

同じスキルはnpx skills add fastcomments/skillsを使って他の環境にもインストールできます。

ドメインエラー

demo テナントを切り替えた後、ウィジェットが認証エラーで読み込みを拒否することがあります。これは、FastComments がそのドメインであなたのアカウントの使用を許可すべきことを認識していないためです。

こちらからアカウントにサイトを追加してください。

Val Town はここで注目に値します。というのも、1つの val が複数のホスト名で到達可能になることがあるからです:

すべての HTTP val には長いデフォルトのエンドポイント <org>--<id>.web.val.run があります。
カスタムサブドメインを取得すると <name>.val.run が追加されます。
カスタムドメインを設定すると3つ目が追加されます。
ブランチにはそれぞれ固有の URL があります。

ウィジェットを実際に配信するホスト名をすべて追加してください。セットアップ後にサブドメインを取得した場合もそれを追加してください。そうしないと、ウィジェットは古い URL では動作しますが、新しい URL では失敗します。

Val Town アプリに投票機能を追加

FastComments が Val Town アプリに導入されると、コメント内でライブ投票も実行できます。ウィジェットのカスタマイズ設定で Enable Polls をオンにすると、コメントツールバーに投票ボタンが表示されます。投票は 2 から 10 の選択肢を取り、結果はページ上の全員にリアルタイムで更新され、投票を作成できるユーザーや投票にログインが必要かどうかを選択できます。Val Town に追加でインストールするものは何もありません。

Live Polls デモを試すまたは投票のドキュメントを読んで設定してください。

言語 🇯🇵 日本語

Val Town インストール

投票

Val Town アプリにライブコメントを追加

ステップ 1: ウィジェットを追加

配信前に urlId を選択

JavaScript なしでコメントを保持する

ステップ 2: 自分のアカウントを使用

環境変数から読み取る

EU アカウント

インデックスページのコメント数

std/oauth による安全なシングルサインオン

サーバーでペイロードを構築する

ウィジェットに渡す

よくある問題

Webhook の受信

問題となる2つの点

イベントの処理

サンプル Vals

ドメインエラー

Val Town アプリに投票機能を追加