TapFun Developer Portal
Markdown JAEN

Introduction

This page is the integration specification for publishers and developers who ship a browser-based web application (Web App) on TapFun. Your web application runs embedded in an iframe on a TapFun page.

If you ship a Windows exe through cloud gaming, see the Cloud Gaming specification instead.

Setting up communication

Logging in to the Publisher Console

You can update your exe and change settings in the Publisher Console of the test environment (https://<TEST_HOST>/publisher). Your TapFun contact grants login access, so send us the email addresses of the people who will log in.

Release planning

Once the remaining issues have a clear path to resolution, we agree on the release date and pricing.

Reporting issues during development

When you hit a problem such as "input does not respond" or "unexpected behavior", report it in the communication channel with:

If the problem comes from intended behavior, both parties may discuss adding or changing a feature.

Debugging

Add one of these parameters to the game page URL to see the client API traffic.

Parameter Effect
?debugLog=1 Shows a log area over the game screen with the client API requests TapFun received (including consoleLog). The second line shows the TapFun user ID of the player who is playing.
?verbose=1 Writes detailed logs to the browser's developer tools console, including the data of consoleLog.

FAQ

Q. Can the game get the player's wallet balance, or how much they are short when the balance is not enough for purchaseItem?
A. No. The TapFun wallet balance and the shortfall cannot be obtained through the client API, the Web API, or the Callback API.

Q. Can the game find out the player's language or country?
A. Yes. The {lang} (the player's language) and {country} (the country the player connects from) placeholders in the launch URL pass them to your web application (How it works). While the game is running, you can also get them as language and country from getPlayerEnvironment.

Environments

Hostnames

TapFun environment Hostname Access check on the web UI
Test Ask your TapFun contact (written as <TEST_HOST> in this document) Introduction pages and play screens: email verification / Publisher Console: Basic auth (ask your TapFun contact for the user name and password)
Production https://tapfun.co.jp None

The test environment hostname and the user name and password of the Publisher Console Basic auth are confidential and are not included in this document. Ask your TapFun contact for them. Replace <TEST_HOST> in code examples with the test environment hostname. Do not share them outside your company or anywhere public (public repositories, public channels, and so on).

Who can access the test environment

When you open an introduction page or a play screen in the test environment, an email verification page appears. Enter the verification code sent to the email address you entered, and the page opens. To play a game, you then also need to log in with a TapFun account.

The following people can pass the email verification:

Only your company's apps are shown in the test environment.

Payments in the test environment

To buy items in the test environment, use one of the following.

Test play in production

To access an app before release, enable maintenance mode in the Publisher Console's basic settings and enter the tester's email address in "Maintenance exception email addresses".

For tests in production that involve purchases, TapFun registers a test-play account for each app. The account receives TapFun credit usable only in that app. Purchases by test-play accounts are cancelled immediately and offset against sales.

Publisher Console

Basic settings

Field Description
App ID Internal ID of the app.
name Internal name.
apiKey API key for calling the Web API.
Bearer token Value of Authorization: Bearer when calling the Web API (format: <AppID>_<apiKey>).
Maintenance mode When enabled, new game launches are blocked (How maintenance mode works).
Maintenance exception email addresses Users with these email addresses can play during maintenance. For an unreleased (private) app, enabling maintenance mode also lets these accounts access it.
Launch URL URL that launches your web application. TapFun loads it in an iframe. Placeholders: {token} (token for create_session), {host} (TapFun hostname, e.g. tapfun.co.jp), {appId} (app ID), {lang} / {country} (the player's language and country; see How it works).
sigKey HMAC-SHA256 signing key. Used for the sig of purchaseItem and for signing the Callback API.
Require sig for purchaseItem When enabled, purchaseItem without sig fails (invalidSignature).
Frameless display When enabled, the TapFun header is not shown on the play screen.
callback HTTP POST URL URL notified when an item is purchased (Callback API).
callback Notice Webhook URL Webhook URL notified when sending a callback fails and when it recovers (e.g. a Slack incoming webhook).
callback Notice Email Email address notified when sending a callback fails and when it recovers.
purchases API compatibility mode Backward-compatibility mode that returns userId in the old format in the purchases API. Normally keep it disabled.

How maintenance mode works

When you enable "Enable maintenance mode" and save:

After you disable it and save, players can reopen the play screen and launch the game.

Analytics (Google Analytics)

When you set "Google Analytics measurement ID" under "Analytics" in the Publisher Console, page views and purchases on your TapFun introduction page and play screen are sent to your Google Analytics 4 (GA4) property. If it is blank, nothing is sent.

Setup

  1. In GA4 admin, find the "Measurement ID" (starting with G-) shown on your web data stream. This is not the numeric "Property ID".
  2. Enter it in "Google Analytics measurement ID" under "Analytics" in the Publisher Console and click "Save".
    • Leading and trailing spaces are removed and letters are saved in upper case.
    • Values that do not start with G- cannot be saved.
  3. In the enhanced measurement settings of the GA4 data stream, turn off "Page changes based on browser history events". Otherwise the play screen is counted twice.

Pages that send data

Other TapFun pages (top, account, charge, etc.) send nothing. After the player moves from these 2 screens to another page, enhanced measurement events (scrolls, etc.) are no longer sent either.

Events

Event When it is sent
page_view When the introduction page or the play screen opens. Sent once for each.
purchase When a purchase completes (purchases covered).

All events carry these values.

Parameter Content
user_id The TapFun user ID.
page_location The page URL. Only query parameters starting with utm_ are kept; the rest are removed.

page_view also carries the page title as page_title.

purchase carries these values.

Parameter Content
transaction_id A unique key for each purchase.
value Purchase amount (JPY).
currency JPY (fixed).
items The one purchased product, with item_id, item_name, item_category, price (same amount as value), and quantity (always 1).

Login status (login_status)

Whether the player is logged in is sent as the user property login_status.

Value Meaning
logged_in A player logged in to TapFun
guest A guest (a player who is not logged in)

To use login_status in GA4 reports, register it as a user-scoped custom dimension. Data sent before you register it cannot be used in reports, so we recommend registering it right after you set the measurement ID.

Not sent

When the player returns in the same tab from TapFun's payment screens or Google login, that external site is not treated as the referrer.

Purchases covered

Item purchases made with purchaseItem are sent.

Parameter Value
transaction_id Same as key in the Callback API and the purchases API
item_id in items purchaseItem's code
item_name in items purchaseItem's name
item_category in items item

Details (introduction page)

The "詳細情報" (details) tab edits what is shown on the game's introduction page on TapFun.

Field Description
Icon image The game's icon. Recommended size: 512x512 (square).
2:1 image A wide image used in listings and on the introduction page. Recommended size: 1920x960.
Controls guide images Optional images explaining the controls, which players can open from the TapFun screen while playing.
Screenshot images Screenshots shown on the introduction page.
Game title The game name shown on the introduction page and elsewhere.
Developer / Publisher Developer and publisher names shown on the introduction page.
Game description Body text of the introduction page, in Markdown.
Third-party EULA License terms shown on the introduction page, such as third-party licenses included in the game.

Drag controls guide images and screenshots to reorder them. To delete one, click it to mark it for deletion, then press "追加アップロード & 順序を保存" (upload and save order) to apply the change.

Launching the game

"アプリページ" (app page) at the top of the app screen launches the game with the options below (Debugging). Unreleased apps show "非公開状態" (private).

Option Description
ログ表示 (show log) Shows consoleLog API and other logs on screen (same as ?debugLog=1).
verbose Increases the logs written to the browser console (same as ?verbose=1).

Other tabs

Tab Contents
月別売上 (monthly sales) Daily purchase counts, sales and cancellations, with a breakdown by sales category (Platform / Publisher).
全ての Purchases / 未完了の Purchases (all / unfinished purchases) List of purchases. "Unfinished" shows only purchases whose callback has not completed. You can resend the callback from each purchase. In the test environment you can also cancel a purchase and stop callback resends.
Callbacks History of Callback API requests.
Leaderboards Leaderboards and their entries.
紹介ページ (introduction page) Opens the game's introduction page on TapFun in a new tab.

Launch and authentication

How it works

Example launch URL:

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

User authentication / getting the TapFun user ID

  1. Send the value passed in {token} from the browser to your game server.
  2. Your game server calls POST /api/v1/create_session, which returns the TapFun user ID.
  3. {token} is valid for 180 seconds. It can be reused while valid.
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"}

Keep the Bearer token on the server. Never send it to the browser.

TapFun user IDs for guests and members

A Web App can be played by guests who are not logged in to TapFun.

Situation TapFun user ID
Playing as a guest Issued per browser. It is tied to the cookie that keeps the TapFun login state (valid for one year), so it stays the same in the same browser.
A guest signs up Does not change. The guest's ID becomes the member's ID. This also holds if the page is reloaded during sign-up or the confirmation email is opened in another browser.
An existing member plays as a guest, then logs in Switches to the member's ID. TapFun keeps no record linking the guest ID and the member ID.
The cookie is lost, or another browser is used A new ID is issued as a different guest.

Client API

APIs for communication between your web application and TapFun, its parent frame. Messages are exchanged in the player's browser, so never include secrets.

API Summary
purchaseItem Item purchase
getPlayerEnvironment Get the player's environment
getOneTimeData Read the URL's onetime value once
proposeAuthentication Prompt the player to log in
openAccount Open the account page
reboot Restart
consoleLog Show a log message

Transport

Item Value
Sending window.parent.postMessage(JSON string, "https://" + {host})
Receiving The message event on window. event.data is a JSON string.
Encoding UTF-8
Request / response format JSON

TapFun accepts a message only if it comes from the embedded iframe and its origin matches the launch URL's origin. On your side, check that event.origin is https://{host}.

js
const params = new URLSearchParams(location.search);
const tapfunOrigin = 'https://' + params.get('host'); // include {host} in your launch URL

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

Shows the item purchase confirmation dialog and processes the payment. When the payment succeeds, TapFun notifies your game server through the Callback API. Grant the item on your game server when it receives the callback.

Parameter Required Description
req ✓ purchaseItem (fixed)
tran ✓ Transaction ID generated by your app, unique per app. Purchase is refused if a past purchase (successful or not) used the same tran
code ✓ Product code (any value; used for aggregation on TapFun)
item Composite product code (any value)
amount ✓ Price (300-10000)
name ✓ Product name (any value)
img Product thumbnail image URL
note Free-form field
ret Return target. When charging the TapFun wallet involves a page transition, this sets the path (and after) of the launch URL used to restart the app. It is treated as a launch URL, so placeholders such as {host} are needed again. Must start with /. Example: /purchaseReturn?host={host}&token={token}&appId={appId}#anchor
sig * Signature (How to sign). Required if "Require sig for purchaseItem" is enabled in the Publisher Console. Always verified when sent

Request example:

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 Gems",
  "ret": "/purchaseReturn?host={host}&token={token}&appId={appId}#anchor",
  "sig": "SIGNATURE_HASH_HERE"
}

How to sign

Join the following values with & in this order, compute HMAC-SHA256 with the Publisher Console's sigKey as the key, and use the lowercase hex string.

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

Response notifications

Every notification includes from (purchaseItem). All notifications except parameterError also include code (the requested code) and tran (the requested tran).

result When Extra keys
received The purchase event was received and the confirmation dialog opened —
purchaseCancel The confirmation dialog was closed (purchase cancelled) —
purchase The purchase button in the dialog was pressed —
purchaseSuccess The payment succeeded —
incompleteCallback The purchase failed (sent when the failure modal is shown) reason (below)
parameterError A required parameter (tran / code / amount / name) is missing (an amount of 0 or a non-numeric amount counts as missing), or amount is negative reason: error details (e.g. required param not found "code"; invalid param "amount" for a negative amount)
reason Description
duplicateTran The tran duplicates a past purchase
unfinishedClallbackPrucahseRemaining There is an unfinished callback (e.g. due to a network error). The spelling is exactly as shown
rejected The callback response's result was reject
unknown The callback result could not be obtained for an unknown reason
invalidSignature The signature did not match

getPlayerEnvironment

Gets the player's environment.

Parameter Required Description
req ✓ getPlayerEnvironment (fixed)

Response:

Key Description
from getPlayerEnvironment
userAgent The browser's navigator.userAgent
isSP 1 / 0. See How isSP is determined for the logic and how tablets are handled.
authenticated 1: logged in / 0: guest
language The player's most preferred browser language (a BCP 47 language tag, e.g. ja, en-US). Empty if it cannot be obtained.
country The country the player connects from (e.g. JP). See How country is determined for how it is determined and which countries are supported.

How isSP is determined

isSP is determined only from the browser's User-Agent string (navigator.userAgent). Screen size, touch support, and device orientation are not checked.

It is 1 if the User-Agent contains any of the following, and 0 if it contains none of them.

Device / browser User-Agent isSP
iPhone Contains iPhone 1
iPad (Safari "Request Desktop Website" on) Same as a Mac (contains Macintosh, does not contain iPad) 0
iPad (Safari "Request Desktop Website" off) Contains iPad 1
Android smartphone Contains Android and Mobile 1
Android tablet Contains Android but not Mobile, or does not contain Android when viewing the desktop site 0
Windows / Mac (including touch-enabled PCs) Contains none of the above 0

How country is determined

country is the country that AWS WAF determines from the IP address the player connects from. The value is an ISO 3166-1 alpha-2 country code (e.g. JP). The countries AWS WAF can determine are those listed under CountryCodes in GeoMatchStatement. If the country cannot be determined, the value is empty.

getOneTimeData

Reads the onetime query string value of the TapFun page URL, once. Useful for deep links. After the request, onetime is removed from the URL.

Parameter Required Description
req ✓ getOneTimeData (fixed)

Response:

Key Description
from getOneTimeData
onetime Decoded value of onetime. Empty string if already read or absent

Example: when the URL is https://tapfun.co.jp/p/dummy/play?onetime=abcdefg

json
// 1st request
{ "from": "getOneTimeData", "onetime": "abcdefg" }
// 2nd request (onetime has been removed from the URL)
{ "from": "getOneTimeData", "onetime": "" }

With an encoded value:

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

Prompts the player to log in. For a guest, shows the sign-up / login modal.

Parameter Required Description
req ✓ proposeAuthentication (fixed)

Response:

Key Description
from proposeAuthentication
authenticated 1: already logged in, nothing was done / 0: guest, the modal was shown

openAccount

Opens the account page. For a guest, shows the sign-up / login modal.

Parameter Required Description
req ✓ openAccount (fixed)

Response: none

reboot

Restarts the game, the same as when the player taps the restart icon in the TapFun UI.

Parameter Required Description
req ✓ reboot (fixed)

Response: none

consoleLog

Adds a log line to TapFun's log area. It is also written to the browser's developer tools console.

Parameter Required Description
req ✓ consoleLog (fixed)
data ✓ A string or JSON string. If JSON.parse() succeeds, it is shown in the console as a JSON object.

Response: none

Callback API (item purchase notification)

When a purchaseItem payment succeeds, the TapFun server notifies your game server of the purchase.

Specification

Item Value
Endpoint "callback HTTP POST URL" in the Publisher Console
Source IP address Test: ask your TapFun contact / Production: 54.178.93.41
Method HTTP POST
Content-Type application/json
Encoding UTF-8
Response JSON (Response)
Timeout 5 seconds

Request headers:

Header Description
X-TapFun-Callback-Key Unique key per callback
X-TapFun-Retry Retry count (only on retries)
X-TapFun-Signature HMAC-SHA256 of the request body signed with sigKey (hex). Compute it from the raw body string as received
js
// Signature verification example with 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' }); // anything other than success / reject is retried
  }
  const purchase = JSON.parse(req.body);
  // process idempotently by purchase.tran and grant the item
  res.json({ result: 'success' });
});

