Xでシェアする

WebアプリやゲームはXで広がります。投稿が効くのは、大きな画像が目に入り、Xアプリの中ですぐにタップして試せて、自分の結果やスコアでまた投稿する、という3つが起きたときです。KUMODeckは、この流れに必要なバックエンドの部品を提供します。アプリもURLもカードもあなたのもので、利用者（API の名前では players = プレイヤー）からKUMODeckは見えません。

どの機能も既定はOFFです。 kumo.config.jsonのshareで、使いたいものだけをONにします（リファレンス）。KUMODeckがあなたのページを書き換えることはありません。カード用のタグは、あなた（かAIエージェント）が<head>に書きます（カード画像とタグ）。

一番早い方法: kumodeck share on#

kumodeck share on          # プロジェクトのフォルダで、最初のデプロイのあとに

投稿に要る機能（share.images（カードのタイトルはindex.htmlの<title>）・share.links・share.tracking）を1つのコマンドでONにし、kumo.config.jsonに書いて両方の環境へ反映します（片方だけなら--env production）。設定済みの文言や色は残ります。そのあと、カード用のタグを1度だけ<head>に書いて（kumodeck share tagsが出します・下を参照）デプロイします。Xでログインは OFF のままです（使うなら別にONにします）。AIエージェントからはMCPのツールshare_enableで同じことができます。

スコアや挑戦をシェアする#

// クリックハンドラーから呼ぶ（投稿ウィンドウはクリックの間に開く必要がある）
shareButton.onclick = () => kumo.share({ kind: 'challenge', score: best, showName: true });

kumo.share()はシェアIDを作り、今のページのURLに?ks=<id>を付けて、Xの投稿画面（https://x.com/intent/tweet。APIキー不要・費用なし）を開きます。scoreはアプリから渡す値なので、受け取る側にはverified: falseと表示されます（改造されたクライアントはどんな数字でも送れるため）。share.linksがOFFでも投稿画面は開きますが、シェアIDは付きません。

受け取る側では次のようにします。

const challenge = await kumo.share.incoming();   // 共有リンクから開かれたページでなければ null
if (challenge?.kind === 'challenge') showBeatThis(challenge.score, challenge.displayName);

カード画像とタグ#

リンク先のページにカード用のタグ（twitter:card、twitter:image、Open Graph）があると、Xは大きな画像を表示します。XのクローラーはJavaScriptを実行しないので、タグはサーバーが返すHTMLに含まれている必要があります。

KUMODeckはページに何も足しません。タグは、あなた（かAIエージェント）がHTMLの<head>に書きます。

kumodeck share tags        # <head> に書く <meta> タグを出す（本番のアプリは --env production）

出たとおりに、共有されるすべてのページ（1ページのアプリならindex.html）の<head>に写し、すでにあるog: / twitter:のタグは置き換えて、デプロイします。画像のURLは変えないでください。AIエージェントには、こう頼めば足ります:「KUMODeckのXのカード用のタグを、このアプリのすべてのページの<head>に入れて。タグはkumodeck share tagsで取って、画像のURLは変えないで」

• 既定のカード（タイトル・色・画像）は、静的なサイトを含めてどこでも出ます。
• シェアごとのカード（?ks=付きのリンクのスコア、挑戦）には、リクエストごとに作るHTMLが要ります。サーバーで画面を作るアプリか自分のサーバーが、そのリクエストでGET /v1/share/tags?ks=<id>（公開用の鍵）を読み、返ってきたタグを<head>に入れます（少なくとも<meta property="og:image" content="https://<あなたのドメイン>/.card/<id>.png">）。KUMODeckでホスティングするサーバーで画面を作るアプリでも、あなたのドメインの/.card.png・/.card/<id>.pngの画像はアプリより先にKUMODeckが返します（独自ドメインでも同じ）。ただしタグはあなたが書きます。KUMODeckはアプリのHTMLを書き換えません。静的なサイトでは、どの共有のリンクも既定のカードになります。リンクそのもの・ページの中の挑戦（kumo.share.incoming()）・投稿ごとの流入はそのまま動きます。
• KUMODeckでホスティングするときは、画像はアプリ自身のドメイン（/.card.png、/.card/<id>.png）から配信されます。独自ドメイン（play.mygame.com）を使うと、画像のURLと共有リンクもそのドメインになり、投稿のどこにもKUMODeckは出ません。

描画されるカードには、share.images.title、色、任意の背景画像が使われます。組み込みのフォントはラテン文字のみです。ほかの文字を描くには、share.images.fontにデプロイ内のフォントファイルを指定します。描画はホスティングのほかの部分と同じく原価で利用料に計上されます。カードは1枚ごとに一度だけ描画され、その後はキャッシュされます。

投稿ごとの流入#

share.trackingをONにすると、誰かが共有リンクを開いたときと、また戻ってきたときをSDKが報告します。保存されるのはシェアIDと日ごとの合計だけです。訪問数、新しい利用者（最初に連れてきたシェアで数える）、利用回数（plays）です。

kumodeck share link "launch post"      # 自分の投稿用の計測付きURL
kumodeck share stats --from 2026-10-01

同じ数値はGET /v1/admin/share/statsでも取得できます（MCP経由でAIエージェントからも使えます）。

Xでログイン#

自分のXアプリを登録し、そのClient IDとClient Secretをダッシュボードのサインイン方法→ Xに貼り付けて、auth.providers.x.enabledをONにします（手順は自分のXアプリ）。Xの同意画面には自分のアプリの名前が出て、XのAPIの利用分はXから自分のアプリに直接請求されます。KUMODeckは請求しません。Xアプリを保存するまでは、Xでログインを始めると409 provider_not_configuredで失敗します。KUMODeckが求めるのはusers.read tweet.readだけで（投稿やDMはしません）、Xのトークンは保存しません。

運営する環境によっては、ダッシュボードで設定なしで使うも選べます。これは自分のアプリの代わりにKUMODeckの共用Xアプリを使うもので、Xの同意画面にはアプリの名前ではなく共用アプリの中立的な名前が表示されます。

Xでログインは無料です。Xはログイン（利用者本人のプロフィール/2/users/meの読み取り）に料金を請求しないため、KUMODeckも回数は数えますが単価は0ドルです。自分のXアプリの場合も、X側の同じ決まりが当てはまります。

利用者のXの名前とアイコンは、利用者本人がONにするまで誰にも表示されません。

await kumo.x.setProfileVisible(true);
// rows: 自分で持っている利用者の一覧（それぞれ playerId を持つ。たとえば Functions から読んだもの）
const withX = await kumo.x.withProfiles(rows);   // row.xProfile = { username, name, avatarUrl } または null

Xのアプリ内ブラウザの中で#

Xアプリでタップしたリンクは、X独自のブラウザで開きます。そのストレージはSafari / Chromeとは別です。

• そこではkumo.share.inAppBrowser()が'x'を返します。ログインは既定でポップアップではなくリダイレクトになります。
• share.inAppBrowserをONにすると、kumo.share.openInBrowser()が、利用者の普段のブラウザで同じゲストのまま続けられるリンク（有効期限10分、1回限り）を返します。ボタンや「リンクをコピー」として表示してください。このリンクは利用者のアカウントそのものなので、投稿しないよう注意を促してください。