#はじめに

このページは、ブラウザで動作する ウェブアプリケーション （Web App）を TapFun に提供するパブリッシャー・開発者向けの接続仕様書です。ウェブアプリケーションは TapFun のページ内に iframe として埋め込まれて動作します。

Windows 向け exe をクラウドゲーミングで提供する場合は クラウドゲーミング向けの仕様書 を参照してください。

#コミュニケーション手段の確立

• 基本はメールで行います。
• 必要に応じて、両社が参加する Slack コネクトチャネルを TapFun 側で発行します。
• Slack コネクトチャネルへの参加ができない場合は、御社のコミュニケーションツールへ参加させていただきます。

#Publisher Console へのログイン

exe のアップデートや各種設定は、テスト環境の Publisher Console（https://<TEST_HOST>/publisher）で行えます。担当者がログイン権限を付与しますので、ログインされる方のメールアドレスをお伝えください。

#リリース内容の調整

動作上の問題の解決の目処が立ちましたら、リリース時期や提供価格を調整します。

#開発中の問題発生時の対応

「操作が反応しない」「意図しない動作がある」といった問題が発生した際は、以下を添えてコミュニケーションチャネルでお知らせください。

• 問題が再現したアプリ名（テスト環境上に同一ゲームが複数ある場合は、アプリ ID など識別できる情報）
• 問題が発生したテスト環境の TapFun ユーザーアカウント（ゲスト状態でのみ発生する場合を除く）
• 発生状況が把握できるスクリーンショット
• スクリーンショットで不足する場合は、再現手順全体の録画
• 問題の再現手順

問題が正常な仕様に起因する場合、双方協議のうえで機能追加や変更を行う場合があります。

#デバッグ

ゲーム実行ページの URL に次のパラメータを付けると、クライアント API のやり取りを確認できます。

#環境

#ホスト名

テスト環境のホスト名と Basic 認証の ID / パスワードは秘匿情報です。このドキュメントには記載していませんので、TapFun の担当者にお問い合わせください。コード例などの <TEST_HOST> はテスト環境のホスト名に置き換えてください。社外や公開の場（公開リポジトリ、公開チャンネルなど）には記載しないでください。

#テスト環境での決済方法

テスト環境でアイテムを購入する際は、次のいずれかを使用してください。

• AmazonPay: 選択すると「マルチペイメントサービス テスト環境」に遷移します。「決済する」を選択すると決済できます。
• テスト用クレジットカード: 番号 4111111111111111、有効期限は未来の任意の年月、セキュリティコードは任意の 3 桁の数字。

#本番でのテストプレイ

リリース前のアプリにアクセスするには、Publisher Console の基本情報でメンテナンスモードを有効にし、「メンテナンス例外メールアドレス」にテストプレイするユーザーのメールアドレスを入力してください。

本番で購入を伴うテストを行う場合は、TapFun 側でアプリごとにテストプレイ用アカウントを登録します。このアカウントには対象アプリでのみ使える TapFun クレジットが付与されます。テストプレイ用アカウントの購入は即座に取り消され、売上から相殺されます。

#Publisher Console

#基本情報

#詳細情報（紹介ページ）

「詳細情報」タブでは、TapFun 上のゲーム紹介ページに表示する内容を編集します。

操作説明画像とスクリーンショット画像は、ドラッグで並べ替えられます。削除するときは、画像をクリックして削除マークを付けたあと、「追加アップロード & 順序を保存」を押すと反映されます。

#ゲームの起動

アプリ画面上部の「アプリページ」から、次のオプションを付けてゲームを起動できます（デバッグ）。リリース前のアプリには「非公開状態」と表示されます。

#そのほかのタブ

#起動と認証

#動作概要

• ウェブアプリケーションは TapFun のページが親フレームとなり、Publisher Console の 起動 URL で iframe として埋め込まれて開かれます。
• 起動 URL のプレースホルダ（{token} / {host} / {appId}）は起動時に値へ置き換えられます。
• TapFun 親フレームとの通信は クライアント API（postMessage）で行います。

起動 URL の例:

https://game.example.com/play?host={host}&token={token}&appId={appId}

#ユーザー認証 / TapFun ユーザー ID の取得

1. 起動 URL の {token} に渡された値を、ブラウザからパブリッシャー様のゲームサーバーへ送ります。
2. ゲームサーバーから POST /api/v1/create_session を呼ぶと、TapFun ユーザー ID が返ります。
3. {token} の有効期限はテスト環境で 24 時間、本番環境で 180 秒です。有効期限内は繰り返し使用できます。

curl https://<TEST_HOST>/api/v1/create_session -X POST \
  -H "Authorization: Bearer BEARER_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_HERE"}'
# {"result":"success","userId":"PLYRABCDEFGHIJKLMNOP123456789APPGRP"}