Notifications and retries

Request

Key Description
req purchaseItem
event purchaseItem
result success
key Unique key per purchase
appId App ID
userId TapFun user ID
publisherUserId Your user ID for the player, or null if not set
fromRegisterDevice Device the player signed up to TapFun on (SP / PC)
purchaseDevice Device used for the purchase (SP / PC)
salesDistinction Sales category (Publisher / Platform)
tran Transaction ID
code Product code
item Composite product code, or null
amount Price
name Product name
img Image URL, or null
note Note, or null
createdAt Purchase time (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 Gems",
  "img": "https://example.com/img/item.png",
  "note": null,
  "createdAt": "2024-03-06T06:37:22.000Z"
}

Response

Your game server must return success or reject in the JSON result. Otherwise TapFun retries. The HTTP status is not evaluated, but 200 is recommended. Redirects are not supported.

json
// Purchase succeeded
{ "result": "success" }
// Purchase rejected
{ "result": "reject" }

Web API

HTTP APIs called from your servers. Keep the Bearer token on the server and never send it to the browser.

Common specification

Item Value
Base URL https://<environment hostname>/api/v1 (Hostnames)
Method HTTP GET / POST
Encoding UTF-8
Request headers User-Agent is required (any value, e.g. ExampleGames-Server/1.0). Requests without it are rejected
Request format URL path, query string, POST data (application/x-www-form-urlencoded unless stated otherwise)
Response format JSON. An empty array when an array result has no items. HTTP status is 200 unless stated otherwise
Date/time UTC, yyyy-mm-ddThh:mm:ss.sssZ

