Docs

Development Troubleshooting

Prioritize troubleshooting issues by symptom using this list of frequently asked questions. If an issue involves multiple components, follow this troubleshooting order:

Account & Permissions: Developer account permissions, TikTok test accounts, target user configuration
Debugging Workflow: ttmg login, ttmg dev, QR code connection, remote debugging / real device preview / platform preview
Platform Configuration: Client Key, domain whitelist, Terms of Service, Privacy Policy, basic settings
Project Artifacts: Package size, subpackages, entry files, Unity build output directories
Capability Integration: Login, network requests, IAP, ads, revisit incentives, Unity SDK
Payment & Settlement: IAP Mock, product pricing, orders, Beans, Webhooks
Client Environment: TikTok App version, account region, device OS, network environment

If you cannot resolve the issue using this FAQ, provide the following information for further troubleshooting:

client_key
Game name
Debug mode where the issue occurs
TikTok App version
Device OS
Account region
Error messages, screenshots, or logs

What preparations are required before debugging?

Issue

You are unsure what account, tool, and platform configurations need to be completed before starting local debugging, remote debugging, real device preview, or platform QR code preview.

Solution

Complete preparations in the following order:

Install the command line tool:
Log in to your TikTok test account on the TikTok client.
Log in to your developer account on the TikTok Developer Portal.
Execute ttmg login. This step is not mandatory for all local debugging, but is required for capabilities like code upload, project detail viewing, and Unity Wasm subpackaging.
Select your mini game application in the Developer Portal and add your current TikTok test account as a test user.
Configure all request domains your game will access at runtime.
Navigate to your game project directory and execute ttmg dev to start the debugging environment.

If this is your first time debugging, you will need to enter your mini game's Client Key from the Developer Portal. The CLI will save the last used Client Key for future debugging sessions.

When to escalate

ttmg login times out or cannot complete login
Your developer account cannot view project details
The TikTok account has been added as a test user but still shows no permission
ttmg dev starts but cannot generate a QR code or connect to your mobile device

References

[TikTok Mini Game Developer Debugging Guide]

What should I do if my developer account doesn't have mini game permissions?

Issue

During debugging, you receive a message that your developer account does not have permissions for the mini game corresponding to the Client Key, or you cannot view mini game project details.

Solution

Troubleshoot in the following order:

Confirm that your currently logged-in Developer Portal account belongs to the organization that owns the mini game.
Confirm that the account has been granted developer permissions for the current mini game application.
Confirm that the Client Key used in ttmg dev belongs to the mini game you are trying to debug.
Execute ttmg login to re-authenticate the command line.
Check the project details in DevTool to confirm basic information, package size, domain configuration, Terms of Service, and Privacy Policy can be pulled normally.

If an email address is displayed in the top right corner of DevTool but project details cannot be pulled, your login session has usually expired. Re-run ttmg login and then ttmg dev.

When to escalate

You still cannot view project details after confirming account permissions
The same account can see the application in the Developer Portal but not in DevTool / CLI
You still get permission errors after changing the Client Key

Can the same developer create multiple mini games?

Issue

You want to know if multiple TikTok mini games can be created under the same developer entity or organization.

Solution

Yes, multiple mini games can be created under the same organization, but they must meet these conditions:

Different mini games must be clearly differentiated to avoid user confusion.
Mini game names, logos, and basic information cannot be duplicated or highly similar.
Each mini game must have a clear, reasonable business purpose and use case.
All mini games created under the same organization require signed contracts.
If your existing signed contract does not cover new mini games, you need to sign supplementary contracts for new games.

For testing, grey releases, or temporary integration purposes, do not create new formal mini game applications. Use test users, debug modes, preview versions, or test environments for validation instead.

When to escalate

Multiple mini games have similar names, logos, or positioning
It is unclear if your current contract covers new mini games
It is unclear if the new mini game is for formal business, test environments, or temporary validation purposes (provide organization information, existing mini game list, new game business purpose, contract coverage, and expected launch scope)

What should I do if I get a "no test permission" error?

Issue

When scanning a preview QR code or debugging locally, you get a "no test permission" error and cannot open the preview version of the mini game.

Solution

Troubleshoot in the following order:

Select the mini game application you want to debug in the Developer Portal.
Add the currently logged-in TikTok client account as a test user.
Confirm that the TikTok account you are using to scan the QR code is the same test account you added.
If you have already added the test user but still get permission errors, check if the TikTok account is a minor account. Minor accounts cannot be used for development and debugging; use an adult TikTok account instead.
Rescan the preview QR code.

Only TikTok accounts added as test users can open preview versions of mini games via QR code or enter local debugging workflows.

When to escalate

You have confirmed the account is an adult and added as a test user but still get permission errors
The test user list shows the account is added, but the scanning device still does not recognize permissions
The same account can preview one mini game but not another

How should I choose between Remote Debugging, Real Device Preview, and Platform Preview?

Issue

You are unsure which debugging mode to use during different development stages.

Solution

Choose based on your debugging objectives:

Remote Debugging (preferred during feature development):

Ideal for rapid logic development, troubleshooting script errors, and using Chrome DevTools breakpoints
Game JavaScript logic runs on your computer browser; screen and touch events are synchronized between your phone and computer

Real Device Preview (use after feature completion or when encountering performance issues):

Ideal for verifying real frame rate, memory usage, native JSAPI behavior, font rendering, and device adaptation
Game code executes natively in the TikTok client environment; no direct breakpoint support, debug primarily via vConsole and development info panel logs

Platform Preview (use before submission or to verify versions uploaded to the Developer Portal):

Requires ttmg login first
Click "Upload" in DevTool to upload artifacts to the Developer Portal, then scan the QR code on the platform details page to preview
Most closely matches the subsequent review and release workflow

