あなたのサーバーを、
TSUMUにつなぐ。

接続先に必要なもの

初期接続先は https://tsumu.tarohida.jp。別サーバーを使う場合は、以下のAPIとDiscord OAuthを実装してください。単にDiscord対応のサイトを入力しても接続できません。

https://games.example.com
https://games.example.com:8443

• HTTPSと、iPhoneが信頼するTLS証明書。HTTPや証明書エラーを回避する設定はありません。
• オリジン単位のURL。ホストと任意のポートを指定します。パス、ユーザー名・パスワード、クエリ、フラグメントは指定できません。末尾の / は除去、スキーム省略時はHTTPSを補完、443番ポートは省略形に正規化します。
• API・画像・音声を同じオリジンで配信。スキーム・ホスト・ポートが一致しないURLや、別オリジンへのHTTPリダイレクトはiPhoneが拒否します。外部CDNのURLをそのまま返さないでください。
• JSONを正しい型で返す。キーの大文字小文字も契約の一部です。数値を文字列にしないでください。エラーをHTTP 200のHTMLで返すことも避けます。

実装するエンドポイント

iPhone 2.2は一覧・残高・設定を /api/game-data から取得します。/api/settings を除くゲームAPIは認証必須。管理API、スキル作成UI、旧Android専用認証はこの接続仕様の対象外です。

Discord認証とセッション

DiscordのアクセストークンをiPhoneへ返すのではありません。本人確認はサーバーが行い、そのサーバー専用のTSUMUセッションを発行します。Discordのclient secretはサーバー内だけに置きます。

1. iPhone → サーバー

   システム認証ブラウザで /auth/login?client=ios&code_challenge=…&client_state=… を開きます。

2. サーバー → Discord → サーバー

   独立したランダムstateを保存し、oauth_state Cookieにも設定。Discordへリダイレクトし、/auth/callback で両方のstateを検証します。

3. サーバー → iPhone

   成功時はHTTP 302で tsumu://auth?code=ONE_TIME_CODE&state=CLIENT_STATE へ。URLにセッショントークンを含めません。

4. iPhone → サーバー

   POST /auth/token にコードとverifierを送信。交換したセッションをKeychainへ保存し、その後のAPIにBearerとして付けます。

1. GET /auth/login

S256固定です。code_challenge_method は送信しません。サーバー側stateは別に生成し、Cookieと紐づけて有効期間300秒・一回限りとします。Cookieは HttpOnly; Secure; SameSite=Lax。通常の成功応答はDiscordへのHTTP 307です。

2. GET /auth/callback

Discordからの code と state を受け、Cookieのstate・サーバー保存のstateを照合して消費します。Discordユーザーを許可できたらTSUMUセッションと一回限りコードを発行します。

HTTP/1.1 302 Found
Location: tsumu://auth?code=ONE_TIME_CODE&state=ORIGINAL_CLIENT_STATE
Cache-Control: no-store
Referrer-Policy: no-referrer

認証拒否は tsumu://auth?error=access_denied&state=…、Discord通信エラーは error=discord_error を返します。state自体が不正な場合はアプリへ戻さず、/login.html?error=invalid_state へリダイレクトします。Web認証は session Cookieを発行して / へ戻します。

3. POST /auth/token

{
  "code": "SERVER_ISSUED_ONE_TIME_CODE",
  "code_verifier": "APP_GENERATED_VERIFIER_AT_LEAST_43_CHARACTERS_LONG"
}

{
  "access_token": "TSUMU_SESSION_TOKEN",
  "token_type": "Bearer",
  "expires_in": 604800
}

code は20〜128文字、code_verifier は43〜128文字で A–Z a–z 0–9 . _ ~ - のみ。一回限りコードは60秒で失効し、正しいverifierと交換できた時だけ消費します。期限切れ・不一致・再使用はHTTP 400。セッションは作成から7日で失効し、refresh tokenはありません。

4. 認証済みAPI / ログアウト

GET /api/game-data HTTP/1.1
Authorization: Bearer TSUMU_SESSION_TOKEN
Accept: application/json