Authentication

Authenticate with the HTTP header Authorization: Bearer <AppID>_<APIKey> (the Bearer token in the Publisher Console).

text
Authorization: Bearer 123_NWU0MjlkY2ViYTVkOTdiYjIwNThmZTkxMDMzYWM4Y2JmNGUyMTQ0Ng

On authentication failure the API returns HTTP 403 with:

json
{"error":"no authorization"}

If the User-Agent header is missing, the API returns an HTML 403 Forbidden page instead of the JSON above.

POST /api/v1/create_session

Gets the TapFun user ID from the launch URL's {token} (User authentication). Authentication: required.

POST data Required Description
token ✓ Value passed in the launch URL's {token}
json
// Success
{ "result": "success", "userId": "<TapFun user ID>" }
// Failure (400): token missing
{ "result": "failure", "message": "token is missing" }
// Failure (400): token invalid
{ "result": "failure", "message": "token is invalid" }

GET /api/v1/purchases

Gets the purchase history, newest first. Useful for checking purchases whose callback you missed. Authentication: required.

Query string Required Description
userId TapFun user ID. If omitted, returns purchases for the whole app
key Purchase key
tran Transaction ID
limit Number of results (1-100, default 10). Out of range becomes 10
nextKey Key for fetching the next results (the nextKey of the previous response)
json
// Success
{
  "nextKey": "Purchase01HE2R3JV6Y2NEGRMS4KZQB858",   // null when there are no more results
  "result": [
    {
      "key": "Purchase01HE2R3JV6Y2NEGRMS4KZQB861",
      "appId": 1,
      "userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
      "tran": "abcdef123456",
      "code": "abcdef123456",
      "item": "abcdef123456",
      "amount": 500,
      "name": "300 Gems",
      "img": null,
      "callbackSuccess": false,
      "createdAt": "2024-03-06T06:37:22.000Z"
    }
  ]
}