Bearer token はサーバー側でのみ扱い、ブラウザに渡さないでください。

#クライアント API

ウェブアプリケーションと、親フレームである TapFun との通信用 API です。送信データはユーザーのブラウザ上でやり取りされるため、秘匿情報は含めないでください。

#通信仕様

TapFun はメッセージの送信元が埋め込んだ iframe であること、およびそのオリジンが起動 URL のオリジンであることを確認します。受信側でも event.origin が https://{host} であることを確認してください。

const params = new URLSearchParams(location.search);
const tapfunOrigin = 'https://' + params.get('host'); // 起動 URL に {host} を含めておく

function send(data) {
  window.parent.postMessage(JSON.stringify(data), tapfunOrigin);
}

window.addEventListener('message', (event) => {
  if (event.origin !== tapfunOrigin) return;
  const data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
  console.log('from TapFun', data);
});

send({ req: 'getPlayerEnvironment' });

#purchaseItem

アイテム購入の確認ダイアログを表示し、決済を行います。決済が成功すると、TapFun からパブリッシャー様のゲームサーバーへ Callback API で通知します。アイテムの付与は Callback を受けたゲームサーバー側で行ってください。

リクエスト例:

{
  "req": "purchaseItem",
  "tran": "UNIQUE_TRANSACTION_ID_HERE",
  "code": "code_type01",
  "item": "item_type01",
  "img": "https://example.com/img/item.png",
  "amount": 500,
  "name": "300ジェム",
  "ret": "/purchaseReturn?host={host}&token={token}&appId={appId}#anchor",
  "sig": "SIGNATURE_HASH_HERE"
}

#署名の作り方

次の順に値を & で結合した文字列を、Publisher Console の sigKey をキーとして HMAC-SHA256 でハッシュ化し、16 進数（小文字）の文字列にした値です。

tapfunUserId&tran&code&item&amount&name&img&note&ret

• tapfunUserId はリクエストパラメータには不要ですが、署名用の文字列には必要です。
• item / img / note / ret などが空の場合も省略せず、& を連続させます。例: PLYR123456DBG&ABCD&gem300&&500&ジェム300&&&
• 署名はパブリッシャー様のゲームサーバーで計算し、sigKey をブラウザに渡さないでください。

// Node.js（ゲームサーバー側）
import { createHmac } from 'node:crypto';

function purchaseSig(sigKey, p) {
  const s = [p.tapfunUserId, p.tran, p.code, p.item ?? '', p.amount, p.name, p.img ?? '', p.note ?? '', p.ret ?? ''].join('&');
  return createHmac('sha256', sigKey).update(s).digest('hex');
}

#レスポンス通知

すべての通知に req（purchaseItem）、code（リクエストした code）、tran（リクエストした tran）が付きます。

• 過去の購入と同じ tran の場合は、購入前のチェックでエラーダイアログを表示します。タイミングによって購入前のチェックを通過した場合も、購入ボタンを押した後に同じ tran を検出するとエラーダイアログを表示します。
• 同一 tran のエラーを再現するには、TapFun のゲーム実行ページの URL に ?purchasableCheck=0 を付けて開き、ゲームから同じ tran で purchaseItem を呼び出してください。購入前のチェックをスキップして購入ボタンを押せるようになります。
• ブラウザが受け取ったリクエストの内容は、ブラウザのデベロッパーツールのコンソールで確認できます。

#getPlayerEnvironment

プレイヤーの環境を取得します。

レスポンス通知:

#getOneTimeData

TapFun のページ URL のクエリストリング onetime の値を一度だけ取得します。ディープリンクなどに使えます。リクエストを受けると URL 上の onetime は消えます。

レスポンス通知:

例: URL が https://tapfun.co.jp/p/dummy/play?onetime=abcdefg の場合

// 1 回目
{ "from": "getOneTimeData", "onetime": "abcdefg" }
// 2 回目（URL から onetime が消えているため）
{ "from": "getOneTimeData", "onetime": "" }

値をエンコードした URL の場合:

// ?onetime=page%3Dqrcode%26code%3Daaaa
{ "from": "getOneTimeData", "onetime": "page=qrcode&code=aaaa" }
// ?onetime=abc%0D%0Adef%0D%0Aghi
{ "from": "getOneTimeData", "onetime": "abc\r\ndef\r\nghi" }

#proposeAuthentication

ユーザーにログインを促します。ゲスト状態の場合は新規登録 / ログインモーダルを表示します。

レスポンス通知:

#openAccount

アカウントページを開きます。ゲスト状態の場合は新規登録 / ログインモーダルを表示します。

レスポンス通知: なし

#reboot

ゲームを再起動します。プレイヤーが TapFun UI 上の再起動アイコンをタップしたときと同じ動作です。

