og.kbn.one

テンプレ駆動の og:image 生成サービス。テンプレ(SVG)は各プロジェクトが静的ファイルとして持ち、 このサーバはクエリの値を埋めて PNG を描画します。サーバを持たないクライアントだけのゲームでも、 静的ホスティングにテンプレを 1 ファイル置けば使えます。

注意: 本インスタンスは *.kbn.one 専用です。 ご自身のドメインで利用したい方は kuboon/og.kbn.one から Fork してどうぞ(要 Cloudflare Workers かそれに準ずるもの)。

仕組み

  1. ゲームは https://og.kbn.one/share?tmpl=…&score=10&… というシェア URL を作ってユーザーに共有させる。
  2. SNS のクローラが /share を読むと、OG メタ(og:image は /img?…)が返る。
  3. クローラが /img を読むと、テンプレに値を埋めた PNG が返る。
  4. 人間が /share を開くと、テンプレの url で組み立てた元のゲーム URL へ移動する。

SPA はクローラが JS を実行しないため、ページ自身の og:image を動的に変えられません。/share はその代わりになるページです。

シェア URL

https://og.kbn.one/share?tmpl=HOST/PATH&name=value&…
tmpl 必須。テンプレの場所を host/path で(スキーム無し。常に https で取得)。tetra-do.kbn.one/og.svg のように書く。
ar 任意。目標の縦横比(1.91、2:1、1200x630)。省略時はクローラの User-Agent から決める。
その他 すべて変数。{{name}} の置換に使う。テンプレの vars にある名前だけが /img に渡る。

ゲーム側の実装例:

// ゲーム側: 自分のクエリに tmpl と画像用の変数を足すだけ
const share = new URL("https://og.kbn.one/share");
for (const [k, v] of new URLSearchParams(location.search)) share.searchParams.set(k, v);
share.searchParams.set("tmpl", "tetra-do.kbn.one/og.json");
share.searchParams.set("score", String(score));
navigator.share?.({ url: share.href }) ?? navigator.clipboard.writeText(share.href);

シェア UI は @kuboon/share-element の <share-buttons> を使うのを推奨します(必須ではありません)。 X、LINE、Threads のボタンと、端末が対応していればネイティブの共有シート、無ければクリップボードへのコピーをまとめて出してくれます。 url 属性に上で組み立てたシェア URL を渡すだけです。

<!-- バンドラ無しなら esm.sh 経由で読み込める(Deno なら deno add jsr:@kuboon/share-element) -->
<script type="module" src="https://esm.sh/jsr/@kuboon/share-element"></script>

<share-buttons id="share"></share-buttons>
<script type="module">
  // 上で組み立てた share (URL) を渡す
  document.getElementById("share").url = share.href;
</script>

操作ログのような長い値も、通常のクエリ値として 1 回だけエンコードすれば済みます。 /share は受け取った値をデコードし、url パターンに埋めるときに 1 回エンコードし直すので、 ゲームが URLSearchParams で読めば元の値がそのまま戻ります。

テンプレの形式