POST /api/v1/photos

Saves an image to TapFun photo storage. Players can view and download images saved from games on TapFun. Authentication: required.

Item Value
Content-Type multipart/form-data
Query string userId TapFun user ID (required)
POST data file PNG / JPEG / WebP image binary (required). The part's Content-Disposition must have a filename (any value), e.g. form-data; name="file"; filename="sample.jpg"

Limits:

bash
curl -F "file=@sample.jpg;type=image/jpeg" \
  -H "Authorization: Bearer 1_8an4dAfsIyEEvBbaKxd55P2Wgf" \
  "https://<TEST_HOST>/api/v1/photos?userId=PLYR01JY39A09EE40YQZRHWTT9EM1VDBG"
json
// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other (file missing, too large, invalid type, etc.)
{ "result": "failure", "message": "other problems." }

GET /api/v1/leaderboard/entries

Gets leaderboard entries. Authentication: required.

Query string Required Description
name ✓ Leaderboard name
sort asc: ascending / desc: descending (default)
userId User ID
arround Gets entries around the given user (1-100). Works when userId is set
offset Start position (0-9999). Out of range becomes 0
limit Number of entries (1-1000, default 100). Out of range becomes 100
json
// Success
{
  "result": "success",
  "entries": [
    {
      "position": 1,
      "userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
      "userName": "Player",               // UTF-8, no emoji, 1-12 characters
      "score": 12345,
      "note": "extra info",               // up to 8192 characters
      "createdAt": "2025-09-24T00:00:00.000Z",
      "updatedAt": "2025-09-24T00:00:00.000Z"
    }
  ]
}
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }

POST /api/v1/leaderboard/entries

Creates or updates a leaderboard entry. If the score is less than or equal to the existing score, it is not updated. A leaderboard is created automatically for each name. Authentication: required.

POST data Required Description
name ✓ Leaderboard name. 1-64 characters of letters, digits, _ and - (/^[0-9a-zA-Z_-]{1,64}$/)
userId ✓ User ID
score ✓ Score (0 to 9,223,372,036,854,775,807)
note Extra info (UTF-8, 0-8192 characters)
force Pass 1 to save even if the score is lower than the existing one
json
// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }

POST /api/v1/leaderboard/entries/delete

Deletes a leaderboard entry. Returns success even if there is no entry. Authentication: required.

POST data Required Description
name ✓ Leaderboard name (/^[0-9a-zA-Z_-]{1,64}$/)
userId ✓ User ID
json
// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }

Glossary

TapFun user ID

App ID

An unsigned int ID that identifies an app.

API key

A 26-character string issued per app. Characters: 0-9, A-Z.

Publisher Console

The management console for publishers, used for app settings, the introduction page, sales and more. The test and production environments each have their own, and TapFun registers who can log in.

Introduction page

The game's page on TapFun (https://tapfun.co.jp/p/<app>). The play screen is https://tapfun.co.jp/p/<app>/play. Edit its contents under Details in the Publisher Console.

