テンプレ駆動の og:image 生成サービス。テンプレ(SVG)は各プロジェクトが静的ファイルとして持ち、 このサーバはクエリの値を埋めて PNG を描画します。サーバを持たないクライアントだけのゲームでも、 静的ホスティングにテンプレを 1 ファイル置けば使えます。
注意: 本インスタンスは *.kbn.one 専用です。
ご自身のドメインで利用したい方は kuboon/og.kbn.one から Fork してどうぞ(要 Cloudflare Workers かそれに準ずるもの)。
https://og.kbn.one/share?tmpl=…&score=10&… というシェア URL を作ってユーザーに共有させる。/share を読むと、OG メタ(og:image は /img?…)が返る。/img を読むと、テンプレに値を埋めた PNG が返る。/share を開くと、テンプレの url で組み立てた元のゲーム URL へ移動する。SPA はクローラが JS を実行しないため、ページ自身の og:image を動的に変えられません。/share はその代わりになるページです。
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 として読みます。どちらも最終的に同じ構造に正規化されます。
ルート要素直下の <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>
{
"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 文字列(配列または単体)。 |
width と height(または viewBox)が必要です。そこから縦横比を読みます。{{name}} はテキストにも属性にも書けます。値は XML エスケープして埋め込まれます。<image href="https://…"> は取得して data URI に埋め込みます(2MB まで)。@import によるフォント読込は効きません。フォントは fonts で指定してください。foreignObject は使えません。横長の画像でも、表示される場所によっては中央を正方形に切り出したサムネイルになります。 代表的なのは Facebook のコメント欄や Messenger で、投稿本文なら 1.91:1 の大きなカードになるのに、コメントに貼ると小さな正方形になります。 クローラの User-Agent は投稿とコメントで同じなので、サーバ側では区別できません。WhatsApp や Telegram のサムネイルも同様に正方形です。
そのため横長テンプレは、中央の正方形(1200×630 なら中央の 630×630)にスコアやタイトルなどの要点を収め、左右の帯には背景や装飾だけを置くようにしてください。 こうしておけば、横長で表示される場所ではそのまま、正方形に切り出される場所でも要点が残ります。
Facebook 向けにあえて正方形の画像を返す手は勧めません。投稿本文のカードまで小さなサムネイル表示に落ちてしまい、失うものの方が大きいためです。 正方形の画像を別に用意するのは、WhatsApp や Telegram のように常に正方形になるクローラ向けの最適化と考えてください。
/share はクローラの User-Agent から目標の縦横比を決め、テンプレの画像のうち
目標を超えない範囲で最も近いものを選びます(目標以下が無ければ最も近いもの)。
選んだ画像の比率を ar として /img に渡すので、/img 自体は User-Agent を見ません。
| クローラ | 目標比率 | 備考 |
|---|---|---|
| 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.91 | OG 標準の 1200×630 |
画像が 1 枚しか無いテンプレは常にそれが使われます。twitter:card は選ばれた画像が正方形に近ければ summary、それ以外は summary_large_image になります。
If-None-Match / If-Modified-Since 付きで再検証します。再検証はバックグラウンドで行い、そのリクエストには手元のテンプレで応答します。304 なら本文は流れません。静的ホスティングなら ETag は自動で付きます。Cache-Control: public, max-age=3600 を返します。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 で動かすシミュレータも出す。 |