Debug Your Mini Game

After you've developed your mini game and integrated Mini Games SDK to access TikTok capabilities, you can debug your mini game using DevTool, TikTok's mini game developer tool. Once you've completed debugging, you are ready to upload your code package to the Developer Portal.

Prerequisites

To complete the debugging process, you will need the following items and environments:

Install debug tool

To install TikTok's debug tool (DevTool), run the following command:

npm install @ttmg/cli -g --registry=https://registry.npmjs.org/
ttmg -v # Verify installation

Manage test users

Test users are TikTok accounts that you approve to debug and preview your app. Test users can also access the partial rollout version of your app, if you choose grey release.

If you plan to release your mini game to multiple global regions, we recommend having at least one TikTok test account per region.

Add test users to your app page in the Developer Portal:

1. Go to the Testing permissions tab on your app page.

1. Click the Add test users button.
2. Connect the TikTok account that you want to add as a test user. You can add up to 30 test users per app.
1. If you still get permission errors after adding test users, verify that the account is an adult account (minor accounts cannot be used for development testing)

Complete local login

Functions provided by the debug tool, such as viewing game details and uploading the code package to the Developer Platform, require developers to log in to their TikTok for Developers account on the local endpoint before they can be used. We recommend that you complete the account login first and then proceed with subsequent debugging operations.

Log in to the CLI tool to access advanced features like code upload and project detail viewing:

ttmg login

Configure trusted domains

All network requests from your mini game must go to domains registered in your app's allowlist:

1. Go to your app settings in the Developer Portal.
2. Navigate to the Development configuration page then go to the Security tab.
3. Add all domains your game uses for API requests, resource downloads, and more.

Debugging workflow

To debug your mini game, you will need to have completed code development and integration with TikTok's features.

Step 1: Export your game

TikTok mini games use a framework compatible with other mainstream mini game platforms:

1. Export your game from your engine (such as Unity or Cocos) as a mini game project.
2. The project structure is similar to mini games on Douyin or WeChat, with only minor API differences.
3. Ensure your game.json and project.config.json files are properly configured.

Step 2: Initiate debugging session

Enter the game directory with the path to your game project:

cd path/to/your-game-project

Then start up the debugging environment. You will only be asked to enter your app's client key once, during the first debugging session. It will be stored for subsequent debugging sessions.

ttmg dev

Before running your mini game's code exported by the game engine, TikTok will perform a compilation of the game artifact against its runtime framework. The mini game is then run based on this compiled artifact, ensuring consistent performance.

The compilation process will perform necessary pre-verification on the game atifact to help developers identify issues in advance. The verification includes the following:

• game.json configuration: Is it configured? (Required)
• subpackages in game.json: If present, is the configuration correct?
• main file: Does it exist, and is it correct?
• root directory: Does it exist, and is it correct?
• Game package size: Does it meet platform requirements? (This will show as a warning during local debugging, but will cause an error during platform deployment):
• The entire game package size cannot exceed 30 MB.
• The main game package size cannot exceed 4 MB.
• The size of an independent subpackage cannot exceed 4 MB.

Step 3: Select debug mode

There are two primary methods for testing and debugging your mini game: The debug mode type determines where the game's core logic is executed and how you access debugging tools.

Step 4: Upload test version to Developer Portal

Upload your mini game to your app page on the Developer Portal via the DevTool. Unlike local debugging, this creates a persistent preview version hosted on TikTok's servers. All test users added to your app can access this version.

1. Ensure you are logged in to the CLI (ttmg login).
2. Click the Upload button in the DevTool web interface.
3. After the package is successfully uploaded to the Developer Portal, go to the Code version tab on your app page.
4. Find your uploaded mini game version under the Preview section.

Step 5: Scan the QR code to debug