When to escalate

Remote debugging works normally but Real Device Preview has exceptions
Real Device Preview works normally but Platform Preview has exceptions
Platform Preview has no requests, no data, or your server does not receive calls (these issues require distinguishing between local workflows, platform upload versions, domain whitelists, server requests, and client environments; do not assume it is a code issue directly)

What should I do if Real Device Preview won't open / stays loading / shows a QR code scanning error?

Issue

After scanning the preview QR code, the mini game won't open, stays loading, shows an error after entering, or the real device preview results do not match expectations.

Solution

Troubleshoot in the following order:

Confirm the TikTok account used to scan the code has been added as a target user / test user.
Confirm the scanning account's region matches the selected preview / release region.
Confirm your current network can normally and smoothly play TikTok videos.
Use local debugging tools to confirm your code compiles normally.
Check that the login integration process strictly follows documentation.
If using Platform Preview, confirm you have uploaded the latest code version.
If you use API requests, confirm the request domains have been configured in the Developer Portal.

If you still cannot open the game after verifying all the above, provide the following information for troubleshooting:

client_key
Game name
Scanning account region
Preview / release region
Current debug mode: Remote Debugging, Real Device Preview, or Platform Preview
Error messages, error screenshots
TikTok App version, device OS, network environment

When to escalate

Target user, account region, network, and local compilation are all normal but the game still won't open
There are consistently reproducible error messages
Issues involve login, client capabilities, runtime exceptions, or platform QR code scanning workflow anomalies
Local debugging works normally but Platform Preview won't open

How do I open logs and development information when scanning a preview QR code?

Issue

After scanning a preview QR code, you need to view logs, device information, or runtime status but don't know where to find developer options.

Solution

During platform QR code preview loading:

Tap the more button ... in the top right corner
Open the more panel
Tap Developer Options
Enable logs, device information, vConsole, or the development information panel

If tapping ... does not show Developer Options, long press ... for 20-30 seconds before opening the more panel.

Recommended settings for Real Device Preview:

Show vConsole: For viewing console.log logs
Show development information panel: For viewing runtime statistics

Developer options in production versions do not appear in the more panel by default; you need to long press the ... in the top right corner for 20-30 seconds to reveal them. Production versions have limited capabilities:

No log viewing support
No feature simulation support
Only development information overlay support

When to escalate

Developer options still do not appear after long pressing
No logs are visible after enabling vConsole
You need complete logs for production issues but cannot view them directly in the production version

What should I do if network requests are blocked due to unconfigured request domains?

Issue

Network requests within the mini game are blocked with messages that the domain is not registered or not in the whitelist.

Solution

Troubleshoot in the following order:

Add the request domain for your mini game's Client Key in the Developer Portal.
Confirm there are no trailing slashes / in your domain configuration.
Confirm requests use https (not http).
Confirm WebSocket (ws) domain configuration follows platform requirements, avoid port configurations that cause interception.
Re-run ttmg login then ttmg dev to ensure DevTool pulls the latest platform configuration.
Check domain configuration in DevTool project details to see if any domains are missing or empty.

If you disable domain verification during local debugging, unregistered domains may work normally. However, domain whitelist verification is enforced in Platform Preview and production environments, so local functionality does not guarantee Platform Preview functionality.

When to escalate

Domains are already configured in the Developer Portal but are still blocked in preview environments
Local debugging works normally but domains are blocked in Platform Preview
An email address is displayed in the top right corner of DevTool but project details or domain configuration cannot be pulled (provide client_key, full blocked URL, Developer Portal domain configuration screenshot, current debug mode, and whether DevTool can view project details)

What should I do if resource download fails?

Issue

Mini game resource downloads fail, or resource requests are blocked during debugging / preview.

Solution

Prioritize checking three types of issues:

Whether the resource domain has been added to the whitelist in the Developer Portal.
Whether the request protocol is https (HTTP requests are blocked).
Whether download resource names or paths contain spaces (paths with spaces may cause download failures).

If you disabled domain verification during local debugging, resource requests may work locally but still fail after uploading to the platform. Complete whitelist registration in the platform domain configuration before validating on real devices or Platform Preview.

When to escalate

Resource domains are configured but downloads still fail
Issue only reproduces on iOS or Android single platform
Download failures are accompanied by FileSystemManager.unzip errors or resource decompression exceptions (provide full resource URL, error logs, device OS, TikTok App version, and current debug mode)

What should I do if code pre-check shows package size exceeds limits?

Issue

DevTool code pre-check indicates the total package, main package, or independent subpackage exceeds size limits, or upload to the platform fails.

Solution

First distinguish your project type:(Refer to the size limit table in the original document)

Then process according to type:

Total package exceeds limit:

Move non-first-screen required resources and logic into subpackages
Clean up duplicate resources, unused resources, textures, audio, and large JSON files
For Unity projects, focus on controlling overall resource size and Wasm / data file sizes

Main package exceeds limit:

Keep only the minimum working set in the main package
Migrate large resources and non-first-screen features to subpackages
Avoid having the same resource in both the main package and subpackages

Independent subpackage exceeds limit:

Further split independent subpackages
Move unnecessary resources to regular subpackages
Consider on-demand pulling or lazy loading for non-first-screen resources

Package size issues only show warnings during local development, but will cause upload failures if not resolved before platform upload.

When to escalate

The main package size reported by DevTool does not match expectations
Main package is still counted as too large after configuring subpackages
Unity projects trigger Wasm function count warnings (provide project type: Unity / Cocos / Laya / other, DevTool pre-check screenshot, game.json subpackage configuration, and project directory structure)

What should I do if the main package size is still incorrect after configuring subpackages?

Issue