レスポンス通知: なし

#consoleLog

TapFun のログ表示領域にログを追加します。ブラウザのデベロッパーツールのコンソールにも出力されます。

レスポンス通知: なし

#Callback API（アイテム購入完了通知）

purchaseItem の決済が成功すると、TapFun サーバーからパブリッシャー様のゲームサーバーへ購入内容を通知します。

#仕様

リクエストヘッダー:

// Node.js（Express）での署名の検証例
import { createHmac, timingSafeEqual } from 'node:crypto';

app.post('/tapfun/callback', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = createHmac('sha256', SIG_KEY).update(req.body).digest('hex');
  const actual = req.get('X-TapFun-Signature') || '';
  if (expected.length !== actual.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(actual))) {
    return res.status(400).json({ result: 'error' }); // success / reject 以外はリトライされる
  }
  const purchase = JSON.parse(req.body);
  // purchase.tran で冪等に処理し、アイテムを付与する
  res.json({ result: 'success' });
});

#通知とリトライ

• 初回の失敗と復旧を、Publisher Console の「callback Notice Email」と「callback Notice Webhook URL」に通知します。
• ユーザーの購入時は、失敗またはタイムアウトの後 0.5 秒待って 3 回リトライします。3 回とも失敗すると、ユーザーに失敗のモーダルを表示します。
• その後は次の間隔でリトライします。
  • 10 分後まで: 1 分ごと
  • 60 分後まで: 10 分ごと
  • 24 時間後まで: 1 時間ごと
  • 14 日後まで: 1 日ごと
  • それ以降は Publisher Console から手動で再実行する必要があります。
• Callback が完了していない購入がある間は、同じ code の商品を続けて購入できません。

#リクエスト

{
  "req": "purchaseItem",
  "event": "purchaseItem",
  "result": "success",
  "key": "01HRC7QZV1GVT0WX9G6EKSYCAS",
  "appId": 1,
  "userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
  "publisherUserId": null,
  "fromRegisterDevice": "PC",
  "purchaseDevice": "PC",
  "salesDistinction": "Publisher",
  "tran": "abcdef123456",
  "code": "gem300",
  "item": "itemGem300",
  "amount": 500,
  "name": "300ジェム",
  "img": "https://example.com/img/item.png",
  "note": null,
  "createdAt": "2024-03-06T06:37:22.000Z"
}

#レスポンス

ゲームサーバーは、JSON の result に success か reject を返してください。それ以外の場合、TapFun はリトライします。HTTP ステータスは判定に使いませんが、200 を推奨します。リダイレクトには対応していません。

// 購入成功
{ "result": "success" }
// 購入拒否
{ "result": "reject" }

• success の場合、正式に売上が計上されます。
• reject の場合、購入は取り消され、ユーザーのウォレット残高は減りません（ユーザーの利用履歴には購入と返金が記載されます）。
• ゲームサーバー側で同じ tran を検出した場合は、既存の購入の結果を返してください（冪等性の確保）。例えば、同じ tran の既存の購入が成功していれば success を返します。

#Web API

パブリッシャー様のサーバーから呼び出す HTTP API です。Bearer token はサーバー側でのみ扱い、ブラウザに渡さないでください。

#共通仕様

#認証

HTTP ヘッダー Authorization: Bearer <アプリID>_<APIキー>（Publisher Console の Bearer token）で認証します。

Authorization: Bearer 123_NWU0MjlkY2ViYTVkOTdiYjIwNThmZTkxMDMzYWM4Y2JmNGUyMTQ0Ng

認証失敗時は HTTP 403 で次を返します。

{"error":"no authorization"}

#POST /api/v1/create_session

起動 URL の {token} から TapFun ユーザー ID を取得します（ユーザー認証）。認証: 必要。

// 成功
{ "result": "success", "userId": "TapFunユーザーID" }
// 失敗（400）: トークンが無い
{ "result": "failure", "message": "token is missing" }
// 失敗（400）: トークンが不正
{ "result": "failure", "message": "token is invalid" }

#GET /api/v1/purchases

購入履歴を取得します。結果は新しい順に並びます。Callback を取りこぼした購入の確認などに使えます。認証: 必要。

// 成功
{
  "nextKey": "Purchase01HE2R3JV6Y2NEGRMS4KZQB858",   // 続きが無い場合は null
  "result": [
    {
      "key": "Purchase01HE2R3JV6Y2NEGRMS4KZQB861",
      "appId": 1,
      "userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
      "tran": "abcdef123456",
      "code": "abcdef123456",
      "item": "abcdef123456",
      "amount": 500,
      "name": "300ジェム",
      "img": null,
      "callbackSuccess": false,
      "createdAt": "2024-03-06T06:37:22.000Z"
    }
  ]
}

