> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/unity/first-steps/faq.md). # 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// Windows %LOCALAPPDATA%\ait-unity-sdk\nodejs\v\\ ``` If you still keep getting a not-found error `~/.ait-unity-sdk/nodejs`delete 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. `npm`is 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_modules`Delete it and build again. 3. **Try running it directly** — `ait-build` directory `pnpm install`directly 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.json`Check the package versions you added to it, and `node_modules`delete it and try building again. What happens at each build stage is [Build pipeline](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-process)documented there. #### Error that the app settings are invalid `AIT` > `Configuration`Check 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 ID**is. 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] 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](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/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 deploy`always 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 profile](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles)here. #### (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. `ErrorCode`and `Message`check together. 2. `IsPlatformUnavailable`If it is `true`then 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. ```csharp try { var result = await AIT.SomeAPI(); } catch (AITException ex) { Debug.LogError($"Error code: {ex.ErrorCode}, message: {ex.Message}"); } ``` For the overall error-handling patterns, [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)here. #### 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 customization](https://developers-apps-in-toss.toss.im/documentation/unity/build/loading-screen-customization)here. #### 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 forum](https://discussions.unity.com/t/memory-leak-when-using-rigidbody2d-physics-in-webgl/1649803)for 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 `ProcessProductGrant`be 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 `true`responded with a value other than true. In most cases, the callback was **not set at all** case, and in that case the SDK automatically `false`returns false and leaves the following error in the Console. ``` [AITCore] Nested callback 'processProductGrant' is not registered ``` Even if you return `false`directly, the same page appears. **Solution**: set the callback and immediately `true`return 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`. ```csharp // ✅ Immediately approve the callback, and perform validation and delivery in onEvent options.ProcessProductGrant = _ => true; // ... onEvent: e => { ShowPurchaseSuccess(); _ = MyServer.VerifyAndDeliver(e.Data.OrderId); } ``` `false`return 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. `IAPGetPendingOrders`look them up with `IAPCompleteProductGrant`to 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](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/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 Manager`Check 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 issue](https://github.com/toss/apps-in-toss-unity-sdk/issues)or file one [TechChat](https://techchat-apps-in-toss.toss.im)for support. ### Related documents * [Get started](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/getting-started) — Installation and basic setup * [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns) — Async patterns and error handling * [Build profile](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles) — Profile-specific settings * [Build pipeline](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-process) — Build stages and error codes * [Contribution guide](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Documentation~/Contributing.md) — When fixing the SDK itself --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/unity/first-steps/faq.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.