Subpackages are configured, but DevTool pre-check shows the main package size does not match expectations, or the first package size verification is incorrect after Laya export.

Solution

First check if the subpackage field in game.json is all lowercase subpackages.

Correct format:

{
  "subpackages": [
    {
      "name": "level1",
      "root": "subpackages/level1"
    }
  ]
}

Do not use subPackages (capital 'P'). If you use subPackages, these files may be counted towards the main package, causing first package / main package size verification anomalies and even preventing platform upload.

Continue checking:

Each subpackage has non-empty name and root fields
Each root corresponds to an existing local directory
Subpackage paths only use valid characters: A-Za-z0-9 _ - . / \
Independent subpackages have independent: true set

When to escalate

Statistics are still abnormal after using subpackages
Engine build output directory does not match game.json configuration
Subpackage directory exists but DevTool reports invalid path

What should I do if required capability pre-check fails?

Issue

DevTool code pre-check indicates required capabilities are not integrated, for example, login is not implemented.

Solution

First confirm the required capabilities for your mini game. Key capabilities include:

Silent user login: TTMinis.game.login
Rewarded video ads: TTMinis.game.createRewardedVideoAd
Home screen shortcut: TTMinis.game.addShortcut, TTMinis.game.getShortcutMissionReward
Profile / TikTok Minis entrance missions: TTMinis.game.startEntranceMission, TTMinis.game.getEntranceMissionReward

If login pre-check fails, confirm:

Frontend calls TTMinis.game.login
code is successfully retrieved
code is sent to your backend
Backend calls POST /v2/oauth/token/ to exchange for open_id and tokens
Terms of Service and Privacy Policy URLs are filled in the Developer Portal

When to escalate

Capabilities are already integrated but pre-check still fails
login call fails or no code is returned
Backend token exchange reports errors
Pre-check prompts do not match actual code

What should I do if TTMinis.game.login reports an error?

Issue

Frontend call to TTMinis.game.login fails, common symptoms include no code returned, scope not matching expectations, or invalid parameters.

Solution

Troubleshoot in the following order:

Check if Terms of Service and Privacy Policy are filled in:

Calling login may directly fail if these are not completed
If official links are not ready, you can use temporary placeholder links and replace them later

Verify Client Key and Client Secret come from the same TikTok mini game application:

Do not mix App IDs / Keys from Lark, Douyin, or other platforms
Do not copy only the Key without updating the corresponding Secret

Check if scope is correct:

Requested scopes must be applied for and approved in the Developer Portal app permissions list
No additional user information authorization is required if you only need open_id

Confirm frontend only retrieves code:

Frontend calls TTMinis.game.login to get AuthorizationCode
Frontend sends the code as-is to your backend
Backend calls TikTok Open API to exchange for AccessToken, RefreshToken, and OpenID

Ensure OAuth is not called directly on the frontend:

Do not call Open API to exchange tokens directly from the frontend
Do not manually call interfaces after OCR recognition of codes or tokens

When to escalate

Backend reports client_key, client_secret, or parameter mismatch
Backend reports code has expired, been used, or cannot be exchanged for tokens
Backend token interface returns missing parameters or unexpected format
Business process cannot recover after user cancels authorization (provide frontend login error information, backend token interface response, current client_key, whether Terms of Service and Privacy Policy are filled, and scope parameters)

Why can't I get an AccessToken?

Issue

Frontend calls login and gets code, but backend cannot exchange it for AccessToken / OpenID.

Solution

The OAuth flow must be completed by your backend:

Frontend calls TTMinis.game.login to get code
Frontend sends code to your backend via HTTPS
Backend calls:
Use request header:
Set grant_type to authorization_code

Key checks:

client_key and client_secret match
Code is used within its validity period
Code is not reused
Parameters are not incorrectly encoded or decoded
Request is initiated from the backend, not the frontend

Code is a one-time, short-lived credential, usually valid for 5 minutes. Expired or reused codes will cause token exchange failures.

When to escalate

Backend reports client information mismatch
Backend reports code has expired or been used
Backend reports missing parameters or unexpected format
Frontend cannot get code

15. What should I do if AccessToken expires?

Issue

After running for some time, calls to authorized Open APIs fail or return 401.

Solution

AccessToken is not permanently valid. Handle it as follows:

Backend saves open_id, access_token, refresh_token, and expiration times
Backend proactively refreshes AccessToken 10-30 minutes before it expires
Use refresh_token to call:
After successful refresh, immediately invalidate old tokens and persist the new access_token and refresh_token
If the refresh interface indicates refresh_token is unavailable (refresh_token expired, user revoked authorization, or exceeded validity period), have the frontend re-trigger TTMinis.game.login

If your business only needs open_id, you still need to complete the token exchange process once. After getting OpenID, you can persist only the OpenID; if you don't need payments, leaderboards, social features, or user profile information, you don't need to maintain AccessToken afterwards.

When to escalate

Cannot re-login after 401 error
refresh_token frequently expires
Business cannot gracefully handle user authorization cancellation

How to handle request compatibility issues on older iOS versions?

Issue

On iOS client versions before 42.7.0, request may have compatibility issues such as POST strings being wrapped, GET return values being automatically deserialized, or GET query parameters being abnormal.

Solution

Handle according to issue type:

iOS POST request strings are automatically wrapped with data:Do not pass strings directly as data:Use an object field instead:
iOS GET return data is automatically deserialized, causing JSON.parse errors in business code:Option 1: Specify dataType: "string" in the request:Option 2: Implement safe parsing in your business logic:
iOS GET requests with common parameters cause missing query parameters:Adjust relevant GET requests to POST requests and pass parameters through data.

When to escalate

Only reproduces on iOS
Only reproduces on older client versions
Still abnormal after adjusting request method (provide client version, device OS, request example, interface response example, and error stack)

