It doesn’t have to be perfect. Build your mini app for a chance to win up to KRW 3 million.
Ctrlk
SupportCommunityConsole
For the complete documentation index, see llms.txt. This page is also available as Markdown.

FAQ

These are the common pain points when using the SDK and how to fix them. Search by symptom.

When the build does not succeed

Error saying Node.js could not be found

The build pipeline uses Node.js. Even if it is not installed on your system, the SDK automatically downloads the bundled Node.js, so if the download dialog appears, just download it.

The bundled Node.js is saved below. The Node version and platform are appended to the path as subfolders.

macOS/Linux   ~/.ait-unity-sdk/nodejs/v<version>/<platform>/
Windows       %LOCALAPPDATA%\ait-unity-sdk\nodejs\v<version>\<platform>\

If you still keep getting a not-found error ~/.ait-unity-sdk/nodejsdelete it completely and build again. Most of the time, the download was interrupted and corrupted.

Unity WebGL build failed

  1. Unity version — At least 2021.3 is required. Unity 6 or later is recommended.

  2. WebGL module not installed — Install the WebGL Build Support module in Unity Hub.

  3. Out of memory — Restart the Unity Editor, close other programs, and try again.

The compilation errors and stack traces in the Console window are the clearest clues.

Dependency installation failed

The build pipeline uses pnpm. npmis not.

  1. Network — Check your internet connection and, if you are in a proxy environment, your proxy settings.

  2. Corrupted node_modules — ait-build/node_modulesDelete it and build again.

  3. Try running it directly — ait-build directory pnpm installdirectly to see more detailed errors than in the Unity Console.

granite build failed

This is a failure at the packaging stage.

  1. TypeScript compilation error — BuildConfig~/Check the syntax errors in your user code added to.

  2. Dependency conflict — package.jsonCheck the package versions you added to it, and node_modulesdelete it and try building again.

What happens at each build stage is Build pipelinedocumented there.

Error that the app settings are invalid

AIT > ConfigurationCheck whether a settings asset has been created there. This error occurs when the settings asset itself cannot be found.

Note: The required item is only the app IDis. In the settings window, *the item with the attached label is also only the app ID. The icon URL is optional, and only when provided http:// or https://we check whether it starts with. You can leave it blank and the build will still proceed.

When behavior is strange

Only mock logs appear in the Unity Editor

This is normal. The SDK API actually only goes through the bridge in WebGL builds. In the Editor, [AIT Mock] <API> called it logs and returns the default value.

Check the actual behavior by building to WebGL and testing in the Apps in Toss app. For details, see API usage patterns the documentation's Mock section.

Works on Dev Server but not on Production

Dev Server has devtools enabled, so in a normal browser more than 60 SDK APIs and ad flows work in mock mode. Production builds require the actual Apps in Toss app environment and cannot be reproduced in a browser.

To verify the production settings as they are on a real device AIT > Deploy (Test)deploy, then scan the QR in the popup with the Apps in Toss app or access it via the URL. ait deployalways deploys to the console QR test environment (intoss-private://), so you can safely verify it before actual review and release using this process.

What differs by profile is Build profilehere.

(for users before 3.x) Production Server menu disappeared

From SDK 3.0.0 onward, the method of connecting a local server to a separate sandbox app for testing became impossible, so AIT > Production Server the menu no longer exists. To check production settings on a real device, use the above "Dev Server works but Production doesn't" item. Deploy (Test)the Deploy (Test) method.

As part of the same overhaul, AIT > Publish menu also Deploy (Test)(incremental build, memo [Test]) and Deploy (Production)(clean build, memo [Production]) were split into. ait deploy The CLI itself always deploys only to the console QR test environment for both menus, and actual release is Deploy (Production)done by going to the "Open Console" button shown after deployment and submitting for review from the console.

AITException occurs

  1. ErrorCodeand Messagecheck together.

  2. IsPlatformUnavailableIf it is truethen it's not a code problem but an execution environment problem — the bridge could not be reached.

  3. Check the network status and the Apps in Toss app version.

For the overall error-handling patterns, API usage patternshere.

stuck on the loading screen

  1. Unity initialization failed — Check the error in the Console tab of the browser developer tools.

  2. Resource loading failed — Check the failed requests and CORS settings in the Network tab.

  3. Out of memory — On mobile, close other apps and try again.

How to handle the loading screen itself Loading screen customizationhere.

Memory usage keeps increasing in WebGL builds (when using Rigidbody2D)

In versions earlier than Unity 6000.1.8, the 2D physics engine (Rigidbody2D) has a known issue where GC memory is not released and keeps accumulating in WebGL builds. For details, see the Unity Discussions forumfor reference.

Solution: use Unity 6000.1.8 or later.

Payment API does not work

  1. Mock environment — Real payments only work inside the Apps in Toss app.

  2. Missing option — Make sure all required fields are filled in. In particular, the order creation API must ProcessProductGrantbe specified (see the item below).

The post-purchase refund information page appears

Payment succeeded, but {App name} has a problem. Please request a refund page appears and the product is not granted.

ProcessProductGrant The callback trueresponded with a value other than true. In most cases, the callback was not set at all case, and in that case the SDK automatically falsereturns false and leaves the following error in the Console.

Even if you return falsedirectly, the same page appears.

Solution: set the callback and immediately truereturn true. Since the return type is bool, server validation (await) does not compile here in the first place. Validation and delivery happen after the overlay closes onEvent.

falsereturn this only when you can truly say right now that you cannot grant this product. If you think "I'm not sure, so I'll just false" then your app will show this page on every payment.

Recover already failed orders: for this symptom, true orders whose responses were missed remain in a delivery-failed state. IAPGetPendingOrderslook them up with IAPCompleteProductGrantto complete the delivery. Orders that were approved but not delivered are found with IAPGetCompletedOrRefundedOrders.

Important: For the detailed mechanism and full code, see API usage patterns the documentation's In-app purchases: grant approval and server verification section. Immediate approval, onEvent validation, and the line shown at app launch — these three are a package, so do not separate and use only one.

Development environment

AIT menu not visible

  1. Package installation failed — Window > Package ManagerCheck whether the SDK is installed in the Package Manager, and if there is an error, remove it and install it again.

  2. Compilation error — If there is even one compilation error in the Console, the menu will not be registered. Resolve them all and restart Unity.

  3. Unity version — Make sure it is 2021.3 or later.

If it still does not work,

  1. capture the full error message from the Unity Console.

  2. Check the Console and Network tabs in the browser developer tools together.

  3. GitHub issueor file one TechChatfor support.

Related documents

PreviousAPI Usage Patterns
NextAdd Features

Was this helpful?