TapFun デベロッパーポータル
Markdown 版 JAEN

はじめに

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

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

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

Publisher Console へのログイン

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

リリース内容の調整

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

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

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

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

デバッグ

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

パラメータ 内容
?debugLog=1 ゲーム画面の上にログ表示領域を出します。TapFun が受け取ったクライアント API のリクエスト(consoleLog を含む)が表示されます。2 行目にはプレイ中のプレイヤーの TapFun ユーザー ID が表示されます。
?verbose=1 ブラウザのデベロッパーツールのコンソールに詳細なログを出します。consoleLog の data もここに出力されます。

FAQ

Q. プレイヤーのウォレット残高や、purchaseItem で残高が足りないときの不足金額を取得できますか?
A. できません。TapFun ウォレットの残高と不足金額は、クライアント API・Web API・Callback API のどれからも取得できません。

Q. プレイヤーの言語や国を知ることはできますか?
A. できます。起動 URL の {lang}(プレイヤーの言語)と {country}(接続元の国)で受け取れます(動作概要)。ゲームの実行中は、getPlayerEnvironment の language と country でも取得できます。

環境

ホスト名

TapFun 環境 ホスト名 Web UI の認証
テスト 担当者にお問い合わせください(本ドキュメントでは <TEST_HOST> と表記) 紹介ページやプレイ画面: メールアドレスの確認 / Publisher Console: Basic 認証(ID / パスワードは担当者にお問い合わせください)
本番 https://tapfun.co.jp なし

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

テスト環境に入れる方

テスト環境で紹介ページやプレイ画面を開くと、メールアドレスの確認画面が表示されます。入力したメールアドレスに届く確認コードを入力すると、ページが表示されます。ゲームをプレイするには、その後に TapFun アカウントでのログインが必要です。

メールアドレスの確認を通れるのは、次の方です。

テスト環境では、御社のアプリだけが表示されます。

テスト環境での決済方法

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

本番でのテストプレイ

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

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

Publisher Console

基本情報

項目 説明
アプリ ID アプリの内部 ID です。
name 内部名です。
apiKey Web API を呼ぶ際の API キーです。
Bearer token Web API を呼ぶ際の Authorization: Bearer の値です(アプリID_apiKey の形式)。
メンテナンスモード 有効にすると、新しくゲームを起動できなくなります(メンテナンスモードの動作)。
メンテナンス例外メールアドレス メンテナンス中でもプレイできるユーザーのメールアドレスです。リリース前の非公開アプリでも、メンテナンスモードを有効にするとこのアドレスのアカウントからアクセスできます。
起動 URL ウェブアプリケーションの起動 URL です。TapFun のページ内に iframe として読み込みます。プレースホルダ {token}(create_session 用トークン)、{host}(TapFun 側のホスト名。例: tapfun.co.jp)、{appId}(アプリ ID)、{lang} / {country}(プレイヤーの言語と国。動作概要 を参照)が使えます。
sigKey HMAC-SHA256 の署名用キーです。purchaseItem の sig と Callback API の署名に使います。
purchaseItem 時の sig 必須 有効にすると、sig を送らない purchaseItem は失敗します(invalidSignature)。
フレームレス表示 有効にすると、プレイ画面に TapFun のヘッダーを表示しません。
callback HTTP POST URL アイテム購入時の通知先(Callback API)の URL です。
callback Notice Webhook URL Callback の送信に問題があったとき・復旧したときに、Webhook で通知する先の URL です(Slack の Incoming Webhook など)。
callback Notice Email Callback の送信に問題があったとき・復旧したときに通知するメールアドレスです。
purchases API 互換モード purchases API のレスポンスの userId を旧形式で返す後方互換モードです。通常は無効にしてください。

メンテナンスモードの動作

「メンテナンスモード 有効」にして保存すると、次のようになります。

無効にして保存すると、プレイヤーはプレイ画面を開き直して起動できます。

アクセス解析(Google Analytics)

Publisher Console の「アクセス解析」で「Google Analytics 測定 ID」を設定すると、TapFun 上の紹介ページとプレイ画面の閲覧と購入を、御社の Google アナリティクス 4(GA4)のプロパティに送ります。空欄の場合は何も送りません。