What should I do if FileSystemManager.unzip errors prevent game loading?

Issue

Calling FileSystemManager.unzip on iOS or Android reports errors, causing game resources to fail decompression or the game to fail loading normally.

Solution

Short-term fix: Adjust how your game consumes files to avoid dependency on unzip.Long-term fix: Wait for FileSystemManager.unzip API support on iOS / Android before restoring this capability.

If decompression failures occur during startup, prioritize checking:

Whether you can pre-unpack files during the build phase
Whether you can replace runtime decompression with subpackages or on-demand resource loading
Whether you can adjust resource organization to avoid strong dependency on unzip for the first screen

When to escalate

Consistently reproduces on one OS
Only specific resource packages fail to decompress
Still cannot start after replacing resource loading methods (provide device OS, TikTok App version, resource package size, resource path, error logs, and reproduction steps)

How to determine if an API or capability is unavailable due to version support?

Issue

A JS API or platform capability call fails, and you are unsure if it's a code issue, client version issue, or the capability is not yet available.

Solution

First confirm the API module, then check version, namespace, and prerequisites.

TikTok Mini Game JS API Reference supports tt, wx, and TTMinis.game namespaces. For example, TTMinis.game.login is equivalent to tt.login and wx.login. This FAQ uses TTMinis.game as the example namespace.

Common API modules include:

Basic: canIUse, env
System: getSystemInfoSync, getSystemInfo, getWindowInfo
Lifecycle: onShow, onHide, getLaunchOptionsSync, getEnterOptionsSync
Subpackage loading: preDownloadSubpackage, loadSubpackage
Sharing: shareToStory, shareAppMessage
Device: Keyboard, network, touch, vibration, memory related APIs
Rendering: Canvas, frame rate, fonts
File: getFileSystemManager and related FileSystemManager methods
Data storage: setStorage, getStorage, removeStorage, etc.
Network: request, downloadFile, connectSocket
Open interfaces: login, authorize, open data domain, open data
Payment: pay, navigateToBalance
Ads: Rewarded ads, interstitial ads
Revisit incentives: startEntranceMission, getEntranceMissionReward, addShortcut, getShortcutMissionReward
Media: Audio related APIs

Prioritize using canIUse for version compatibility checking. canIUse supports checking APIs, object properties, interface parameters, callback parameters, and return value fields:

TTMinis.game.canIUse("env.USER_DATA_PATH");
TTMinis.game.canIUse("getSystemInfoSync.return.safeArea.left");
TTMinis.game.canIUse("getSystemInfo.success.screenWidth");
TTMinis.game.canIUse("request.object.method.GET");

Before calling specific capabilities, check if the API is available:

if (TTMinis.game.canIUse("addShortcut")) {
  TTMinis.game.addShortcut({
    success: () => {
      console.log("success");
    },
    fail: error => {
      console.log("fail", error);
    },
    complete: () => {
      console.log("complete");
    }
  });
}

For APIs marked "Supported from base library x.x.x, compatibility handling required for lower versions", you must perform compatibility checks before calling. Examples:

getWindowInfo: Supported from base library 0.2.0
getMenuButtonBoundingClientRect: Supported from base library 0.3.0
Keyboard related APIs: Supported from base library 0.6.0
WebSocket: Supported from base library 0.4.0
File system open, read, write, rmdir, readdir, unlink, etc.: Mostly supported from base library 0.15.0
File status, rename, save file, etc.: Mostly supported from base library 0.16.0
appendFile, truncate, compressed file reading, zip entry reading, etc.: Mostly supported from base library 0.18.0
Storage information query: Supported from base library 0.8.0

For capabilities with explicit client version restrictions, also confirm the TikTok App version. For example, friend sharing capabilities only work when the client version meets requirements, which should be checked via TTMinis.game.canIUse("shareAppMessage").

Troubleshooting order:

Confirm the capability has been officially launched
Confirm the current client version meets requirements
Confirm the base library version meets the API minimum requirement
Use canIUse to check if the API, parameters, callbacks, or return fields are available
Confirm you are using the correct namespace (prioritize TTMinis.game)
Check error information in the fail callback
Check if specific platform configurations, permissions, account status, or backend capabilities are required

When to escalate

canIUse returns available but the call fails
Only fails on specific platforms, regions, or accounts
Fail callback returns unexplained error messages
API documentation specifies a minimum base library version but you cannot confirm the runtime base library version
A specific parameter or callback field is unavailable but the API itself works

How to debug revisit incentives?

Issue

After integrating home screen shortcut or profile sidebar entry rewards, you don't know how to simulate the entry and debug reward distribution results.

Solution

Use ttmg dev to open the debugging environment:

cd path/to/your/game
ttmg dev

Debug profile sidebar entry rewards:

In DevTool, select New Startup Mode
Set the startup mode to Sidebar Entry
Scan the QR code to simulate launching from the sidebar entry
Call TTMinis.game.getEntranceMissionReward to check reward distribution results

Example:

TTMinis.game.getEntranceMissionReward({
  success: ({ canReceiveReward }) => {
    console.log("success", canReceiveReward);
  },
  fail: () => {
    console.log("fail");
  },
  complete: () => {
    console.log("complete");
  }
});

Debug home screen shortcut entry rewards:

In DevTool, select New Startup Mode
Set the startup mode to Home Screen Shortcut Entry
Scan the QR code to simulate launching from the shortcut entry
Call TTMinis.game.getShortcutMissionReward to check reward distribution results

Example:

TTMinis.game.getShortcutMissionReward({
  success: ({ canReceiveReward }) => {
    console.log("success", canReceiveReward);
  },
  fail: error => {
    console.log("fail", error);
  },
  complete: () => {
    console.log("complete");
  }
});

