Introduction
This page is the integration specification for publishers and developers who ship games on TapFun through cloud gaming. Your Windows exe runs on a Windows server in the cloud and is streamed to the player's browser. It is best suited to titles monetized by play time that do not download additional assets.
If your game runs in the browser, see the Web App specification instead.
Getting to a test play
- Submit a zip file containing an executable exe.
- We send you a link to play it in the test environment. Check how it feels and plays.
- To keep testing after the free play time runs out, purchase energy or a title pass. Choose "AmazonPay" as the payment method (Payments in the test environment).
If the test play shows no major issues, continue with the steps below.
Setting up communication
- Email is the default channel.
- If needed, TapFun creates a Slack Connect channel shared by both companies.
- If you cannot join a Slack Connect channel, we will join your company's communication tool instead.
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:
- The app name where the problem reproduces (if the test environment has several copies of the same game, include the app ID or other identifying information)
- The TapFun user account in the test environment where it happened (unless it only happens as a guest)
- Screenshots that show the situation
- A screen recording of the full reproduction steps, if screenshots are not enough
- The steps to reproduce
If the problem comes from intended behavior, both parties may discuss adding or changing a feature.
If the problem is found to be on the TapFun platform side (launch, save data save and restore, streaming), TapFun handles it. If it is a problem with running the exe on Windows in the cloud (Tencent CAR), please handle it on your side, such as modifying the exe or creating and verifying a workaround, as described in What TapFun does and the scope of support.
Requirements for the exe
- Any game engine is fine, as long as it is an exe that runs on Windows. Whether it actually works is checked in the private test environment (a 13 GB title runs fine).
- There is no installation step. The zip is extracted and the exe is launched directly. Bundled runtime installers (Visual C++ Redistributable, OpenAL, etc.) are not run, so put the required DLLs in the same folder as the exe.
- Do not reference files by absolute path from the exe. Paths differ between your PC and the cloud. Use relative paths.
- The game must start without Steam or other store clients. If you use Steamworks, remove it from the build or make the game continue when initialization fails (without Steam, initialization tends to fail or hang at startup). No other SDK, DRM or launcher support is needed.
- We need the exe itself for testing. Testing with a Steam key is not possible.
- Give the zip a name that identifies the title (e.g.
MyGame_Demo.zip). - Put exactly one folder at the top of the zip, with the exe and all other files inside it. Zip the folder itself, not its contents. Put a readme or any other file inside the folder too, not at the top (e.g.
MyGame/MyGame.exeis fine; a zip withMyGame.exeandMyGame_Data/directly at the top, or withMyGame/andREADME.txtat the top, is not). - Keep the folder name inside the zip and the exe file name fixed. When you update the build, use the same folder name and file name as in your first submission. Do not include build numbers, dates, or versions in the folder name or the exe name (e.g.
MyGame/MyGame.exeis fine; avoid260819_1353/MyGame.exe). You may change the zip file name.- TapFun sets the exe to launch and the save data directory as paths that include this folder name. If the names change, the upload fails, or the game uploads but does not launch.
- Use only ASCII letters, digits and symbols in the folder name inside the zip and the exe file name. Names with Japanese or other multibyte characters do not work correctly in the cloud (e.g.
MyGame/MyGame.exeis fine;マイゲーム/マイゲーム.exeis not).
Adjusting the exe
Before release, adjust the exe as follows.
- Save data must be stored under one of the supported paths. If it already is, tell TapFun the directory. If not, the exe needs to change. The Windows registry cannot be used.
- Unity's
PlayerPrefsis stored in the registry by default on Windows (HKEY_CURRENT_USER\Software\<CompanyName>\<ProductName>), so it is not saved as-is. Switch to saving to files.
- Unity's
- If the game starts in a window, make it start in full screen.
- If the game can start in full screen through a launch option, set it in "exe launch parameters" in the Publisher Console (Basic settings).
- If the in-game settings let players toggle full screen, we recommend disabling that option.
- If players can quit the game from inside it (terminating the exe process), we recommend disabling that.
- In-game external links (store pages, credit URLs, etc.) do not work, because they try to open in the cloud rather than in the player's browser. Use openUrl to open external URLs.
- Features that open other Windows apps or folders, such as "Open save folder", do not work. Hide them.
- In builds for the production environment, remove any on-screen debug display.
- If the game captures the mouse cursor (FPS, etc.), we recommend assigning the menu to a key other than Esc (Mouse cursor capture).
From testing to release
- Test in the test environment: after the email verification, log in with a TapFun account you create yourself (login is required to play). You can also launch a version from "このバージョンで起動" (launch this version) in the Publisher Console version list.
- Final check in production: access to the production Publisher Console is granted separately. Before release, check the private app using Test play in production.
- Publish: TapFun publishes the title. The publish time can be set between 10:00 and 17:00 JST.
- From receiving the exe to release takes about one month (including preparing the cloud environment and testing and adjusting the cloud version).
- The Publisher Console has no roles. Everyone who can log in can do the same things. To add people, send their email addresses to TapFun.
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. |
Getting logs
To get the logs your exe writes in the cloud, write the log files inside the save data directory. In the Publisher Console, enter a TapFun user ID under "Tools → Save data download" on the "バイナリ" (binary) tab to download them together with the save data.
- To find the TapFun user ID to enter, check "ログ表示" (show log) in the Publisher Console, open "アプリページ" (app page) and launch the game. The ID appears on the second line of the on-screen log as
TapFunUserId: <ID>(launching with?debugLog=1in the URL works the same way). - Download at least 1 hour after the game exits.
- Write logs to the save data directory only in development builds.
- Unity writes
Player.logtoApplication.persistentDataPath(C:\Users\%UserName%\AppData\LocalLow\<company>\<product>). If the save data directory is that folder, the log is included even in production builds.
- Unity writes
- If, as an exception, a production build also writes them, keep the logs from growing by deleting old logs, overwriting them or capping their size. Logs are saved and restored as save data, so if the save data exceeds 100 MB in total, problems such as save data rolling back can occur.
Player support
- TapFun handles inquiries about the TapFun platform (login, payment, the game not starting, etc.). When needed, we share them with you along with the player ID.
- Inquiries about the game content are directed to your support contact. Prepare a contact point (such as a form) and let TapFun know.
What TapFun does and the scope of support
This section shows which work TapFun does and which work we ask you to do. Checking the game's content and changing the exe are up to you.
Work TapFun does
These cannot be done in the Publisher Console. Ask TapFun when you need them.
- Setting or changing the exe to launch. The folder name inside the zip and the exe file name are fixed; ask us to change them only when necessary (Requirements for the exe).
- Setting or changing the save data directory. The save data directory is also fixed; ask us to change it only when necessary.
- Changing the resolution and the server specs
- Changing the Steam AppID (Steam)
- Adding people who can log in to the Publisher Console
- Publishing in the production environment and scheduling the release date and time
- Receiving the build when it cannot be uploaded from the Publisher Console
- Investigating issues on the TapFun platform side (launching, saving and restoring save data, streaming)
Check at first registration: only when the first build is registered, TapFun briefly checks the following. This is not a check of the game's content, and it is not repeated when you update the build.
- Launch: TapFun uses AI to check that the game launches and to go as far as the AI can operate it, up to around the start of play (from the title screen to just after play begins). Some games cannot be operated by the AI, and the check may not reach that point.
- Save data directory: TapFun uses AI to identify the save data directory from the directory you told us or from where the game writes, then sets it in the test environment and checks that save data is stored in the cloud. We do not check that the game loads it correctly (that progress and settings carry over). Check this using Checking that save data carries over. If it is not in a location that can be saved (for example, the game saves to the registry), we let you know.
Work you do in the Publisher Console
You can do the following yourself in the Publisher Console. There is no need to ask TapFun.
- Setting "exe launch parameters" (for example, an option to launch in fullscreen, or the launch parameters for integrating with the TapFun API; Basic settings)
- Switching "Gamepad support", "Gamepad input API", "Virtual pad default", "Pointer device support" and "Always show mouse cursor" (Basic settings)
- Editing the text and images of the introduction page (Details)
- Setting the "Tracking parameters (utm)" added to links to the Steam store (Steam)
- Uploading, releasing and reverting to an earlier version of the binary (Updating the binary)
- Downloading save data and logs (Getting logs)
- Adding people who test play in the test environment ("Test players"; Who can access the test environment)
- Buying energy and title passes in the test environment (Payments in the test environment). TapFun does not add energy to test accounts.
Out of scope
TapFun does not do the following.
- Anything that requires launching and playing the game to check (translated text, game progression, how each stage works, how the controls feel, etc.). Please check these in the test environment.
- Checking that the game loads its save data correctly (that progress and settings carry over). Check this using Checking that save data carries over.
- Changing the exe, or creating and testing workarounds (removing Steamworks, switching saves to files, etc.). Upload builds with workarounds to the test environment and check them yourself. If the exe to launch needs to change, TapFun sets it.
- Investigating behavior specific to a game engine or tool
- Investigating the cause of bugs in the game itself. Get logs as described in Getting logs.
- Answering individual questions about our security measures (Security)
Security
- The cloud gaming platform is Tencent CAR (How it works).
- The TapFun web service runs on AWS.
- Images such as those on introduction pages are stored and delivered with Cloudflare.
- The servers that run the games are in Japan.
- Save data is stored per TapFun account (User data save and restore).
- If you would like to sign a non-disclosure agreement (NDA), please contact us.
As a rule, we do not answer individual questions about other specifics of our security measures (such as encrypting builds or preventing data extraction).
FAQ
Q. Can you check the translated text or the game's progression?
A. This is out of scope (Out of scope). Please check it in the test environment.
Q. After uploading a build with a renamed exe or a renamed folder inside the zip, the game no longer launches.
A. TapFun sets the exe to launch and the save data directory as paths that include the folder name inside the zip. Upload builds without renaming the folder or the exe (Requirements for the exe). If you really need to rename them, contact TapFun before uploading.
Q. Save data carried over when I relaunched right away, but not when I launched again later.
A. If you relaunch within 1 hour of exiting the game, the environment from the previous play is reused, so save data can appear to carry over even if the save data directory is incorrect. The save data directory may be incorrect, so please contact TapFun. Wait at least 1 hour before checking that save data carries over (Checking that save data carries over).
Q. Shaders are compiled every time the game starts. Can the compiled results be saved so this is skipped next time?
A. No. The cloud PC environment is not fixed, and each session may not run on the same environment, so even if the compiled results are saved as save data, there is no guarantee they can be reused (Shader compilation results).
Q. Can you set the game to launch in fullscreen?
A. If a launch option can make it fullscreen, you can set it yourself in "exe launch parameters" in the Publisher Console (Basic settings).
Q. Can you add energy to our test account?
A. We do not add energy. Please buy it as described in Payments in the test environment.
Q. Can you try a build with a workaround (such as a separate launcher exe)?
A. Please upload it to the test environment and check it yourself. If the exe to launch needs to change, let TapFun know.
Q. Can you find out why the game crashes?
A. Investigating bugs in the game itself is out of scope. Get logs as described in Getting logs and check them.
Q. Can you tell us about your security measures, such as encrypting builds?
A. What we can share is listed under Security. As a rule, we do not answer individual questions about anything else.
Q. There is no sound until I click the game screen.
A. This is expected behavior caused by browser restrictions.
Q. The gamepad does not respond.
A. It responds after you click the game screen. It sometimes works without a click, but as a rule, click the game screen first.
Q. On iPhone, the sound stops after switching back from another app.
A. This can happen in any title, though not every time.
Q. Can the game get the player's wallet balance, or how much they are short when purchasing?
A. No. The TapFun wallet balance and the shortfall at purchase cannot be obtained through the client API, the Web API, or the launch parameters.
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 pass them to the exe. Neither is included in the default launch parameters, so add them to "exe launch parameters" to use them (Launch parameters). 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:
- People who can log in to your Publisher Console
- People whose email address is registered in "Test players" in the Publisher Console. Register people who do not log in to the Publisher Console (such as QA vendors) here
- Write one address per line. An entry that starts with @, such as
@example.com, covers every email address in that domain - Changes take effect as soon as you save
- This applies only to the test environment. The production Publisher Console does not have "Test players"
- Write one address per line. An entry that starts with @, such as
Only your company's apps are shown in the test environment.
Payments in the test environment
To buy energy or a title pass in the test environment, use one of the following.
- AmazonPay: takes you to the "Multi-Payment Service test environment". Select "決済する" (Pay) to complete the payment.
- Test credit card: number
4111111111111111, any future expiry month/year, any 3-digit security code.
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 and games being played end (How maintenance mode works). |
| Maintenance exception email addresses | Users with these email addresses can play during maintenance (one per line). For an unreleased (private) app, enabling maintenance mode also lets these accounts access it. |
| folder | Folder name inside the uploaded zip. |
| exe | File name of the exe to run inside the zip. |
| exe launch parameters | Command-line options. Example: --debug=on --verbose. Placeholders such as {userId} are replaced with each player's values at launch. The "Set default launch arguments" button replaces the value with the standard parameters for integrating with the TapFun API (Launch parameters). Up to 255 characters. |
| Save data directory | Directory for save data. Every file in it is saved and restored as save data, so put nothing but save data and logs there. Contact us to change it (User data save and restore). |
| Gamepad support | Enable for titles playable with the virtual pad or by tapping on smartphones and tablets. When disabled, the play buttons are not shown on the introduction page on smartphones and tablets (Supported devices). |
| Gamepad input API | Choose "XInput" or "WGI" to match how your game reads gamepads (Gamepad). The default is "XInput". |
| Virtual pad default | Whether the on-screen virtual pad is shown from the start on smartphones and tablets. Disable it for titles played by tapping only. |
| Pointer device support | Enable for titles playable with a mouse. |
| Always show mouse cursor | When enabled, the mouse cursor is always shown. Disable it if the game captures the mouse cursor for camera control, as in FPS games (Mouse cursor capture). |
How maintenance mode works
When you enable "Enable maintenance mode" and save:
- New launches: the play screen shows "現在「〇〇」はメンテナンス中です。少しお時間をおいてから、再度お試しください。" (under maintenance, please try again later) and the game does not launch. Players cannot restart it from the play screen either.
- Games being played: they end without warning and show the same message. What is already written to the save data directory is saved, but progress not yet saved in the game is lost.
- Confirmation on save: when you change it from disabled to enabled and save, you are asked "Enabling maintenance mode disconnects the sessions currently running. Are you sure you want to enable it?". If you cancel, nothing is saved.
- Exceptions: accounts in "Maintenance exception email addresses" can launch during maintenance, and their games do not end.
- Introduction page: it is shown as usual, with no maintenance notice.
After you disable it and save, players can reopen the play screen and launch the game.
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.
Sales settings
Sales settings are display-only. Contact TapFun to change anything other than DLC.
| Field | Description |
|---|---|
| お試し分数 (trial minutes) | Free play time per session. One session recovers 12 hours after use. |
| パス未所有時 1 エナジープレイ分数 (minutes per energy without pass) | Play time one energy gives a player without the title pass. |
| タイトル利用パス価格 (title pass price) | Price of the title pass. |
| タイトル利用パス購入後無料時間 (free hours after pass purchase) | Free play time after buying the title pass. |
| タイトルパス所有時 1 エナジープレイ分数 (minutes per energy with pass) | Play time one energy gives a player with the title pass. |
| DLC (YAML) | Definition of DLC. |
DLC
- Manage the DLC sold on TapFun's web pages in the Publisher Console.
- When a title pass is on sale, DLC is sold both as a "title pass bundle" and as standalone DLC for owners of the standard edition.
- Describe DLC in YAML. You can register several (there is no limit, but contact us before registering more than one).
- If the player owns DLC and the "exe launch parameters" contain
{dlcs}, the exe is launched with the DLC codes, comma-separated. With the default launch parameters this is--dlcs code,code,...(Launch parameters).
- name: Digital Deluxe Upgrade
code: digital_deluxe_upgrade
price: 3270
bundlePrice: 2000
archived: false
description: |
Upgrades the standard edition to the Digital Deluxe edition.
- Collaboration outfits (6)
- "Photo frame" camera feature (6 types)| Key | Type | Description |
|---|---|---|
name |
string | Product name. |
code |
string | DLC identifier. This is the value that goes into {dlcs}. |
price |
number | Price of the standalone DLC. |
bundlePrice |
number | Price when sold bundled with the title pass. The bundle price is the title pass price plus this amount. |
archived |
bool | When true, hidden as additional content (and as a bundle). |
description |
string | Description shown to owners of the standard edition. Line breaks are kept. |
Steam
For titles with a Steam store page, a Steam store purchase widget is shown on the play screen at PC width.
| Field | Description |
|---|---|
| Steam AppID | The Steam app ID to show. Contact TapFun to change it. |
| Tracking parameters (utm) | utm_source / utm_medium / utm_campaign / utm_term / utm_content added to links to the Steam store (up to 100 characters each). Steam only carries over these five. |
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
- In GA4 admin, find the "Measurement ID" (starting with
G-) shown on your web data stream. This is not the numeric "Property ID". - 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.
- 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
- Introduction page (
https://tapfun.co.jp/p/<app>) - Play screen (
https://tapfun.co.jp/p/<app>/play), including a play screen opened in a new tab.
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) |
- The login status at the time the page opens is attached from the first
page_view. - When a guest logs in on the screen, the value becomes
logged_infrom then on. Logging out changes it back toguest.
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
- Page views and purchases by test play accounts
- Energy purchases
- Cancellations and refunds. Check accurate sales in "Monthly sales" in the Publisher Console.
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
Title pass and DLC purchases are sent. The items values are as follows.
| Purchase | item_id |
item_name |
item_category |
|---|---|---|---|
| Title pass | pass |
The name (internal name) from the basic settings followed by " タイトルパス" | pass |
| DLC | The DLC's code |
The DLC's name |
dlc |
A title pass bundled with DLC is sent as one title pass purchase. Its value is the title pass price plus the DLC's bundlePrice.
Updating the binary
- You can upload up to 5 versions, including the one in use. Versions other than the one in use can be deleted.
- After uploading, select "First Release" in the version list to release it (Sessions during a release).
- You can launch the game with any uploaded version.
- You cannot upload another version until the newly uploaded one has been released.
- The steps are the same for the test and production environments.
- The version set as "First Release" is the one players launch. To roll back, set an earlier version as "First Release".
- After uploading, processing takes a while before the version can be used. As a guide, 1-5 GB takes up to 30 minutes. Do not upload multiple versions at the same time.
- An upload can end in the "failed" state. If deleting and retrying does not help, contact TapFun.
Sessions during a release
| Situation | Behavior |
|---|---|
| During and right after upload | Players are not affected. Players only launch the version set as "First Release". |
| When you press "First Release" | The new version is used by sessions started after the release. TapFun does not end sessions that are already running. |
| Running sessions | Sessions started before the release continue as they are. To play the new version, a player has to quit and launch the game again. To move all players to the new version, you can end the games being played with maintenance mode. |
| Save data | Kept per TapFun account and carried over when the version changes. Make sure old and new versions can read the same save data. |
| Rolling back | Press "Revert Version" on the version to go back to. It works like "First Release": it applies to sessions started afterwards. |
| Checking before release | "このバージョンで起動" (launch this version) in the version list launches an unreleased version in a new session (other players are not affected). |
The "バイナリ" (binary) tab:
- zip structure: the zip must contain a folder named after "folder", with the "exe" inside it (
<folder>/<exe>). Use the same folder and exe when you update the build. Otherwise the upload fails with "<folder>/<exe>is not included in the zip". The upload also fails, with "The top level of the zip contains something other than<folder>/", if anything other than the "folder" folder (a readme or other file, or another folder) is at the top of the zip (see Requirements for the exe). - When you cannot upload: if the screen shows "失敗したバージョンを削除してください" (delete the failed version), "不要なバージョンを削除してください" (delete unneeded versions; the limit of 5 is reached) or "First Release 待ちのバージョンがあります" (a version is waiting for First Release), follow that instruction.
- ApplicationVersions: list of uploaded versions. For each version you can use "First Release" (release), "Revert Version" (go back to an earlier version), "削除" (delete) and "このバージョンで起動" (launch this version).
- Tools → Save data download: enter a TapFun user ID to download that player's save data (do this at least 1 hour after the game exits). See Getting logs for how to find the TapFun user ID.
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 |
|---|---|
| 新規セッション (new session) | Starts the game in a new session instead of reusing the existing one. The environment from the previous play may still be used, so this cannot be used to check that save data carries over (Checking that save data carries over). |
| パフォーマンスモニタ (performance monitor) | Shows a performance monitor on the PC play screen. |
| ログ表示 (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). |
| CustomEvents | Log of requests sent through the client API (custom_event). |
| Leaderboards | Leaderboards and their entries. |
| Times | Per-player play time (free, trial, energy, total) and title pass purchase times. |
| 紹介ページ (introduction page) | Opens the game's introduction page on TapFun in a new tab. |
Cloud runtime
How it works (important)
TapFun runs the game on a server and the player controls it remotely from the browser (remote desktop model). The cloud gaming platform is built on Tencent CAR.
- The exe runs on a Windows server in the cloud (Windows Server 2019 / 2022).
- The desktop graphics and audio output are captured and streamed to a canvas element in the browser (tapfun.co.jp). Start the game in full screen.
- Mouse and keyboard input inside the canvas is sent to the exe on the Windows server.
- There is no limit on game size.
- The maximum refresh rate is 60 fps.
- Video formats playable through Windows Media Foundation are H.264 / H.265. VP9 is not supported.
- Additional asset downloads are normally not possible (they would be stored as per-user data; contact us depending on size).
- Contact us if you want to use other Tencent CAR features or APIs.
Server specs
| Plan | CPU | Memory | GPU performance | FurMark 2 1080p score |
|---|---|---|---|---|
| S | 4 cores | 8 GB | 2TF SP/30T | 2600-3200 |
| M | 4 cores | 16 GB | 4TF SP/30T | 2600-3200 |
The performance in this table is a rough guide as of when it was observed. It varies with timing and over time.
Network requirements
Requirements when your game servers communicate with the game runtime environment.
- Inbound: allow UDP 8000 and 60000-60100 from all sources.
- Source IP: the source IP of outbound HTTP and other traffic from the servers running the exe is not disclosed.
User data save and restore
User data is restored automatically at launch and saved automatically at exit. Save and restore use the Saving Application Archives feature of Tencent CAR. For the supported paths and other settings on TapFun, follow this page.
- The save/restore directory is configurable per title, and only one directory is allowed. We recommend keeping the total size within 100 MB.
- Save data is kept per TapFun account and carries over when you update the build.
- Data is saved to cloud storage after the game exits. When downloading save data from the Publisher Console, wait at least 1 hour after the game exits.
- Supported paths (under one of these):
C:\Users\%UserName%\AppData\Local\<any directory>C:\Users\%UserName%\AppData\LocalLow\<any directory>C:\Users\%UserName%\AppData\Roaming\<any directory>C:\Users\%UserName%\Documents\<any directory>C:\Users\Public\Documents\<any directory><root of the uploaded zip>\<any directory>(not recommended)
- As a rule, do not change the save data directory. After a change, the contents saved in the old directory are restored into the new directory. This can cause the game to malfunction, so after a change, restart testing with a different account, for example by deleting your TapFun account.
- We do not recommend using a directory inside the uploaded zip as the save data directory. It makes the behavior unstable, so save under one of the
C:\Users\directories above. Use a directory inside the zip only if you cannot change the save location in the exe. In that case, create a folder at least one level below the exe's folder and save there (files placed directly in the exe's folder are not saved). - Put nothing but save data and logs in the save data directory. Every file in it is saved and restored as save data. If it contains DLLs, assets or other files, the old saved copies are restored instead of the latest files from your uploaded zip, which causes bugs. If you put logs there, follow the notes in Getting logs.
%UserName%is the Windows login user name. It is fairly stable but essentially random, so only rely on it within a single session.- Tell TapFun the directory name you use. Data written to the registry is not restored. Unity's
PlayerPrefsis stored in the registry on Windows, so switch to saving to files. - There is no feature to reset save data. To check first-time-only behavior (tutorials, etc.), use another TapFun account.
- Saving does not work correctly until the save directory has been configured. Test save behavior after it is configured. See Checking that save data carries over for how to check it.
Examples of save directories:
| Engine, etc. | Example |
|---|---|
Unity (Application.persistentDataPath) |
C:\Users\%UserName%\AppData\LocalLow\<CompanyName>\<ProductName> |
| Godot 4 | C:\Users\%UserName%\AppData\Roaming\Godot\app_userdata\<ProjectName> |
| Electron (including localStorage) | C:\Users\%UserName%\AppData\Roaming\<AppName> |
| Action Game Maker | C:\Users\%UserName%\AppData\Local\<FolderName>\save |
Checking that save data carries over
Please check for yourself that save data carries over (that the save data directory is configured correctly).
If you relaunch the game within 1 hour of exiting, the environment from the previous play may be reused as is. In that case, save data appears to carry over even if the save data directory is not configured correctly. The same applies when you launch with "新規セッション" (new session) on "アプリページ" (app page). Wait at least 1 hour after exiting the game before checking.
- Launch the game in the test environment and save in the game (advance the progress, change settings, and so on).
- Exit the game.
- After waiting at least 1 hour, check in one of the following ways.
- Download the save data and check it: in the Publisher Console, enter a TapFun user ID under "Tools → Save data download" on the "バイナリ" (binary) tab, download the save data, and check that it contains what you saved in step 1. See Getting logs for how to find the TapFun user ID.
- Relaunch the game and check it: launch the game again and check that the progress and settings from step 1 have carried over.
- Even if save data carries over when you relaunch within 1 hour, that does not mean the save data directory is correct.
- If save data does not carry over after waiting at least 1 hour, the save data directory may be incorrect. Please contact TapFun.
Shader compilation results
Shader compilation results (shader caches) cannot be kept across sessions. If your game compiles shaders at startup, plan on the compilation running at the start of every session.
- The cloud PC environment is not fixed, and each session may not run on the same environment as the previous one.
- For this reason, TapFun does not keep shader caches between sessions or share them per server.
- Even if your game writes its shader cache to the save data directory so that it is saved and restored as save data, there is no guarantee it can be reused. If you save it, it counts toward the save data size (100 MB total recommended).
User data retention
| Data | Retention |
|---|---|
| Save data | Kept until the player closes their TapFun account. Deleted when the app's publication ends. |
| Images saved with the Photos API | Kept until the player closes their TapFun account, except images the player deletes on TapFun and images beyond the 1,000 limit. |
Supported input
Player input arrives at Windows in the cloud as follows.
| Player input | What the exe sees |
|---|---|
| Keyboard (PC) | Standard Windows keyboard input |
| Mouse (PC) | Standard Windows mouse input. Available for titles with "Pointer device support" enabled in the Publisher Console |
| Touch (smartphone / tablet) | Mouse clicks |
| Gamepad (PC) / virtual pad (smartphone / tablet) | A virtual gamepad (the type chosen in Gamepad input API) |
- Titles with "Gamepad support" enabled in the Publisher Console can be played from smartphones and tablets (iOS / Android) (Supported devices). Players use the on-screen virtual pad (sticks, D-pad, buttons and an Esc key button) or tap. For titles played by tapping only, enable "Gamepad support" and disable "Virtual pad default".
- Virtual pad input arrives as gamepad input, so no extra implementation is needed in the game (in Unreal Engine, the engine's gamepad settings work as-is).
- Keyboard input cannot be sent from smartphones and tablets. If a scene can only be advanced with a key (such as "Press A to start"), players on smartphones and tablets get stuck. Make it work with taps or a gamepad too.
- There is no virtual mouse cursor on touch devices. A touch arrives as a mouse click at that position. Additional fingers (multi-touch) may not be distinguished.
- Gamepad vibration is not supported.
- Gamepads and the virtual pad respond after the game screen has been clicked (tapped) once (FAQ).
Supported devices
When a player opens the introduction page, TapFun classifies the device as either "PC" or "smartphone / tablet" from browser information. Whether "Gamepad support" is enabled or disabled in the Publisher Console changes the following (Basic settings).
| Classified as | Enabled | Disabled |
|---|---|---|
| PC | Can play | Can play |
| Smartphone / tablet | Can play | Cannot play |
- For titles with "Gamepad support" disabled, the introduction page on devices classified as smartphone / tablet does not show the play buttons. Instead, it shows "このタイトルはPCブラウザ(キーボード・マウス)でのプレイ専用です。" (this title can only be played in a PC browser with a keyboard and mouse).
- On smartphones and tablets, players use the virtual pad and taps (Supported input).
- Title listings show all titles regardless of "Gamepad support".
The introduction page also shows the following, on any device.
| Introduction page item | Enabled | Disabled |
|---|---|---|
| "対応環境" (supported environments) | PC, スマートフォン (smartphone), WiFi | PC, WiFi |
| "対応デバイス" (supported devices) | Keyboard (& mouse) or gamepad | Keyboard (& mouse) |
- The mouse in "対応デバイス" is shown only for titles with "Pointer device support" enabled.
How devices are classified
| Device / browser | Classified as |
|---|---|
| Windows (including touch-enabled PCs and tablets) | PC |
| Mac | PC |
| Chromebook / Linux | PC |
| iPhone | Smartphone / tablet |
| iPad (whether Safari "Request Desktop Website" is on or off) | Smartphone / tablet |
| Android smartphone / tablet | Smartphone / tablet |
| Android Chrome with "Desktop site" turned on | PC |
The checks run in the following order, and the first one that matches decides.
- The User-Agent (
navigator.userAgent) containsWindows→ PC navigator.userAgentData.platformisiOSorAndroid→ smartphone / tablet- The User-Agent contains
iPhoneorAndroid→ smartphone / tablet - The User-Agent contains
iPad, or containsMacintoshand the device supports touch → smartphone / tablet (iPad) - None of the above → PC
- This classification is separate from isSP. Android tablets and iPads with "Request Desktop Website" on have an
isSPof0, but are classified as smartphone / tablet here.
If you want to stop play from smartphones and tablets
"Gamepad support" indicates whether a title can be played with the virtual pad or by tapping on smartphones and tablets. It is not a setting for prohibiting play on smartphones and tablets. When it is disabled, players cannot start playing from the introduction page on smartphones and tablets. However, they can still play in the following cases.
- Devices in a state that is classified as PC (such as Android "Desktop site" in How devices are classified)
- When the play screen URL is opened directly (for example, when a play screen URL opened on a PC is opened on a smartphone). The device is classified only on the introduction page, not on the play screen or on the server.
If you also want to stop it in the exe, check the {isSp} launch parameter, or isSP and userAgent from getPlayerEnvironment. Note that isSP can be 0 on tablets, and an iPad with "Request Desktop Website" on cannot be told apart from a Mac by its User-Agent (How isSP is determined).
Mouse cursor capture (FPS, etc.)
If the game captures the mouse cursor, as in FPS games, disable "Always show mouse cursor" in the Publisher Console.
- In that case, players have to press and hold the Esc key to get the mouse cursor back from the game to their own PC.
- Many games assign Esc to opening the menu and similar actions. If possible, we recommend assigning the menu to a key other than Esc.
Gamepad
Input from physical gamepads on PC and the virtual pad on smartphones and tablets reaches Windows in the cloud as one virtual gamepad. Choose "Gamepad input API" in the Publisher Console to match how your game reads gamepads (Basic settings).
| Gamepad input API | Pad type on Windows in the cloud | How the game reads it |
|---|---|---|
| XInput (default) | Xbox 360 controller | XInput |
| WGI | DualShock 4 | Windows.Gaming.Input (WGI) |
- With "XInput", the pad cannot be read through WGI. With "WGI", it cannot be read through XInput. You cannot make it readable through both.
- A change takes effect when you reopen the play screen and launch the game after saving.
Launch parameters
The exe receives the "exe launch parameters" set in the Publisher Console (Basic settings). Placeholders from the table below in that value are replaced with each player's values every time the exe is launched. Apps that integrate with the TapFun API (apps that use the Client API or the Web API) should write the placeholders they need into "exe launch parameters".
The "Set default launch arguments" button replaces "exe launch parameters" with the value below. If a value is already set, you are asked to confirm the replacement. The button does not save the value, so press "Save" afterwards.
--type car --tapfun-user-id {userId} --api-host {apiHost} --bearer-token {bearerToken} --sig-key {sigKey} --port {port} --username {username} --is-paid-timer {isPaidTimer} --is-sp {isSp} --dlcs {dlcs}With this value, the exe is launched like this:
C:\Apps\%UserName%\TapFunDebugConsoleApp.exe --type car --tapfun-user-id PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG --api-host <TEST_HOST> --bearer-token 123_AAABBBCCC --sig-key FFFGGGHHH --port 10100 --username %E3%81%82%E3%81%84 --is-paid-timer 0 --is-sp 0 --dlcs delux_upgrade,special_upgrade| Placeholder | Option in the default launch parameters | Description |
|---|---|---|
{userId} |
--tapfun-user-id |
The TapFun user ID. It is not secret, but do not display it on screen. |
{apiHost} |
--api-host |
Hostname of the Web API (e.g. tapfun.co.jp in production). |
{bearerToken} |
--bearer-token |
Bearer token for the Web API and for sending client API requests. |
{sigKey} |
--sig-key |
Signing key (sigKey) from the Publisher Console. |
{port} |
--port |
UDP port for the CAR Data Channel. Normally fixed at 10100. |
{username} |
--username |
User name. URL-encoded UTF-8, 1-12 characters after decoding, no emoji. |
{isPaidTimer} |
--is-paid-timer |
1: paid-timer user / 0: free-timer user |
{isSp} |
--is-sp |
Same value as isSP in getPlayerEnvironment. See How isSP is determined for the logic and how tablets are handled. |
{dlcs} |
--dlcs |
Comma-separated code values of the DLC the player owns. |
{lang} |
— | 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. |
--type carin the default launch parameters is fixed text with no placeholder.{lang}and{country}are not included in the default launch parameters. To use them, add them yourself, as in--lang {lang} --country {country}.- You can rename and reorder the options, and leave out the ones you do not use (for example
-screen-fullscreen 1 --user {userId}). - Placeholders are also replaced when joined with other text, as in
--user={userId}. {dlcs}is empty for players who own no DLC. When a value is empty, the option name right before it (such as--dlcs) is not passed either. If you join them as in--dlcs={dlcs},--dlcs=is passed as is.{...}not listed in the table above is passed as is.
Client API
APIs for communication between your exe and TapFun in the player's browser. Data you send passes through the player's browser, so never include secrets.
| API | Summary |
|---|---|
| openUrl | Open a URL in a new tab |
| inputTextSingleLine | Single-line text input modal |
| inputTextMultiLine | Multi-line text input modal |
| inputTextMultiLineChunkText | Send the initial multi-line text in chunks |
| copyText | Modal for copying text to the clipboard |
| showText | Text modal |
| getPlayerEnvironment | Get the player's environment |
| launchSuccessNotice | Notify successful launch |
| consoleLog | Show a log message |
| clientStatus | Client status notifications (sent automatically) |
Transport
Requests are HTTP POSTs to the TapFun API. Responses arrive over UDP that the exe listens on. Sending requires the TapFun user ID and the Bearer token. Write {userId} and {bearerToken} into "exe launch parameters" to receive them (Launch parameters).
Sending
| Item | Value |
|---|---|
| Endpoint | https://<environment hostname>/api/v1/custom_event?userId=<TapFun user ID> |
| Method | HTTP POST |
| Content-Type | application/x-www-form-urlencoded |
| Authentication | Authorization: Bearer <Bearer token> (e.g. Authorization: Bearer 123_NWU0MjlkY2ViYTVkOTdiYjIw) |
| Encoding | UTF-8 |
| Max size | 10 MB |
| Delivery to the browser | WebSocket |
Receiving
| Item | Value |
|---|---|
| Method | CAR Data Channel. Listen on local UDP port 10100 (--port) |
| Encoding | UTF-8 |
| Format | Query string (e.g. from=getPlayerEnvironment&isSP=0). Spaces are encoded as %20. |
Requests right after launch
As of 2026-11-10, the answer to a request sent within a few seconds after the exe starts may not reach the exe. The request itself reaches TapFun, so requests without an answer, such as launchSuccessNotice, can be sent right after launch.
- Send requests whose answer you use (getPlayerEnvironment, inputTextSingleLine, inputTextMultiLine) 5 seconds or more after the exe starts.
- If the answer to getPlayerEnvironment does not arrive within 3 seconds, send it again.
- Do not send again requests that show something to the player, such as inputTextSingleLine.
Sample code
Samples for Unity, Godot and .NET that read the launch parameters and call the client API and the Web API. Licensed under MIT-0.
Sending sample (Unity / C#):
public IEnumerator SendCustomEventToCar(string userId, WWWForm formData)
{
// config.apiHost = --api-host, config.bearerToken = --bearer-token
string url = $"https://{config.apiHost}/api/v1/custom_event?userId={userId}";
using (UnityWebRequest www = UnityWebRequest.Post(url, formData))
{
www.SetRequestHeader("Authorization", $"Bearer {config.bearerToken}");
yield return www.SendWebRequest();
}
}Receiving sample (Unity / C#):
private UdpClient udpServer;
private IPEndPoint udpEndPoint;
private Thread serverThread;
private int udpServerPort = 10100; // --port
private bool isDataChannelReceiveLoopRunning = false;
public void CarHandleDataChannel()
{
try
{
udpEndPoint = new IPEndPoint(IPAddress.Parse("127.0.0.1"), udpServerPort);
udpServer = new UdpClient(udpEndPoint);
isDataChannelReceiveLoopRunning = true;
serverThread = new Thread(CarDataChannelReceiveLoop);
serverThread.IsBackground = true;
serverThread.Start();
}
catch (Exception e)
{
Debug.LogError($"Failed to start UDP server: {e.Message}");
}
}
private void CarDataChannelReceiveLoop()
{
while (isDataChannelReceiveLoopRunning)
{
try
{
byte[] receivedBytes = udpServer.Receive(ref udpEndPoint);
string receivedMessage = Encoding.UTF8.GetString(receivedBytes); // query string
byte[] responseBytes = Encoding.UTF8.GetBytes("OK");
udpServer.Send(responseBytes, responseBytes.Length, udpEndPoint);
lock (queueLock)
{
receivedMessagesQueue.Enqueue(receivedMessage);
}
}
catch (Exception e)
{
Debug.LogError($"Unexpected error in receive loop: {e.Message}");
Thread.Sleep(1000); // wait a little before continuing after an unexpected error
}
}
}openUrl
Opens a URL in a new tab.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | openUrl (fixed) |
url |
✓ | URL to open in a new tab |
Response: none
inputTextSingleLine
Shows a single-line text input modal.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | inputTextSingleLine (fixed) |
label |
Label to identify the response | |
title |
Modal title | |
placeholder |
Placeholder text | |
text |
Default text (max 128 characters) | |
submit |
Submit button label | |
cancel |
Cancel button label | |
position |
Position. Centered by default; bottom for the bottom |
|
maxlength |
Max characters (default 128, max 128) | |
pattern |
Value for the HTML input pattern attribute |
|
invalid |
Message shown when the input does not match pattern (passed to setCustomValidity) |
Response:
| Key | Submitted | Cancelled |
|---|---|---|
from |
inputTextSingleLine |
inputTextSingleLine |
label |
The request's label |
The request's label |
result |
submit |
cancel |
text |
Entered text (max 128 characters) | Entered text |
inputTextMultiLine
Shows a multi-line text input modal.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | inputTextMultiLine (fixed) |
label |
Label to identify the response | |
title |
Modal title | |
placeholder |
Placeholder text | |
submit |
Submit button label | |
cancel |
Cancel button label | |
position |
Position. Centered by default; bottom for the bottom |
|
maxlength |
Max characters (default 128, max 10000; a line break counts as 1) | |
text |
Default text | |
end |
Final sequence number of the chunks sent with inputTextMultiLineChunkText |
Response: input longer than 128 characters is split into a sequence of chunks of up to 128 characters and delivered in several notifications.
| Key | Submitted | Cancelled |
|---|---|---|
from |
inputTextMultiLine |
inputTextMultiLine |
label |
The request's label |
The request's label |
result |
submit |
cancel |
text |
Entered text (max 128 characters) | — |
seq |
Sequence number (1 to end) |
— |
end |
Final sequence number | — |
inputTextMultiLineChunkText
Sends the initial text for inputTextMultiLine in chunks ahead of time. After sending all chunks, send inputTextMultiLine with end; the chunks are joined and the modal opens. Use this to send long text in parts.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | inputTextMultiLineChunkText (fixed) |
text |
✓ | Text |
seq |
✓ | Sequence number (max 100) |
Response: none
copyText
Shows a modal that lets the player copy text to the clipboard.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | copyText (fixed) |
title |
Modal title | |
text |
✓ | Text to copy |
Response: none
showText
Shows a text modal.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | showText (fixed) |
text |
✓ | Text to show |
Response: none
getPlayerEnvironment
Gets the player's environment. The answer may not arrive when it is sent right after the exe starts (Requests right after launch).
| 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 |
isPaidTimer |
1: player has paid play time remaining (1 second or more) / 0: otherwise |
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.
iPhoneiPodiPad- Both
AndroidandMobile
| 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 |
- The default of "Request Desktop Website" on iPad (Settings → Apps → Safari) differs by model. So an iPad's
isSPcan be either0or1even with the settings unchanged. - Browsers other than Safari are also determined by whether their User-Agent contains
iPad. - There is no value that indicates a tablet. To tell tablets apart, check the
userAgentfrom getPlayerEnvironment in your game. Note that an iPad with "Request Desktop Website" on sends the same User-Agent as a Mac, so the User-Agent alone cannot tell an iPad from a Mac.
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.
launchSuccessNotice
Notifies the platform that the game launched successfully. Sending it dismisses the "Starting streaming" dialog sooner.
For apps that wait for this notice, mouse input is blocked until the notice arrives or streaming has continued past a threshold. This avoids the process hanging on mouse input before it has finished starting. The timer does not run while input is blocked. We tell you in advance whether your app is one of them.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | launchSuccessNotice (fixed) |
Response: none
consoleLog
Outputs a log line. Add ?verbose=1 to the game page URL to see it in the browser's developer tools console, or ?debugLog=1 to see it in the on-screen log area (Debugging).
| 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
clientStatus
Notifies changes in client state (no request needed, sent automatically).
result |
When | Extra keys |
|---|---|---|
lastTimeRemain |
Remaining play time reached 90 seconds | second: seconds (90) |
purchaseSelectModalOpen |
The play time purchase modal was shown | — |
lastTimeInfoModalOpen |
The remaining time modal was shown | — |
manualOpen |
The controls guide was shown | — |
isPaidTimer |
The player became a paid-timer user | — |
isFreeTimer |
The player became a free-timer user | — |
Every notification includes req=clientStatus. Example: req=clientStatus&result=lastTimeRemain&second=90
Web API
HTTP APIs called from your servers or from the exe.
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).
Authorization: Bearer 123_NWU0MjlkY2ViYTVkOTdiYjIwNThmZTkxMDMzYWM4Y2JmNGUyMTQ0NgOn authentication failure the API returns HTTP 403 with:
{"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/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:
- Max images stored: 1,000. The TapFun list shows up to 1,000 images, newest first. Images beyond 1,000 are deleted over time.
- Retention: kept until the player closes their TapFun account, except images the player deletes on TapFun and images beyond the 1,000 limit.
- Max size: 10 MB per image (no overall limit)
- Max width/height: 12,000 pixels
- Max image size: 100 megapixels (e.g. 10,000 × 10,000)
- No wait between calls and no call limit
curl -F "file=@sample.jpg;type=image/jpeg" \
-H "Authorization: Bearer 1_8an4dAfsIyEEvBbaKxd55P2Wgf" \
"https://<TEST_HOST>/api/v1/photos?userId=PLYR01JY39A09EE40YQZRHWTT9EM1VDBG"// 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 |
// 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 |
// 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 |
// 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
Runtime environment
The cloud streaming server that runs and streams the exe.
TapFun user ID
- A unique ID of up to 64 characters that identifies a user. Issued per app.
- Characters:
0-9,a-z,A-Z. - Format:
PLYR+ ULID + a per-app suffix of 3-7 characters (e.g.DBG,XENO,MOCODVLP).
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).
Session
One play from launching the game in the cloud until it exits. Save data is stored when a session ends and restored when the next session starts.
Trial time
Free play time set per title ("お試し分数" in the Publisher Console). One session recovers 12 hours after use.
Energy
A unit players buy to extend play time. The play time per energy is set per title, with separate values for players with and without the title pass (Sales settings).
Title pass
A per-title right of use that players can buy. After purchase, the player can play for free for a set time. A version bundled with DLC can also be sold (DLC).
Paid-timer / free-timer user
A player with at least one second of paid play time remaining (from energy or the title pass) is a paid-timer user; otherwise a free-timer user. You can tell from {isPaidTimer} in the launch parameters or isPaidTimer of getPlayerEnvironment.
First Release
The Publisher Console operation that makes an uploaded version the one players launch (Sessions during a release).
Virtual pad
A virtual gamepad shown on the play screen on smartphones and tablets. Its input arrives at the exe as gamepad input (Supported input).
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-18 | User data save and restore now states that it uses the Saving Application Archives feature of Tencent CAR, with a link to its specification. |
| 2026-11-16 | Added to Requirements for the exe that a readme or any other file also goes inside the folder, not at the top of the zip. The Publisher Console now also rejects an upload when anything other than the folder is at the top of the zip (Updating the binary). |
| 2026-11-12 | Added to Requirements for the exe that the zip must have exactly one folder at the top, with the exe and all other files inside it. |
| 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-10 | Replaced the sample code with the public repository tapfun-sample-car (Unity, Godot and .NET). You no longer need to send us your GitHub account name to view it. |
| 2026-11-10 | Added Requests right after launch: the answer to a request sent within a few seconds after the exe starts may not arrive, and what to do about it. |
| 2026-11-09 | Added the {lang} (the player's language) and {country} (the country the player connects from) placeholders to the launch parameters. getPlayerEnvironment now also returns language and country (How country is determined). |
| 2026-11-05 | Added Supported devices, describing which devices can play depending on whether "Gamepad support" is enabled. |
| 2026-11-05 | Removed specific GPU names (the GPU model and the rough equivalents) from Server specs. Also noted that the performance in the table is a rough guide as of when it was observed and varies with timing and over time. |
| 2026-11-05 | Added why shader compilation results cannot be kept across sessions. |
| 2026-11-04 | Added How isSP is determined, including the values on tablets. |
| 2026-11-04 | Added Checking that save data carries over. Downloading save data from the Publisher Console should now be done at least 1 hour after the game exits, instead of a few minutes. |
| 2026-11-02 | Added User data retention and updated the description of the maximum number of images in the Photos API. |
| 2026-11-02 | Enabling maintenance mode in the Publisher Console now also ends games being played (How maintenance mode works). |
| 2026-10-30 | You can now choose "XInput" or "WGI" in "Gamepad input API" in the Publisher Console. The gamepad known issue has been removed. |
| 2026-10-28 | Added to Reporting issues during development which issues TapFun handles and which you handle. |
| 2026-10-28 | Added to Requirements for the exe that the folder name inside the zip and the exe file name must stay fixed. |
| 2026-10-27 | The log shown with ?debugLog=1 ("ログ表示", show log) now shows the TapFun user ID on its second line. Added how to find the ID used to download save data and logs to Getting logs. |
| 2026-10-26 | Changed the launch parameters so that you write them as placeholders (such as {userId}) in "exe launch parameters" in the Publisher Console. You no longer need to ask TapFun. The "Set default launch arguments" button sets the standard value. |
| 2026-10-26 | Added What TapFun does and the scope of support and Getting logs, and added cases to the FAQ. |
| 2026-10-23 | The issue where one gamepad input was received twice has been resolved. Added a known issue that gamepads can currently be read only through XInput. |
| 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 C:\Users\%UserName%\Documents and C:\Users\Public\Documents to the save data locations. |
| 2026-10-02 | Published this document. |