設定方法

  1. GA4 の管理画面で、ウェブのデータストリームに表示される「測定 ID」(G- で始まる ID)を確認します。数字だけの「プロパティ ID」とは別のものです。
  2. Publisher Console の「アクセス解析」の「Google Analytics 測定 ID」に入力し、「保存」を押します。
    • 前後の空白は取り除き、英字は大文字にそろえて保存します。
    • G- で始まらない値は保存できません。
  3. GA4 のデータストリームの拡張計測で、「ブラウザの履歴イベントに基づくページの変更」をオフにします。オンのままだと、プレイ画面の表示が二重に数えられます。

送信するページ

TapFun のほかのページ(トップ、アカウント、チャージなど)からは送りません。この 2 画面から別のページへ移ると、拡張計測のイベント(スクロールなど)も送らなくなります。

送信するイベント

イベント 送るタイミング
page_view 紹介ページ・プレイ画面を開いたとき。それぞれ 1 回送ります。
purchase 購入が完了したとき(対象の購入)。

すべてのイベントに次の値を付けます。

パラメータ 内容
user_id TapFun ユーザー ID です。
page_location ページの URL です。クエリ文字列は utm_ で始まるものだけを残し、ほかは取り除きます。

page_view には、ページのタイトルを page_title として付けます。

purchase には、次の値を付けます。

パラメータ 内容
transaction_id 購入ごとのユニークキーです。
value 購入金額(円)です。
currency JPY(固定)です。
items 購入した商品 1 件です。item_id・item_name・item_category・price(value と同じ金額)・quantity(常に 1)を持ちます。

ログイン状態(login_status)

プレイヤーがログインしているかどうかを、ユーザー プロパティ login_status として送ります。

値 意味
logged_in TapFun にログインしているプレイヤー
guest ゲスト(ログインしていないプレイヤー)

login_status を GA4 のレポートで使うには、ユーザー スコープのカスタム ディメンションとして登録してください。登録する前に送られたデータはレポートでは使えないので、測定 ID を設定したら続けて登録することをおすすめします。

送信しないもの

TapFun の決済画面や Google ログインから同じタブで戻ってきたときは、その外部サイトを参照元として扱いません。

対象の購入

purchaseItem によるアイテムの購入を送ります。

パラメータ 値
transaction_id Callback API と purchases API の key と同じ値
items の item_id purchaseItem の code
items の item_name purchaseItem の name
items の item_category item

詳細情報(紹介ページ)

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

項目 説明
アイコン画像 ゲームのアイコンです。推奨解像度は 512x512(正方形)です。
2:1 画像 一覧や紹介ページで使う横長の画像です。推奨解像度は 1920x960 です。
操作説明画像 プレイ中に TapFun の画面から開ける操作説明の画像です(任意)。
スクリーンショット画像 紹介ページに表示するスクリーンショットです。
ゲームタイトル 紹介ページなどに表示するゲームの名前です。
開発元 / パブリッシャー 紹介ページに表示する開発元とパブリッシャーの名前です。
ゲーム詳細紹介文 紹介ページの本文です。Markdown 形式で書けます。
サードパーティー EULA ゲームに含まれるサードパーティーの使用許諾など、紹介ページに表示する規約の文面です。

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

ゲームの起動

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

オプション 説明
ログ表示 画面上に consoleLog API などのログを表示します(URL の ?debugLog=1 と同じ)。
verbose ブラウザのコンソールに出すログの量を増やします(URL の ?verbose=1 と同じ)。

そのほかのタブ

タブ 内容
月別売上 日ごとの購入回数・売上・取消と、売上区分(Platform / Publisher)ごとの内訳です。
全ての Purchases / 未完了の Purchases 購入の一覧です。「未完了」は Callback が完了していない購入だけを表示します。各購入の画面から Callback を再送できます。テスト環境では購入の取り消しと Callback 再送の停止もできます。
Callbacks Callback API の送信履歴です。
Leaderboards リーダーボードとエントリーの一覧です。
紹介ページ TapFun 上のゲーム紹介ページを別タブで開きます。

起動と認証

動作概要

起動 URL の例:

text
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} の有効期限は 180 秒です。有効期限内は繰り返し使用できます。
bash
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 はサーバー側でのみ扱い、ブラウザに渡さないでください。

ゲストと会員の TapFun ユーザー ID

Web App は、TapFun にログインしていないゲストでもプレイできます。

状況 TapFun ユーザー ID
ゲストでプレイ ブラウザごとに発行されます。TapFun のログイン状態を保つ Cookie(有効期限 1 年)に結び付いていて、同じブラウザでは同じ ID のままです。
ゲストが会員登録した 変わりません。 登録前のゲストの ID が、そのまま会員の ID になります。登録の途中でページを読み直したり、確認メールを別のブラウザで開いたりしても同じです。
既存の会員が、ゲストで遊んだあとにログインした ログインした会員の ID に切り替わります。ゲストのときの ID と会員の ID の対応は、TapFun には残りません。
Cookie が消えた・別のブラウザで開いた 別のゲストとして新しい ID が発行されます。