When to escalate

Entry scene does not match expectations after configuring startup mode
canReceiveReward does not match expectations
Fail callback returns error information (provide startup mode configuration, scene, query, API callback logs, and current TikTok App version)

How to enable Mock for IAP payment debugging?

Issue

After integrating IAP payments, you need to verify the payment flow during development or preview without real charges.

Solution

You can enable payment Mock in local debugging or platform QR code preview:

Local development debugging:

Enter your project root directory
Execute ttmg dev
In the debug page opened in your computer browser, go to Developer Options
Check "Enable payment Mock"

Platform QR code preview:

Generate a preview QR code through the Developer Portal
Scan with TikTok to enter real device preview
Open Developer Options
Check Enable IAP Mock

After enabling:

No real charges are made during the payment flow
The payment panel shows a Sandbox environment indicator
Clicking payment simulates successful payment
Your backend receives a Webhook callback with the is_sandbox: true flag

When processing test orders, your backend must verify the is_sandbox flag to avoid treating test orders as real payment orders.

When to escalate

Real charges still occur after enabling Mock
Payment panel does not show Sandbox environment indicator
Frontend success callback is triggered but backend does not receive Webhook
Payment result polling API reports errors (provide current debug mode, whether Mock is enabled, payment callback logs, Webhook logs, trade_order_id, order_id, and domain whitelist configuration)

What should I do if the IAP payment page shows "An error occurred, please try again later"?

Issue

IAP reports an error on the "Recharge and Unlock" page, or store product information query fails.

Solution

This issue is usually related to region settings. Check in the following order:

Phone system region is a supported region (e.g., US or JP)
App store account region is a supported region (e.g., US or JP)
Current IP address is in a supported region
Do not use regions where payment is not enabled (CN or HK) for payment debugging
For real payments, confirm IAP capabilities are enabled in the backend and you have completed enterprise verification and payment capability activation

The payment flow also depends on login capabilities. Before integrating payment, you need to get a code via TTMinis.game.login and have your backend exchange it for AccessToken and OpenID.

When to escalate

Region, store account, and IP are all switched to supported regions but errors still occur
Order is created successfully but frontend TTMinis.game.pay call fails
Behavior differs between Sandbox, review environment, and production environment (provide phone system region, store account region, IP, trade_order_id, frontend error information, backend order creation response, and current environment)

Can I deliver virtual items directly after frontend payment success?

Issue

After the frontend payment success callback is triggered, you want to know if you can immediately give players virtual goods, coins, or entitlements.

Solution

Do not rely solely on frontend success callbacks for entitlement delivery.

Correct flow:

Backend creates a prepayment order and gets trade_order_id
Frontend calls TTMinis.game.pay to initiate payment
After frontend success or complete callback, you can start polling for order status
Backend uses the Webhook callback minis.trade_order.redeem.success as the only basis for entitlement delivery
Backend verifies the Webhook signature
Backend performs idempotency processing based on trade_order_id or your business order_id to avoid duplicate delivery
Backend updates player assets only after confirming order success

The frontend success callback only indicates the client payment process has completed; it does not mean the backend has confirmed payment completion.

When to escalate

User does not receive entitlements after frontend success
Webhook not received or signature verification fails
Duplicate Webhooks received for the same order
Test orders are mistakenly treated as real orders

What should I note before debugging Unity mini games?

Issue

Unity mini games cannot run, cannot be debugged, or uploaded artifacts do not meet expectations.

Solution

Prioritize confirming these prerequisites:

TikTok Android / iOS client version ≥ 43.1.0
Use Unity 2021-2022 versions
Import the TikTok Unity plugin
Unity build output directory is tt-minigame
Execute ttmg dev in the tt-minigame directory following the debugging guide
Upload the tt-minigame folder when publishing
Unity total package size ≤ 60 MB
If DevTool indicates wasmFuncCount >= 80000, optimize startup performance using the Wasm splitting process

Other APIs can only be called after the Unity SDK is initialized:

TT.InitSDK((code, env) =>
{
    if (code == 0)
    {
        Debug.Log("SDK initialized successfully");
        // Call other APIs after this point
    }
});

(Refer to initialization error code table in original document)

When to escalate

TikTok App version meets requirements but Unity game still won't start
InitSDK returns code 1 or 2
Debugging in the tt-minigame directory fails
Package size is under 60 MB but upload fails
Real device startup is still slow after Wasm splitting (provide Unity version, TikTok App version, SDK plugin version, InitSDK return code, artifact directory structure, and DevTool pre-check screenshot)

What should I do if Login fails in Unity?

Issue

Unity mini game call to TT.Login fails, or cannot get the code for backend OpenID exchange.

Solution

Troubleshoot in the following order:

Confirm TT.InitSDK has completed and returned code 0
Confirm you are running in a real TT Container environment, not the editor or non-container environment
Call TT.Login to get temporary login credentials
Send the code to your backend
Backend calls TikTok Open API to exchange for OpenID / AccessToken

Example:

TT.Login(
    successCallback: code =>
    {
        Debug.Log($"Login successful, code: {code}");
    },
    failedCallback: errMsg =>
    {
        Debug.Log($"Login failed: {errMsg}");
    }
);

If Unity gets the code but backend token exchange fails, continue troubleshooting according to the OAuth flow in the login FAQ.

When to escalate

TT.InitSDK did not succeed
Current environment is not a real TT Container
No code returned from Unity side
Backend token exchange reports errors

What should I do if Remote Debugging or Real Device Preview is laggy?

Issue

Remote Debugging screen is laggy, iOS package runs with frame drops, or Real Device Preview is sluggish.

Solution

First distinguish the debug mode:

Remote Debugging lag:

