TapFun Developer Portal
Markdown JAEN

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

  1. Submit a zip file containing an executable exe.
  2. We send you a link to play it in the test environment. Check how it feels and plays.
  3. 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

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.

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

Adjusting the exe

Before release, adjust the exe as follows.

From testing to release

  1. 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.
  2. Final check in production: access to the production Publisher Console is granted separately. Before release, check the private app using Test play in production.
  3. Publish: TapFun publishes the title. The publish time can be set between 10:00 and 17:00 JST.

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.

Player support

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.

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.

Work you do in the Publisher Console

You can do the following yourself in the Publisher Console. There is no need to ask TapFun.

Out of scope

TapFun does not do the following.

Security

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:

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.

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:

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

yaml
- 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

  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

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

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:

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.

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.

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.

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.

  1. Launch the game in the test environment and save in the game (advance the progress, change settings, and so on).
  2. Exit the game.
  3. 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.

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.

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)

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

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)

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.

  1. The User-Agent (navigator.userAgent) contains Windows → PC
  2. navigator.userAgentData.platform is iOS or Android → smartphone / tablet
  3. The User-Agent contains iPhone or Android → smartphone / tablet
  4. The User-Agent contains iPad, or contains Macintosh and the device supports touch → smartphone / tablet (iPad)
  5. None of the above → PC

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.

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.

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)

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.

text
--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:

text
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.

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#):

csharp
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#):

csharp
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.

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.

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).

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

Runtime environment

The cloud streaming server that runs and streams the exe.

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).

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.

↑ Back to top