クライアント API

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

API 概要
purchaseItem アイテム購入
getPlayerEnvironment プレイヤー環境の取得
getOneTimeData URL の onetime 値を一度だけ取得
proposeAuthentication ログインを促す
openAccount アカウントページを開く
reboot 再起動
consoleLog ログ表示

通信仕様

項目 内容
送信 window.parent.postMessage(JSON 文字列, "https://" + {host})
受信 window の message イベント。event.data は JSON 文字列です。
文字コード UTF-8
リクエスト / レスポンス形式 JSON

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

js
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 ✓ トランザクション ID。アプリ側で生成する、アプリごとに一意な ID。過去に同じ tran の購入(成功・失敗を問わない)がある場合は購入できません
code ✓ 商品コード(アプリ側で自由に設定。TapFun 上の集計などに使用)
item 複合商品コード(アプリ側で自由に設定)
amount ✓ 金額(300〜10000)
name ✓ 商品名(アプリ側で自由に設定)
img 商品サムネイル画像の URL
note 自由入力フィールド
ret 戻り先。TapFun ウォレットへのチャージでページ遷移した場合に、アプリを再起動するときの起動 URL のパス以降を指定します。起動 URL として扱われるため、{host} などのプレースホルダが改めて必要です。/ から始めてください。例: /purchaseReturn?host={host}&token={token}&appId={appId}#anchor
sig ※ 署名(署名の作り方)。Publisher Console で「purchaseItem 時の sig 必須」を有効にしている場合は必須です。送った場合は常に検証されます

リクエスト例:

json
{
  "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 進数(小文字)の文字列にした値です。

text
tapfunUserId&tran&code&item&amount&name&img&note&ret
js
// 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');
}

レスポンス通知

すべての通知に from(purchaseItem)が付きます。parameterError 以外の通知には、code(リクエストした code)と tran(リクエストした tran)も付きます。

result タイミング 追加キー
received 購入イベントを受信し、確認ダイアログを開いた —
purchaseCancel 確認ダイアログが閉じられた(購入キャンセル) —
purchase ダイアログ上で購入ボタンが押された —
purchaseSuccess 決済に成功した —
incompleteCallback 購入に失敗した(失敗のモーダルを表示した時点で送信) reason(下表)
parameterError 必須のパラメータ(tran / code / amount / name)が無い(amount が 0 や数値でないときも無いものとして扱う)。または amount がマイナス reason: エラー内容(例: required param not found "code"。amount がマイナスなら invalid param "amount")
reason 説明
duplicateTran 過去の購入と tran が重複している
unfinishedClallbackPrucahseRemaining 完了していない Callback がある(通信エラーなど)。綴りはこのとおりです
rejected Callback のレスポンスの result が reject だった
unknown 原因不明で Callback の結果が得られなかった
invalidSignature 署名が一致しなかった

getPlayerEnvironment

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

パラメータ 必須 説明
req ✓ getPlayerEnvironment(固定)

レスポンス通知:

キー 説明
from getPlayerEnvironment
userAgent ブラウザの navigator.userAgent
isSP 1 / 0。判定方法とタブレットの扱いは isSP の判定 を参照してください。
authenticated 1: ログイン中 / 0: ゲスト状態
language プレイヤーのブラウザで最も優先される言語です(BCP 47 の言語タグ。例: ja、en-US)。取得できない場合は空になります。
country 接続元の国です(例: JP)。判定方法と判定できる国は country の判定 を参照してください。

isSP の判定

isSP は、ブラウザの User-Agent(navigator.userAgent)の文字列だけで判定します。画面サイズ、タッチ操作への対応、端末の向きは見ません。

User-Agent に次のいずれかが含まれると 1、どれも含まれないと 0 です。

端末・ブラウザ User-Agent isSP
iPhone iPhone を含む 1
iPad(Safari の「デスクトップ用Webサイトを表示」がオン) Mac と同じ(Macintosh を含み、iPad を含まない) 0
iPad(Safari の「デスクトップ用Webサイトを表示」がオフ) iPad を含む 1
Android スマートフォン Android と Mobile を含む 1
Android タブレット Android を含み Mobile を含まない、または PC 版サイトの表示で Android を含まない 0
Windows / Mac(タッチ対応の PC を含む) 上のいずれも含まない 0