Remote Debugging depends on Wi-Fi and computer browser performance; screen synchronization may be affected by network latency
Suitable for logic development and breakpoint debugging, not for final performance judgment
Switch to Real Device Preview to verify actual performance when encountering lag

Real Device Preview lag:

Real Device Preview most closely matches actual user experience
Enable the development information panel to view runtime statistics
Diagnose issues based on FPS, memory, resource loading, and first screen time

Unity game lag:

Pay attention to total package size, data / wasm file sizes
If wasmFuncCount >= 80000, optimize startup performance using the Wasm splitting process

When to escalate

Real Device Preview consistently lags
Only iOS experiences frame drops
Unity first screen loading is noticeably slow
Lag is related to specific scenes, resource loading, or capability calls (provide current debug mode, device model, TikTok App version, FPS / memory performance, reproduction steps, and performance screenshots)

What should I do if local debugging works normally but platform preview is abnormal?

Issue

Local debugging works normally, but after uploading to the Developer Portal, QR code testing has no data, your server receives no requests, or platform preview behavior differs from local.

Solution

Distinguish the issue layer in the following order:

Confirm you uploaded the latest code package
Confirm Platform Preview uses the currently uploaded version
Confirm the scanning account has been added as a test user
Confirm the scanning account region matches the preview / release region
Confirm platform domain whitelist has been configured
Confirm if you disabled domain verification during local debugging (if disabled, local functionality does not guarantee Platform Preview functionality)
Confirm your server has received request logs
Confirm frontend requests are actually sent (check via vConsole or logs)

Do not assume these issues are caused by developer code directly; distinguish between local, platform, server callback, domain configuration, and environment configuration issues.

When to escalate

Platform scan has no requests but local has requests
Platform scan has frontend logs but server has no logs
Domain whitelist is configured but still no requests
Only reproduces on specific region accounts or devices (provide platform upload records, QR code source, frontend logs, server logs, domain configuration screenshot, account region, and device information)

What should I do if ttmg login command line cannot log in?

Issue

When executing ttmg login, you encounter network timeouts, long periods of no response, 503 errors, account password verification failures, or the browser can access TikTok / Google but the command line cannot log in.

Solution

First use an API request to determine if the issue is "command line network connectivity" or "account password error".

Windows PowerShell test:

curl.exe -sS -L "https://developers.tiktok.com/passport/web/email/login?aid=2471&account_sdk_source=web&sdk_version=2.1.6-tiktok" `
  -H "Content-Type: application/x-www-form-urlencoded" `
  -H "Accept: */*" `
  -H "Origin: https://developers.tiktok.com" `
  -H "Referer: https://developers.tiktok.com/passport/web/email/login" `
  --data-urlencode "email=your_email@example.com" `
  --data-urlencode "password=your_password" `
  --data-urlencode "mix_mode=1" `
  --data-urlencode "fixed_mix_mode=1"

Interpret results:

If there is a long period of no response or direct error: The command line cannot access the external network. Prioritize checking proxy / VPN / system network configuration.
If the interface returns normally but ttmg login still fails: Usually the VPN proxy does not cover command line tools.
If the interface returns account or password related errors: Network is working, prioritize checking Developer Portal account, email, and password.

Command line network connectivity troubleshooting:

Switch VPN from rule mode / PAC mode to global mode to ensure command line requests go through the proxy.
If your VPN client supports TUN mode / enhanced mode, enable TUN mode first.
Confirm the VPN client has "System Proxy" enabled.
Confirm current HTTP / HTTPS proxy port, avoid environment variables pointing to old ports after port changes.
Temporarily close other VPNs, network accelerators, or security software, keep only one VPN running.
If you get 503 errors, switch VPN nodes first; if still unstable, use a more reliable VPN client or service.
Check if firewall or third-party security software is blocking VPN, Node.js, or DevTool.
If still unable to access, check DNS configuration, try changing DNS settings in the VPN client.

Windows manual proxy environment variable setup (using proxy port 7890 as example):

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

Or add these system environment variables:

http_proxy=http://127.0.0.1:7890
https_proxy=http://127.0.0.1:7890

Restart your terminal and re-run ttmg login.

macOS manual proxy environment variable setup:First check your current network proxy port in system settings. For zsh users, edit ~/.zshrc (using proxy port 7897 as example):

export https_proxy=http://127.0.0.1:7897 http_proxy=http://127.0.0.1:7897 all_proxy=socks5://127.0.0.1:7897

Save and execute:

source ~/.zshrc

Then re-run ttmg login.

When to escalate

curl test has no response, and still cannot access after switching global mode, TUN mode, and system proxy
ttmg login consistently returns 503
curl test returns normally but ttmg login still times out
Network is confirmed to be working but account or password errors are reported
Firewall, security software, or company proxy policies cannot be adjusted (provide full ttmg login error, curl test results or screenshots, computer OS, VPN client name, proxy mode, whether TUN / system proxy is enabled, current HTTP / HTTPS / SOCKS proxy ports, and whether you are using company network, company proxy, or security software)

What should I do if my phone cannot connect to local debugging via QR code?

Issue

After scanning the local debugging QR code with TikTok, there is no response, it stays on connecting, shows "client debug service connection failed", or DevTool still shows no connection after scanning.

Solution

First use the two built-in DevTool tools:

Basic Debugging Guide: /basic_debug_guide

Basic QR code debugging can continue even if CLI login fails or there is no developer login session
You can still use QR code debugging, startup modes, browser preview / client preview, network diagnostics, and manual connection
Project overview, upload and release, and platform capability verification require restored CLI login
Recommended workflow: First get local package and QR code scanning working; if scanning has issues, use network diagnostics or manual connection first, don't assume all issues are login issues; handle network / proxy issues and re-run ttmg login / ttmg dev only when platform capabilities are needed