• callbackSuccess は Callback が成功したかどうかです。
• Publisher Console の「purchases API 互換モード」が有効な場合、userId の末尾（suffix）が数文字短い形式になります。通常は無効にしてください。
• 失敗のレスポンスはありません（該当が無い場合は空の配列）。

#POST /api/v1/photos

TapFun フォトストレージに画像を保存します。ユーザーは TapFun 上で、ゲームから保存された画像を閲覧・ダウンロードできます。認証: 必要。

制約:

• 最大保存枚数: 1,000 枚（超えた場合は古いものから自動削除）
• 最大容量: 1 枚あたり 10 MB（全体の容量制限はありません）
• 最大の高さ・幅: 12,000 ピクセル
• 最大画像サイズ: 100M ピクセル（例: 10,000 × 10,000）
• 連続呼び出しの待機時間・呼び出し回数の制限: なし

curl -F "file=@sample.jpg;type=image/jpeg" \
  -H "Authorization: Bearer 1_8an4dAfsIyEEvBbaKxd55P2Wgf" \
  "https://<TEST_HOST>/api/v1/photos?userId=PLYR01JY39A09EE40YQZRHWTT9EM1VDBG"

// 成功
{ "result": "success" }
// 失敗（404）: ユーザー ID が無い
{ "result": "failure", "message": "userId is not found" }
// 失敗（400）: その他（file が無い、大きすぎる、形式が不正など）
{ "result": "failure", "message": "other problems." }

#GET /api/v1/leaderboard/entries

リーダーボードのエントリー一覧を取得します。認証: 必要。

// 成功
{
  "result": "success",
  "entries": [
    {
      "position": 1,
      "userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
      "userName": "ユーザー名",          // UTF-8、絵文字不可、1〜12 文字
      "score": 12345,
      "note": "追加情報",                // 最大 8192 文字
      "createdAt": "2025-09-24T00:00:00.000Z",
      "updatedAt": "2025-09-24T00:00:00.000Z"
    }
  ]
}
// 失敗（404）: ユーザー ID が無い
{ "result": "failure", "message": "userId is not found" }
// 失敗（400）: その他
{ "result": "failure", "message": "other problems." }

#POST /api/v1/leaderboard/entries

リーダーボードのエントリーを作成・更新します。既存のスコア値以下（同値を含む）の場合は更新しません。リーダーボードは name ごとに自動で作られます。認証: 必要。

// 成功
{ "result": "success" }
// 失敗（404）: ユーザー ID が無い
{ "result": "failure", "message": "userId is not found" }
// 失敗（400）: その他
{ "result": "failure", "message": "other problems." }

#POST /api/v1/leaderboard/entries/delete

リーダーボードのエントリーを削除します。エントリーが無い場合も成功を返します。認証: 必要。

// 成功
{ "result": "success" }
// 失敗（404）: ユーザー ID が無い
{ "result": "failure", "message": "userId is not found" }
// 失敗（400）: その他
{ "result": "failure", "message": "other problems." }

#用語

#TapFun ユーザー ID

• ユーザーを特定する最大 64 桁のユニーク ID です。アプリごとに発行されます。
• 文字種は 0-9, a-z, A-Z です。
• 形式は PLYR + ULID + アプリごとの suffix（3〜7 文字。例: DBG, XENO, MOCODVLP）です。

#アプリ ID

アプリを特定する unsigned int 型の ID です。

#API キー

アプリごとに発行される 26 桁の文字列です。文字種は 0-9, A-Z です。

#Publisher Console

パブリッシャー様向けの管理画面です。アプリの設定、紹介ページ、売上の確認などを行います。テスト環境と本番環境で別々にあり、ログインできる方は TapFun が登録します。

#紹介ページ

TapFun 上のゲームのページです（https://tapfun.co.jp/p/<アプリ>）。ゲームのプレイ画面は https://tapfun.co.jp/p/<アプリ>/play です。内容は Publisher Console の詳細情報で編集します。

#ゲスト

TapFun にログインしていない状態のプレイヤーです。

#TapFun ウォレット

プレイヤーが TapFun でチャージする残高です。TapFun 上での購入に使います。

#TapFun クレジット

本番環境のテストプレイ用アカウントに付与される、対象のアプリでのみ使えるウォレット残高です（本番でのテストプレイ）。

#商品コード / 複合商品コード

• 商品コード（code）: 商品の種類を表すコードです。TapFun 上での集計に使います。Callback が完了していない購入があるときは、同じ商品コードの商品を続けて購入できません。
• 複合商品コード（item）: アプリ側で自由に使える補助のコードです。TapFun は内容を解釈せず、Callback API と purchases API でそのまま返します。

#変更履歴

↑ ページ先頭へ