先頭が < なら SVG、{ なら JSON として読みます。どちらも最終的に同じ構造に正規化されます。

1. SVG 単体(画像が 1 枚のとき)

ルート要素直下の <metadata id="og"> に設定 JSON を書きます。CDATA で包めば & や < をエスケープせずに済みます。設定は省略可能で、{{name}} だけ書いた SVG でも動きます。

<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">
  <metadata id="og"><![CDATA[
  {
    "vars": { "score": "0" },
    "fonts": ["Noto Sans JP:700"],
    "url": "https://tetra-do.kbn.one/?date={{date}}&rec={{rec}}",
    "og": {
      "title": "tetra-do {{date}} で {{score}} 点",
      "description": "ブラウザで遊べる落ちものパズル"
    }
  }
  ]]></metadata>
  <rect width="1200" height="630" fill="#f2d4ef"/>
  <text x="600" y="360" font-family="Noto Sans JP" font-weight="700"
        font-size="160" text-anchor="middle">{{score}}</text>
</svg>

2. JSON(縦横比ごとに画像を出し分けるとき)

{
  "vars": { "score": "0" },
  "fonts": ["Noto Sans JP:700"],
  "url": "https://tetra-do.kbn.one/?date={{date}}&rec={{rec}}",
  "og": { "title": "tetra-do {{date}} で {{score}} 点" },
  "images": [
    "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"1200\" height=\"630\">…</svg>",
    "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"800\" height=\"800\">…</svg>"
  ]
}

ビルドスクリプトで SVG ファイルからまとめると楽です:

// build_og.ts — 複数の SVG を 1 つの JSON テンプレにまとめる
const svgs = ["og-wide.svg", "og-square.svg"].map((f) => Deno.readTextFileSync(f));
const tmpl = {
  vars: { score: "0" },
  fonts: ["Noto Sans JP:700"],
  url: "https://tetra-do.kbn.one/?date={{date}}&rec={{rec}}",
  og: { title: "tetra-do {{date}} で {{score}} 点" },
  images: svgs,
};
Deno.writeTextFileSync("public/og.json", JSON.stringify(tmpl));

設定項目

vars 画像描画に使う変数とデフォルト値。省略すると SVG 内の {{name}} から推定し、デフォルトは空文字。ここにある名前だけが /img の URL に載るので、画像に無関係な長い値(操作ログなど)は入れないこと。
fonts Google Fonts のファミリ名の配列。"Noto Sans JP:700" のように :weight を付けられる。SVG に含まれる文字だけをサブセット取得する。先頭のフォントが既定になる。
url 人間を送る元 URL のパターン。{{name}} はシェア URL のクエリ値で置換される(URL エンコード済み)。vars に無い名前も使える。
og title、description、site_name、type。値の中で {{name}} が使える。
player X の Player Card 用。{ "url": "https://同じホスト/player?date={{date}}", "width": 480, "height": 480 }。 指定すると twitter:card=player と twitter:player* を出し、twitter:image は正方形の画像から選ぶ。 url は https で、テンプレと同じホストのものだけ有効({{name}} は URL エンコードして置換)。 プレイヤー側の作り方は x-player-card スキルを参照。/preview の「X の Player Card」で確認できる。
images / image JSON 形式のときの SVG 文字列(配列または単体)。

SVG の書き方

中央の正方形に要点を収める

横長の画像でも、表示される場所によっては中央を正方形に切り出したサムネイルになります。 代表的なのは Facebook のコメント欄や Messenger で、投稿本文なら 1.91:1 の大きなカードになるのに、コメントに貼ると小さな正方形になります。 クローラの User-Agent は投稿とコメントで同じなので、サーバ側では区別できません。WhatsApp や Telegram のサムネイルも同様に正方形です。

そのため横長テンプレは、中央の正方形(1200×630 なら中央の 630×630)にスコアやタイトルなどの要点を収め、左右の帯には背景や装飾だけを置くようにしてください。 こうしておけば、横長で表示される場所ではそのまま、正方形に切り出される場所でも要点が残ります。

Facebook 向けにあえて正方形の画像を返す手は勧めません。投稿本文のカードまで小さなサムネイル表示に落ちてしまい、失うものの方が大きいためです。 正方形の画像を別に用意するのは、WhatsApp や Telegram のように常に正方形になるクローラ向けの最適化と考えてください。

縦横比の出し分け

/share はクローラの User-Agent から目標の縦横比を決め、テンプレの画像のうち 目標を超えない範囲で最も近いものを選びます(目標以下が無ければ最も近いもの)。 選んだ画像の比率を ar として /img に渡すので、/img 自体は User-Agent を見ません。

クローラ目標比率備考
WhatsApp 1 サムネイルが正方形にトリミングされる
Telegram 1 サムネイルが正方形にトリミングされる
Mastodon / Misskey 1.78 カードが 16:9
X (Twitter) 2 summary_large_image は 2:1
Facebook / LINE / Threads 1.91 OG 標準の 1.91:1
Discord 1.91 OG 標準の 1.91:1
Slack 1.91 OG 標準の 1.91:1
Bluesky 1.91 OG 標準の 1.91:1
その他1.91OG 標準の 1200×630

画像が 1 枚しか無いテンプレは常にそれが使われます。twitter:card は選ばれた画像が正方形に近ければ summary、それ以外は summary_large_image になります。

キャッシュと更新

利用できるドメイン

tmpl のホストは次に限られます: *.kbn.one kuboon.github.io

プレビュー

/preview にシェア URL を貼ると、各画像に値を埋めた状態、クローラごとにどの画像が選ばれるか、OG メタ、遷移先を確認できます。 ゲームのページ URL を貼った場合は、その HTML の og:image が https://og.kbn.one/img?tmpl=… ならそこからテンプレと変数を読み取ります。テンプレの URL を直接貼るとデフォルト値で表示します。

エンドポイント

GET /share OG メタ付き HTML。人間には JS で遷移先へ移動。
GET /img PNG。tmpl、ar、画像用変数を受け取る。
GET /preview プレビューア。画像、クローラごとの選択、OG メタに加えて、player があれば X の Player Card の条件確認と、プレイヤーを X と同じ sandbox の iframe で動かすシミュレータも出す。