Network Connectivity Diagnostics: /network_diagnostics

Used to diagnose scanning stuck, connection failures, port unreachable, and other network issues
Diagnostics sequentially check local Node service, client HTTP, and client WebSocket
Diagnostic conclusions distinguish: "Missing client debug address", "Local debug service not ready", "Client link completely unreachable", "Client WS link abnormal", "No obvious network abnormalities found"
If the scanning link is unavailable, go directly to manual connection and enter the Client IP, HTTP port, and WS port displayed on the client loading page

Local debugging QR code workflow:ttmg dev generates a debugging schema with core parameters:

host: Computer LAN IP
port: Local Node WebSocket port
host_list: List of available LAN IPs on your machine
debugMode: Debug mode (Remote Debugging / Real Device Preview, etc.)

After scanning, the link is established in this order:

TikTok client scans the QR code and reads host, port, debug mode, and startup parameters
Client sends scanning results back to local Node WebSocket
After Node receives scanQRCodeResult successfully, it gets the client debug service's clientHost, clientHttpPort, clientWsPort
DevTool browser connects to client WebSocket: ws://clientHost:clientWsPort
The local debugging link is fully established only after the browser to client WS connection succeeds

QR code connection failures need to be diagnosed at each layer, not just based on "whether the QR code was scanned".

Troubleshooting order:

Confirm ttmg dev is running in your project root directory
Confirm DevTool can access local Node HTTP: /game/config
Confirm DevTool can connect to local Node WS: ws://localhost:<nodeWsPort>
Confirm host in the QR code is not 127.0.0.1 or localhost (phone cannot access local services with loopback addresses)
Confirm computer and phone are on the same Wi-Fi / same LAN segment
Prioritize using Wi-Fi adapter IP. CLI filters out virtual network adapters (Docker, VMware, TUN, TAP, WireGuard, Tailscale, etc.) and prefers wireless adapters, then wired adapters
If DevTool shows "No LAN IP detected for QR code scanning", first disable VPN / proxy / firewall blocking, or use manual connection
If no client IP, HTTP port, and WS port are returned after scanning, the client debug service address was not successfully returned; use manual connection
If client addresses are obtained, run network diagnostics to check the four links:

IDE ↔ Node (HTTP): /game/config
IDE ↔ Node (WS): ws://localhost:<nodeWsPort>
IDE ↔ Client (HTTP): http://<clientHost>:<clientHttpPort>/game/scripts/krypton.js
IDE ↔ Client (WS): ws://<clientHost>:<clientWsPort>

Result-based troubleshooting:

Missing client debug address:

Rescan the QR code first
If still no client IP / HTTP / WS ports, use manual connection

IDE ↔ Node HTTP or WS failed:

Local debug service is not ready
Confirm ttmg dev is running
If you just changed network or proxy configuration, go back to project root and re-run ttmg dev
Check if local ports are occupied

IDE ↔ Client HTTP and WS both failed:

First confirm phone and computer are on the same Wi-Fi / network segment
Company networks may have AP isolation preventing device access even on the same Wi-Fi
Disable global VPN / TUN
Proxy tools need to enable "Allow LAN" connections
Check system firewall allows Node.js and LAN access
Confirm client is on the debug loading page and client debug service is enabled

IDE ↔ Client HTTP reachable but WS unreachable:

First check WS port is correct
Confirm client debug service is listening on the WS port
WS timeouts are usually caused by ports being blocked by firewalls, routing policies, VPN / TUN, or proxies
Rescan QR code or re-enter WS port in manual connection

All four links are reachable but still cannot debug:

No obvious network layer abnormalities
Go back to scanning page and rescan
If still failing, check startup mode, client version, resource compilation, capability calls, or upper-level runtime logic

Manual connection method:

Open DevTool "Network Diagnostics" or "Manual Connection"
Enter values from the client loading page:

Client IP
Port 1 (HTTP port)
Port 2 (WS port)

Click Manual Connection
DevTool first checks ws://Client IP:WS port quickly, then runs full network diagnostics

Manual connection limitations:

Only supports TikTok Android 42.9 and above
iOS does not support manual connection to client debug service

When to escalate

host in QR code is 127.0.0.1, localhost, or no available host_list
Phone and computer on same Wi-Fi but client HTTP / WS are unreachable
HTTP reachable but WS unreachable
Company network has AP isolation preventing phone access to computer
Still unreachable after disabling VPN / TUN / firewall
Manual connection also fails (provide computer IP, HTTP port, WS port from QR code page, Client IP, HTTP port, WS port from client loading page, network diagnostics four results screenshot, whether using VPN / TUN / proxy / company network, computer OS, phone OS, TikTok App version, and ttmg dev terminal logs)

Which login scheme should I choose?

Issue

When integrating TikTok Mini Games, you are unsure if login is mandatory, when to use silent login, and when to request user information authorization.

Solution

Choose a login scheme based on your business needs:

If you don't need user data, you don't need to integrate login.
If you only need the user's OpenID, use silent login. Frontend calls TTMinis.game.login at an appropriate time, and the backend completes the OAuth flow to get AccessToken and OpenID. Silent login does not show authorization popups, and the IAP flow can be executed based on this result.
If you need additional user information like username or avatar, call TTMinis.game.authorize with the corresponding scope only when necessary. Do not request additional authorization immediately after game launch, as user rejection may block core flows.
If you need sensitive user information like email or phone number, contact your BD and complete more complex compliance processes.

login is used to get basic identity
authorize is used to get additional permissions only when business needs require them
When authorize fails, use login as a fallback to avoid losing basic login information

When to escalate