Webは同じセッションをHttpOnly Cookieで送ります。BearerとCookieを同じユーザー検証に接続し、Bearerが不正なときにCookieへフォールバックしないでください。個人データと認証応答には Cache-Control: no-store を付けます。

POST /auth/logout は現在のセッションを失効して {"status":"ok"} を返します。未認証でも同じ応答です。HTTP 401を受けたiPhoneは認証情報を破棄してログイン画面へ戻ります。保存するトークンは接続先ごとに分離されます。

GET /api/game-data

認証後に最初に読むスナップショットです。以下は架空の値による例です。/uploads/sample.png は例示URLで、ファイルを提供しているわけではありません。最小構成はデフォルトプリセットのJSONを参照してください。

{
  "version": 1,
  "user": {
    "discord_id": "demo-user",
    "username": "サンプル",
    "jewels": 100,
    "bestScore": 1200,
    "gamesPlayed": 3
  },
  "tsums": {
    "overrides": {
      "mickey": {
        "name": "サンプルツム",
        "imageUrl": "/uploads/sample.png",
        "skillId": "skill_example",
        "skillName": "タイムプラス"
      }
    }
  },
  "settings": {
    "combo_timeout": 3000,
    "game_duration": 60,
    "fever_duration": 8000,
    "fever_multiplier": 3,
    "min_chain": 3,
    "bomb_chain_threshold": 7,
    "connect_gap_tolerance": 26
  },
  "stage": null,
  "fan": {
    "url": null,
    "color": "#4fc3f7"
  },
  "collection": {
    "mickey": 2
  },
  "rankings": [
    {
      "name": "サンプル",
      "score": 1200,
      "tsumUsed": "mickey",
      "createdAt": 1790000000
    }
  ]
}

トップレベルの8キーは常に返してください。追加の未知フィールドはiPhoneで無視されます。skillCode / skillType が含まれていても、iPhoneはコードを実行せず skillId の有無でカスタムスキルを判定します。

標準ツムIDと typeIndex

名前・画像は変更できますが、IDとインデックスの順序は固定です。ツムの追加種類や基本スコアの変更をこのAPIだけで行うことはできません。

settings の単位と標準値

iPhoneでは安全のため、プレイ時間1〜86400秒、倍率1〜100、チェーン条件2〜50、接続許容間隔0〜300に丸めます。コンボ・フィーバー時間の下限は100msです。互換性を保つには標準値から始めてください。

ランキングとガチャ

POST /api/rankings

{
  "name": "サンプル",
  "score": 1200,
  "tsum_used": "mickey",
  "request_id": "11111111-1111-4111-8111-111111111111"
}

name は1〜20文字、score は0〜2,147,483,647の整数。tsum_used は標準ツムIDまたはnullです。成功時は {"status":"ok"} をHTTP 200で返します。現行実装はクライアント申告のスコアを保存し、サーバーによるプレイ内容の再検証はしません。

POST /api/gacha/pull

{
  "request_id": "22222222-2222-4222-8222-222222222222"
}

{
  "tsumId": "donald",
  "jewelsRemaining": 0
}

1回100ジュエル、標準6種類から均等に選択、重複あり。残高減算・所持追加・処理済みIDの保存は1トランザクションで行います。残高不足はHTTP 400です。

同じユーザーと request_id の再送では二重消費せず、同じ tsumId を返します。jewelsRemaining は再送した時点の現在残高です。未確定IDは結果が判明するまで保存し、新しいガチャ操作にだけ新しいIDを発行してください。

スコア保存だけでジュエルは増えません。ゲストや旧オフライン版の残高・スコアはサーバーへ移行・合算しません。GET /api/user-tsums は {"mickey":2,"donald":1} のような辞書を返します。

一覧の個別取得

GET /api/me はスナップショットの user と同じ形式。GET /api/rankings は rankings と同じ配列で、現行APIはページングなしです。全件をスコア降順で返します。

POST /api/skills/resolve