Guest

A player who is not logged in to TapFun.

TapFun wallet

The balance a player charges on TapFun, used for purchases on TapFun.

TapFun credit

Wallet balance given to test-play accounts in production, usable only in the target app (Test play in production).

Product code / composite product code

Changelog

Date Change
2026-11-19 score in POST /api/v1/leaderboard/entries must now be 0 or greater. A negative value returns 400.
2026-11-19 When amount in purchaseItem is negative, TapFun no longer opens the confirmation dialog and sends parameterError (reason: invalid param "amount").
2026-11-11 Corrected the purchaseItem response notifications to match the actual behavior. The notifications carry from, not req. parameterError is sent only when a required parameter is missing, and does not include code or tran.
2026-11-11 Introduction pages and play screens in the test environment now use email verification instead of Basic auth. You can add people who test play in "Test players" in the Publisher Console (Who can access the test environment).
2026-11-09 Added the {lang} (the player's language) and {country} (the country the player connects from) placeholders to the launch URL. getPlayerEnvironment now also returns language and country (How country is determined).
2026-11-04 Added How isSP is determined, including the values on tablets.
2026-11-02 Added the image retention period to the Photos API and updated the description of the maximum number of images.
2026-11-02 Added how maintenance mode works in the Publisher Console.
2026-10-27 The log shown with ?debugLog=1 ("ログ表示", show log) now shows the TapFun user ID on its second line.
2026-10-21 Added to the Web API common specification that the User-Agent header is required.
2026-10-14 Added "Analytics (Google Analytics)" to the Publisher Console.
2026-10-07 Added "TapFun user IDs for guests and members". Added notes on value length and behavior after login to getOneTimeData.
2026-10-02 Published this document.

↑ Back to top