country の判定

country は、接続元の IP アドレスから AWS WAF で判定した国です。値は ISO 3166-1 alpha-2 の国コード(例: JP)です。判定できる国は、AWS WAF の GeoMatchStatement の CountryCodes に載っている国です。国を判定できない場合は空になります。

getOneTimeData

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

パラメータ 必須 説明
req ✓ getOneTimeData(固定)

レスポンス通知:

キー 説明
from getOneTimeData
onetime onetime の値(デコード済み)。取得済みまたは無い場合は空文字

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

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

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

json
// ?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

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

パラメータ 必須 説明
req ✓ proposeAuthentication(固定)

レスポンス通知:

キー 説明
from proposeAuthentication
authenticated 1: ログイン中だったので何もしなかった / 0: ゲスト状態だったのでモーダルを表示した

openAccount

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

パラメータ 必須 説明
req ✓ openAccount(固定)

レスポンス通知: なし

reboot

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

パラメータ 必須 説明
req ✓ reboot(固定)

レスポンス通知: なし

consoleLog

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

パラメータ 必須 説明
req ✓ consoleLog(固定)
data ✓ 文字列または JSON 文字列。JSON.parse() できた場合は JSON オブジェクトとしてコンソールに表示します。

レスポンス通知: なし

Callback API(アイテム購入完了通知)

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

仕様

項目 内容
通知先 URL Publisher Console の「callback HTTP POST URL」
接続元 IP アドレス テスト環境: 担当者にお問い合わせください / 本番: 54.178.93.41
メソッド HTTP POST
Content-Type application/json
文字コード UTF-8
応答 JSON(レスポンス)
タイムアウト 5 秒

リクエストヘッダー:

ヘッダー 説明
X-TapFun-Callback-Key Callback ごとのユニークキー
X-TapFun-Retry リトライ回数(リトライの場合のみ)
X-TapFun-Signature リクエストボディを sigKey で HMAC-SHA256 署名した値(16 進数)。受信したボディの文字列そのものから計算して照合してください
js
// 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' });
});

通知とリトライ

リクエスト

キー 説明
req purchaseItem
event purchaseItem
result success
key 購入ごとのユニークキー
appId アプリ ID
userId TapFun ユーザー ID
publisherUserId パブリッシャー様側のユーザー ID。未設定の場合は null
fromRegisterDevice 購入ユーザーが TapFun に新規登録したデバイス(SP / PC)
purchaseDevice 購入時のデバイス(SP / PC)
salesDistinction 売上区分(Publisher / Platform)
tran トランザクション ID
code 商品コード
item 複合商品コード、または null
amount 金額
name 商品名
img 画像 URL、または null
note 補足、または null
createdAt 購入日時(UTC)
json
{
  "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 を推奨します。リダイレクトには対応していません。

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

Web API

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

共通仕様

項目 内容
ベース URL https://<環境のホスト名>/api/v1(ホスト名)
メソッド HTTP GET / POST
文字コード UTF-8
リクエストヘッダー User-Agent は必須です(値は任意。例: ExampleGames-Server/1.0)。付いていないリクエストは受け付けません
リクエスト形式 URL パス、クエリストリング、POST データ(application/x-www-form-urlencoded。個別に記載があるものを除く)
レスポンス形式 JSON。配列の結果が 0 件の場合は空配列。HTTP ステータスは記載が無い限り 200
日時 UTC、yyyy-mm-ddThh:mm:ss.sssZ

認証

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

text
Authorization: Bearer 123_NWU0MjlkY2ViYTVkOTdiYjIwNThmZTkxMDMzYWM4Y2JmNGUyMTQ0Ng

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

json
{"error":"no authorization"}

User-Agent ヘッダーが無い場合は、上の JSON ではなく HTML の 403 Forbidden が返ります。

POST /api/v1/create_session

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

POST データ 必須 説明
token ✓ 起動 URL の {token} に渡された値
json
// 成功
{ "result": "success", "userId": "TapFunユーザーID" }
// 失敗(400): トークンが無い
{ "result": "failure", "message": "token is missing" }
// 失敗(400): トークンが不正
{ "result": "failure", "message": "token is invalid" }

GET /api/v1/purchases

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

クエリストリング 必須 説明
userId TapFun ユーザー ID。省略するとアプリ全体の購入を返します
key 購入キー
tran トランザクション ID
limit 件数(1〜100、デフォルト 10)。範囲外は 10
nextKey 続きの結果を取得するためのキー(前回のレスポンスの nextKey)
json
// 成功
{
  "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"
    }
  ]
}