ツムに skillId を割り当てる場合に必要です。iPhoneは盤面を送信し、サーバーが返すアクションをネイティブで実行します。リクエストにJavaScriptコードを含めず、サーバー側でそのツムに割り当てられたスキルを選びます。

{
  "myTsumIndex": 0,
  "active": [
    {
      "id": "piece-1",
      "typeIndex": 1,
      "body": {
        "x": 120,
        "y": 300
      }
    },
    {
      "id": "piece-2",
      "typeIndex": 0,
      "body": {
        "x": 170,
        "y": 330
      }
    }
  ]
}

active はボムを除く最大100個。id は1〜80文字で配列内で一意、typeIndex / myTsumIndex は0〜5の整数。座標は有限の数値（受理範囲−1000〜2000）です。左上原点、xは右向き、yは下向き。プレイエリアは {x:38,y:170,width:299,height:410}。iPhoneの盤面座標はこの論理座標に変換して送られます。

{
  "actions": [
    {
      "type": "time",
      "value": 3
    },
    {
      "type": "boost",
      "value": 5000
    },
    {
      "type": "clear",
      "ids": [
        "piece-1"
      ]
    }
  ]
}

アクションは最大64個、対象IDはリクエストの盤面に存在するものだけを返します。通信中は両クライアントの盤面・タイマーを停止。成功した時だけゲージを消費し、失敗時は再試行できます。このAPIにはrequest_idによる同一結果の再送保証はありません。

画像・音声の配信

URLは /uploads/your-file.png のようなルート相対URLを推奨します。同一オリジンの絶対URLも利用できます。素材が認証必須なら、APIと同じBearer / Cookieを受け付けてください。HTTP 200で素材のバイト列を返し、ログインHTMLへ転送しないでください。

{
  "id": "stage_example",
  "name": "サンプルステージ",
  "bgUrl": "/uploads/background.png",
  "bgmUrl": "/uploads/music.m4a",
  "seconnectUrl": null,
  "seclearUrl": "/uploads/clear.wav",
  "sebombUrl": null,
  "seskillUrl": null,
  "sefeverUrl": null,
  "secomboUrl": null,
  "seresultUrl": null
}

SEキーは大文字小文字に注意してください。たとえば seclearUrl であって seClearUrl ではありません。未設定はnull。画像はPNG / JPEG、音声はWAV / AAC（M4A）を推奨します。Web用にアップロード可能な形式でも、iOSのUIImage / AVAudioPlayerがデコードできる形式である必要があります。

素材取得に失敗した場合は標準画像・同梱音声にフォールバックし、再読み込み案内を表示します。iPhoneの通信タイムアウトはリクエスト20秒・リソース全体40秒です。ログインURLのブラウザ遷移はこのAPI通信設定とは別です。

困ったときは

{"detail":"Unauthorized"}

通常の detail は文字列ですが、FastAPIの入力検証エラー（422）では配列になります。サーバーのログにclient secret、Bearer、Cookie、認可コード、verifierを記録・公開しないでください。スクリーンショットを共有するときも伏せてください。

公開前のチェックリスト

• HTTPSオリジンを入力し、Discordからアプリへ戻れる。
• stateの不一致・期限切れ・再使用を拒否できる。
• コードの再交換・誤ったverifierを拒否できる。
• BearerとWeb Cookieが同じアカウント・残高を参照する。
• 未認証のゲームAPIはHTMLでなく401 JSONを返す。
• 最小構成のgame-dataで標準ツムのゲームが始まる。
• 同じrequest_idのスコア送信が1件だけ保存される。
• 同じrequest_idのガチャが1回だけ消費される。
• 別オリジンに認証情報を送らず、素材を正しく読み込める。
• ログアウト後、古いトークンがゲームAPIで使えない。

実装に使えるファイル

このページは2026年9月22日時点のiPhone 2.2 / Client API v1の実装に対応しています。OpenAPIの文書バージョンは1.0.0。実際の互換対象は game-data.version = 1 です。管理画面を含むサーバー全APIを公開するSwaggerではなく、クライアント接続に必要な契約を抜き出した文書です。