Unclear whether business needs OpenID, basic profile, or sensitive information
Authorization is triggered immediately on app launch, and users cannot continue after rejection
Payments, leaderboards, social features, or other capabilities depend on identity but no clear login scheme is defined (provide business scenario, required user fields, whether IAP is involved, whether Open API is used, authorization trigger timing, and fallback process after rejection)

What should I do if a user rejects or cancels authorization?

Issue

User rejects additional authorization, manually cancels authorization, or subsequent Open API calls indicate authorization expiration.

Solution

Handle according to authorization type:

Silent login is user-transparent and cannot be actively rejected.
After silent login completes, if you request additional permissions, users can reject them. Rejection of additional authorization should not affect the basic identity already obtained via silent login.
After a user agrees to additional authorization, the new AccessToken replaces the previous AccessToken.
After a user manually cancels authorization, relevant permissions become invalid; when the backend finds authorization expired during Open API calls, notify the frontend to re-trigger login or authorization.

Handling principles:

Use login as fallback for basic identity
Request additional information only when needed, not in advance
Provide a degraded user experience that allows continued use after authorization rejection
When backend Open API calls fail, do not retry Open API directly on frontend; return to the login / authorization flow to get valid credentials

When to escalate

Game cannot be entered after user rejects avatar / nickname authorization
Backend continues using old AccessToken after user cancels authorization
No re-login fallback after authorization failure (provide authorization scope, page where authorization is triggered, product flow after user rejection, backend Open API response, and whether re-login fallback exists)

How to get current TT UID and account region?

Issue

When debugging or troubleshooting account issues, you need to know the current TikTok account's TT UID or determine the account's region.

Solution

TT UID can be displayed by repeatedly tapping the version number in the TikTok App settings page. After getting the TT UID, provide it to the operations team to help query the account region if needed.

Distinguish between different identifiers:

OpenID: Developer-side identity within the mini game, associated with Client Key
TT UID: TikTok account identity, used internally for locating accounts, regions, or test user issues
Account region / store region / phone system region: All need to be confirmed when troubleshooting payment, IAP, or regional grayscale issues

When to escalate

Test user is added but still shows no permission
IAP or account capabilities are abnormal only on a specific account
Need to confirm account region, store region, or operations-side whitelist (provide TT UID, TikTok account, account region, device OS, TikTok App version, client_key, and issue screenshots)

How to manage IAP products and pricing?

Issue

When integrating IAP, you are unsure if you need to pre-register products on third-party platforms, maintain product prices, or handle Beans tiers.

Solution

TikTok currently does not require developers to pre-register in-game product content and corresponding prices on third-party platforms. When creating an order, pass the number of Beans to be consumed in the token_amount field of the TikTok Open API.

Pricing and tier rules:

The reference conversion is 100 Beans = 1 USD, but after taxes and channel fees, the actual user payment may be 100 Beans = 1.5 USD.
Beans prices should be as consistent as possible across currencies, so no fixed local currency price is provided.
If you need to query the price of a specific tier in the user's account country, use the TikTok Open API to query specified tier information.
If product prices exceed current Beans tier limits, contact sales or BD to apply for higher Beans tiers.

When to escalate

Product prices need to be mapped to multiple countries or currencies
Need to exceed current Beans tier limits
Unsure about token_amount, product name, or business order fields during order creation (provide product list, expected prices, target regions, Beans amounts, whether higher tiers are needed, and order creation parameters)

Can payment orders be reused?

Issue

You want to reuse already created payment orders, or reuse the same order for retry after payment failure.

Solution

Payment orders cannot be reused.

After a payment order (trade_order_id) is created, order fields should not be changed. After an order is successfully paid, it cannot be paid again. For new payments, you must create a new order with correct:

token_amount
order_id
product_name

Order processing principles:

Create a new payment order for each new purchase
Keep business-side order_id unique, avoid mixing with historical orders
Backend performs idempotency processing based on trade_order_id or business-side order_id
Do not reuse already successfully paid orders just because frontend payment failed or the payment panel was closed

When to escalate

Same order_id is used multiple times
Backend order status is inconsistent after frontend repeatedly initiates payment
Duplicate Webhook callbacks cause duplicate entitlement delivery (provide trade_order_id, order_id, order creation response, frontend payment results, Webhook records, and entitlement delivery records)

How to count Beans recharge and consumption?

Issue

You are unsure how much Beans users actually recharged, how much Beans they consumed, and which number to use for developer revenue statistics.

Solution

Distinguish between recharged Beans and consumed Beans:

When users have no Beans balance, they will recharge and consume Beans directly.
When users have sufficient Beans balance, they will consume directly from the balance.
When users have insufficient Beans balance, they will recharge the nearest available tier to cover the required amount, then consume the needed Beans.

Example:

User has 50 Beans balance, needs 99 Beans: User will be prompted to recharge 100 Beans; after successful recharge, 99 Beans are consumed, leaving 51 Beans balance.
User has 100 Beans balance, needs 99 Beans: 99 Beans are consumed directly, leaving 1 Bean balance.

Developer revenue is only counted based on the number of Beans consumed within the corresponding mini game. For example, if a user recharges 100 Beans and spends 90 Beans in your game, developer revenue is calculated based on the amount corresponding to 90 Beans.

Actual consumption, refunds, and test orders should be based on backend Webhooks. The is_sandbox flag in Webhooks distinguishes test orders from real orders.

When to escalate

The number of Beans users see for recharge is greater than the current product consumption amount
Developer revenue statistics do not match user recharge amounts
Test orders and real orders are mixed in statistics
Entitlements or revenue statistics are not rolled back after refunds (provide user balance, product consumption Beans, recharge tier, Webhook content, is_sandbox flag, refund records, and revenue statistical method)

Was this document helpful?