POST /api/v1/photos

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

項目 内容
Content-Type multipart/form-data
クエリストリング userId TapFun ユーザー ID(必須)
POST データ file PNG / JPEG / WebP の画像バイナリ(必須)。part の Content-Disposition の filename は任意の値で必須(例: form-data; name="file"; filename="sample.jpg")

制約:

bash
curl -F "file=@sample.jpg;type=image/jpeg" \
  -H "Authorization: Bearer 1_8an4dAfsIyEEvBbaKxd55P2Wgf" \
  "https://<TEST_HOST>/api/v1/photos?userId=PLYR01JY39A09EE40YQZRHWTT9EM1VDBG"
json
// 成功
{ "result": "success" }
// 失敗(404): ユーザー ID が無い
{ "result": "failure", "message": "userId is not found" }
// 失敗(400): その他(file が無い、大きすぎる、形式が不正など)
{ "result": "failure", "message": "other problems." }

GET /api/v1/leaderboard/entries

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

クエリストリング 必須 説明
name ✓ リーダーボード名
sort asc: 昇順 / desc: 降順(デフォルト)
userId ユーザー ID
arround 指定ユーザーの周辺のエントリーを取得します(1〜100)。userId 指定時に機能します
offset 表示開始位置(0〜9999)。範囲外は 0
limit 件数(1〜1000、デフォルト 100)。範囲外は 100
json
// 成功
{
  "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 ごとに自動で作られます。認証: 必要。

POST データ 必須 説明
name ✓ リーダーボード名。英数字・_・- の 1〜64 文字(/^[0-9a-zA-Z_-]{1,64}$/)
userId ✓ ユーザー ID
score ✓ スコア値(0〜9,223,372,036,854,775,807)
note 追加情報(UTF-8、0〜8192 文字)
force 1 を渡すと、既存のスコア値を下回る場合でも登録します
json
// 成功
{ "result": "success" }
// 失敗(404): ユーザー ID が無い
{ "result": "failure", "message": "userId is not found" }
// 失敗(400): その他
{ "result": "failure", "message": "other problems." }

POST /api/v1/leaderboard/entries/delete

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

POST データ 必須 説明
name ✓ リーダーボード名(/^[0-9a-zA-Z_-]{1,64}$/)
userId ✓ ユーザー ID
json
// 成功
{ "result": "success" }
// 失敗(404): ユーザー ID が無い
{ "result": "failure", "message": "userId is not found" }
// 失敗(400): その他
{ "result": "failure", "message": "other problems." }

用語

TapFun ユーザー ID

アプリ 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 クレジット

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

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

変更履歴

日付 内容
2026-11-19 POST /api/v1/leaderboard/entries の score は 0 以上になりました。負の値を送ると 400 を返します。
2026-11-19 purchaseItem の amount がマイナスのときは、確認ダイアログを開かずに parameterError(reason: invalid param "amount")を送るようになりました。
2026-11-11 purchaseItem のレスポンス通知の説明を実際の動きに合わせました。通知に付くキーは req ではなく from です。parameterError は必須のパラメータが無いときだけ送り、code と tran は付きません。
2026-11-11 テスト環境の紹介ページやプレイ画面で、Basic 認証の代わりにメールアドレスの確認を行うようになりました。テストプレイする方は Publisher Console の「テストプレイヤー」で追加できます(テスト環境に入れる方)。
2026-11-09 起動 URL のプレースホルダに {lang}(プレイヤーの言語)と {country}(接続元の国)を追加しました。getPlayerEnvironment も language と country を返すようになりました(country の判定)。
2026-11-04 isSP の判定を追記しました。タブレットでの値も記載しています。
2026-11-02 Photos API の画像の保存期間を追記し、最大保存枚数の説明を更新しました。
2026-11-02 Publisher Console のメンテナンスモードの動作を追記しました。
2026-10-27 ?debugLog=1(「ログ表示」)のログの 2 行目に TapFun ユーザー ID が表示されるようになりました。
2026-10-21 Web API の共通仕様に、User-Agent ヘッダーが必須であることを追記しました。
2026-10-14 Publisher Console の「アクセス解析(Google Analytics)」を追加しました。
2026-10-07 「ゲストと会員の TapFun ユーザー ID」を追加しました。getOneTimeData に値の長さとログイン後の扱いを追記しました。
2026-10-02 このドキュメントを公開しました。

↑ ページ先頭へ