1. Click the Preview button next to your mini game version to generate a QR code.
2. Scan the generated QR code with TikTok Client to preview the game.
1. TikTok may require a VPN to be accessed normally.
2. Before scanning the QR code, you need to log in using a test account.
3. Wait for the TikTok app to verify whether the currently logged-in TikTok user has debugging permissions for this application.
1. If authorized, the TikTok app will enable the debugging environment.
2. If unauthorized, check the following:
1. Open project.config.json and check if the appid is consistent with the game ID on the Developer Portal.
2. Check whether the appid in project.config.json has already added test users on the Developer Portal.
4. After completing debugging of user authentication, the debugging tool will start uploading the game package to TikTok app. After the upload is completed, it will start loading the game.
1. The browser interface displays the upload progress, and after the upload is completed, the TikTok app starts the game.
2. After the TikTok app completes the game startup, operate the game within the TikTok app and enter the module you want to debug.
3. Use the browser Console to view your logged messages or debug your JavaScript.
5. When you need to modify the code during debugging, you can select the same export path in the game engine export process.
1. The local debugging service will monitor changes to the game's original code package and automatically perform pre-compilation.
2. The debugging page will notify via a pop-up window after the modified code is compiled.

Advanced settings

You can modify debugging settings depending on the scenario you want to test.

• After enabling domain verification, only domains configured on the platform will be allowed to make requests.
• After enabling ad mock debugging, when calling JavaScript APIs for In-App Ads, it will enter the mock environment to help you debug various boundary scenarios.
• After enabling payment mock debugging, when calling JavaScript APIs for In-App Purchases, it will enter the mock environment to help you debug various boundary scenarios.

Set debug startup mode

During mini game development, internal logic is usually differentiated based on different traffic entry sources, and function customization can be achieved by selecting different scenario entry points.

If your mini game supports independent subpackages, you can also choose a specific subpackage as the code package at startup for debugging purposes.

Additionally, in scenarios related to advertising placement, developers often need to customize startup parameters for internal technical attribution within the game.

You can obtain these custom parameters by accessing the TTMinis.game.getLaunchOptionsSync method and use them in subsequent technical processes.

New startup mode

To configure a new startup mode:

1. Select New launch mode from the dropdown above the QR code.
2. Name your launch mode and select launch package and entry scene. Add custom launch parameters if needed.
3. Click Save and apply.

Custom startup package

1. Game main package startup: Load and start the game using the game entry file game.js
2. Independent subpackage startup: Start, load, and debug the game using the independent subpackage entry file

Select to enter the scene

Simulate different traffic scenarios within the TikTok app to launch mini-games, enabling the development and debugging of subsequent processes

Add startup parameters

TTMinis.game.getLaunchOptionsSync method retrieves these custom parameters and uses them in subsequent technical processes.

   // Get startup arguments
    const launchOptions = TTMinis.game.getLaunchOptionsSync();

    console.log('Startup scene value:', launchOptions.scene);
    console.log('Startup query parameters:', launchOptions.query);

    // Common usage example: Executing different logic based on startup parameters
    if (launchOptions.scene === 'scan_qrcode') {
        console.log('User enters the game by scanning a QR code');
    }
    if (launchOptions.query && launchOptions.query.from_user_id) {
        console.log('The game was entered by a user sharing, sharer ID:', launchOptions.query.from_user_id);
    }

Development options

Default development options

By default, development options allow you to choose either remote debugging or real device preview.

Domain name verification settings

By default, the requested domain name is verified and the Disable domain check toggle is switched off. When the domain name verification toggle is switched on, requests can be sent normally without registering a domain name on the Developer Platform.

Payment and ads development settings

You can toggle settings to test payment flows for In-App Purchases and In-App Ads:

• Enable IAP Mock: When switched on, making a payment will not require real money payment and the transaction will pass directly. When switched off, real money is required.
• Enable Ad Mock: Allows you to test configuration of In-App Ads.

Local code pre-check

Below is a list of what content to check:

• Package size check
• The size of the entire game package must be contained within 30 MB, the size of the main package cannot exceed 4 MB, and the size of independent subpackages cannot exceed 4 MB.
• Required connection capability check
• Check if the game has integrated the necessary API capabilities to ensure that the mini game has better user experience and conversion effects on TikTok.
• Configuration file check
• game.json: Ensure that the configuration of the subpackage file paths is correct, all paths can be accessed normally, and avoid subsequent loading failures.
• project.config.json: Confirm that the appid has been filled in and is a valid value; otherwise, local debugging will not run properly.

Explanation of package sizes

Required capabilities

Configuration file instructions

Test the preview version

1. On your app page in the Developer Portal, click the Code version tab.
2. Find your uploaded mini game version in the Preview section. It should have been uploaded directly from the DevTool.
3. Click the Preview button on your uploaded mini game to generate a QR code.
4. Scan the QR code with a TikTok user account that you've already added as a test user.

Set development options

You can set development options while previewing your mini game on TikTok Client.

1. Immediately after scanning the QR code, you will be directed to the mini game's loading page. On the loading page, tap the More options (...) button in the upper right corner of the screen.
2. Tap Developer Options in the panel that appears.
3. Turn on ShowDevInfo Panel and Show vConsole. This displays development info and a vConsole log.

Debug revisit features

Debugging user engagement and revisit features like home screen shortcut and revisit from profile require you to use New Startup Mode in DevTool.

Revisit from Profile incentive debugging

Test the profile sidebar reward functionality:

1. Start debugging environment:

cd path/to/your/game
ttmg dev

2. Select New Startup Mode.
3. Configure the startup mode as Sidebar Entry.
4. Scan the QR code with TikTok to test the reward flow:

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

Home Screen Shortcut incentive debugging

Test the desktop shortcut reward functionality:

1. Start debugging environment:

cd path/to/your/game
ttmg dev

2. Select New Startup Mode.
3. Configure the startup mode as Desktop Shortcut Entry.
4. Scan the QR code with TikTok to test the reward flow:

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

Upload local code to the Developer Portal

Once you have a version of your mini game that you're satisfied with, use DevTool to upload local game code packages to the Developer Portal for testing or debugging.

This feature allows you to directly select the code package to be uploaded and push it to the Developer Portal after completing code writing and packaging locally.

This process helps you quickly verify the content of different versions or sub-packages, enhancing the flexibility of development and debugging.

Troubleshooting

Permission isues

I get "no permission" error when scanning the QR code Verify the following:

1. Your TikTok account is added as a test user in the Developer Portal
2. You are using an adult TikTok account (minor accounts are restricted)
3. The Client Key in your project configuration matches the app in the Developer Portal

Network issues

Network requests are being blocked Check the following:

1. All domains your game uses are added to the trusted domains list in the Developer Portal
2. Your requests use HTTPS protocol (HTTP requests are blocked)
3. WebSocket URLs don't include port numbers
4. Resource file paths don't contain spaces

Debugging settings

I can't find the developer options in the TikTok app When scanning a preview QR code:

1. Tap the three dots (...) in the top right corner during loading
2. If no menu appears, long press the three dots for 20-30 seconds to reveal the developer options
3. From here you can enable vConsole, show development info, and access other debugging features

Performance issues

The game is laggy or dropping frames

• For remote debugging lag: This is normal due to network transmission; switch to real device preview for accurate performance testing
• For real device lag: Optimize your game's performance (reduce draw calls, optimize assets, etc.)
• Persistent performance issues should be reported to the platform team for investigation

Online version troubleshooting

For issues in production versions:

1. Open the game in TikTok
2. Long press the three dots (...) in the top right corner for 20-30 seconds to reveal the developer options
3. Turn on ShowDevInfo Panel to view version information and runtime statistics

Next step: Release your mini game

After debugging your code, you are ready to upload, preview, submit for review, and release to users.