> 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 common stumbling points when using the SDK and how to fix them. Find them by symptoms. ### When the build does not work #### Error saying Node.js cannot 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 just accept the download dialog if it appears. The bundled Node.js is stored 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 an error saying it cannot be found, `~/.ait-unity-sdk/nodejs`delete it completely and build again. Most of the time, the download was interrupted and became corrupted. #### Unity WebGL build failure 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. Compile errors and stack traces in the Console window are the most reliable clues. #### Dependency installation failed The build pipeline uses pnpm. `npm`is not. 1. **Network** — Check your internet connection, and if you're behind a proxy, check the proxy settings. 2. **Corrupted node\_modules** — `ait-build/node_modules`Delete it and build again. 3. **Try running it directly** — `ait-build` in the directory `pnpm install`Running it directly will show more detailed errors than the Unity Console. #### granite build failure This is a failure during the packaging stage. 1. **TypeScript compilation error** — `BuildConfig~/`Check for syntax errors in the user code you added. 2. **Dependency conflict** — `package.json`Check the package versions you added, and `node_modules`delete it and try building again. What happens at each build step is [the build pipeline](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-process)documented there. #### Error that the app settings are incorrect `AIT` > `Configuration`Check whether the configuration asset was created in AIT Configuration. This error occurs when the configuration asset itself cannot be found. > **Note**: The only required item is **the app ID**only. In the settings window, `*`the item labeled is also just the app ID. The icon URL is optional, and only if you enter it `http://` or `https://`it checks whether it starts with them. You can leave it blank and the build will still proceed. ### When behavior is strange #### Only Mock logs appear in Unity Editor This is normal. The SDK API only actually goes through the bridge in WebGL builds. In the Editor, `[AIT Mock] called` it logs and returns a default value. To see the real behavior, build to WebGL and check it 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) in the documentation's **Mock** section. #### Works in Dev Server but not in Production Dev Server has devtools enabled, so more than 60 SDK APIs and ad flows work as mocks even in a normal browser. Production builds require the actual Apps in Toss app environment and cannot be reproduced in a browser. To verify the production settings as-is on a real device `AIT` > `Deploy (Test)`after deploying, scan the QR in the window that appears with the Apps in Toss app, or access it by URL. `ait deploy`always deploys to the console QR test environment (`intoss-private://`), so this procedure lets you safely verify things before actual review and release. What changes by profile is [Build Profiles](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles)in. #### (For users before 3.x) `Production Server` menu disappeared Starting with SDK 3.0.0, it became impossible to test by connecting a local server to a separate sandbox app, `AIT` > `Production Server` so the menu no longer exists. To verify production settings on a real device, follow the item above, "Works in Dev Server but not in Production," `Deploy (Test)`and use it. With the same restructuring, `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 both menus only to the console QR test environment, and actual release `Deploy (Production)`is done by going to the "Open Console" button shown after this deployment and applying for review in the console. #### AITException occurs 1. `ErrorCode`and `Message`Check them together. 2. `IsPlatformUnavailable`If it is `true`then it is not a code problem but an execution environment problem — it could not reach the bridge. 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 pattern, [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)in. #### stuck on the loading screen 1. **Unity initialization failure** — Check errors in the Console tab of the browser developer tools. 2. **Resource load failure** — Check 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 is [Loading screen customization](https://developers-apps-in-toss.toss.im/documentation/unity/build/loading-screen-customization)in. #### 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 in WebGL builds and keeps accumulating. For details, see [the Unity Discussions forum](https://discussions.unity.com/t/memory-leak-when-using-rigidbody2d-physics-in-webgl/1649803). **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** — Check that all required fields are filled in. In particular, the order creation API must `ProcessProductGrant`be specified (see below). ### A refund notice page appears after in-app payment The payment succeeded, but `{App name} has a problem. Please request a refund` This symptom is that the page appears and the item is not delivered. `ProcessProductGrant` The callback `true`responded with a value other than **not set at all** case, in which case the SDK automatically `false`responds with it and leaves the error below in the Console. ``` [AITCore] Nested callback 'processProductGrant' is not registered ``` If you directly `false`return it, the same page appears. **Solution**: Set the callback and immediately `true`return it. Since the return type is `bool`, server verification at this point (`await`) does not even compile. Verification and delivery are done after the overlay closes `onEvent`in onEvent. ```csharp // ✅ Approve the callback immediately, and do verification/delivery in onEvent options.ProcessProductGrant = _ => true; // ... onEvent: e => { ShowPurchaseSuccess(); _ = MyServer.VerifyAndDeliver(e.Data.OrderId); } ``` `false`should be returned only when you can definitely say right now that you really cannot give this product. "If you're not sure, for now `false`" will make this page appear on every payment. **Recover already failed orders**: With this symptom, `true` orders that missed the response remain in payment-failed state. `IAPGetPendingOrders`query them, then `IAPCompleteProductGrant`complete delivery with it. Orders that were approved but not delivered are `IAPGetCompletedOrRefundedOrders`found with it. > **Important**: For the detailed mechanism and full code, [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns) in the documentation's **In-app payments: delivery approval and server verification** section. Immediate approval, `onEvent` verification, and the startup dialogue — these three form a single set, so you should not use only one of them. ### Development environment #### AIT menu not visible 1. **Package installation failed** — `Window` > `Package Manager`Check in the Package Manager whether the SDK is installed, and if there is an error, remove it and reinstall. 2. **Compilation error** — If there is even one compilation error in the Console, the menu will not be registered. Fix them all and then restart Unity. 3. **Unity version** — Make sure it is 2021.3 or later. ### If it still isn't resolved, 1. get 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)contact us through it. ### Related documents * [Getting 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 Profiles](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles) — Profile-specific settings * [the 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 modifying 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.