> 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/integration.md). # Integrate Apps in Toss mini-apps are **web-based**they work. To turn a Unity game into a mini-app, you need to build the project **as a WebGL build**When built as WebGL, the Unity game is converted into a form that can run in a browser, and it can be provided as a mini-app in the Apps in Toss environment. The one provided exclusively for Unity **Apps in Toss Unity package**If you install it, you can handle everything from WebGL build to mini-app packaging at once, without configuring a Vite project or implementing a JS Bridge. *** ### Why you should use the Apps in Toss Unity SDK Using the Apps in Toss Unity package gives you the following benefits. * **Short porting time**: You can easily and quickly port a game developed in Unity to an Apps in Toss mini-app without a separate Vite project setup or JS Bridge implementation. * **Improved stability and user experience**: By reducing loading time to about one-fifth, you can improve mini-app stability and provide users with a better experience. * **Check more performance metrics**: You can check more diverse game performance metrics such as crash rate, loading time, and FPS. * **Built-in loading screen**: The loading screen is included by default in the SDK, so partners do not need to configure one separately. {% hint style="info" %} Real-world use case: a certain game had a loading time of about 20 seconds when the manual porting method was used, which led to a lot of user drop-off and an explosive increase in CS inquiries. After switching to the Unity SDK, the loading time **1 second**was reduced to, greatly improving those issues. {% endhint %} *** ### What is SDK integration? SDK integration is a method that automatically handles the processes needed for Apps in Toss integration inside Unity. * For WebView SDK integration, **JS Bridge**is included by default. * In Unity **Apps in Toss API**can be called directly with C# code. * From WebGL build to `.ait` file generation, everything is automated at once. * Game performance metrics such as crash rate, loading time, and FPS are collected automatically. If you are developing a mini-app in Unity, we recommend proceeding based on the Unity SDK provided by Apps in Toss. {% hint style="info" %} **Manual integration** If you need to configure WebGL builds directly or implement a JS Bridge without the Apps in Toss Unity package, [manual integration guide](/documentation/api-and-sdk-en/unity/manual-integration.md)please refer to. {% endhint %} *** ### SDK installation #### Method 1: Package Manager (recommended) 1. In the Unity Editor, `Window` > `Package Manager`open it. 2. top left `+` click the button and `Add package from git URL...`select it. 3. Enter the Git URL and **Install**press it to install. ``` https://github.com/toss/apps-in-toss-unity-sdk.git ``` {% hint style="info" %} **Version pinning** If you want to pin a specific version, `#release/v2.4.5`use a release tag like this. The release list is [GitHub Releases](https://github.com/toss/apps-in-toss-unity-sdk/releases)can be found in {% endhint %} #### Method 2: Directly edit manifest.json of the project `Packages/manifest.json` You can also add it directly to the file: ```json { "dependencies": { "im.toss.apps-in-toss-unity-sdk": "https://github.com/toss/apps-in-toss-unity-sdk.git#release/v2.4.5" } } ``` #### Supported Unity versions * **Minimum version**: Unity 2021.3 * **Recommended version**: Unity 6 or later * Supports all versions from Unity 2021.3 onward. #### Checking installation completion If installation completes successfully: * In the Package Manager list, **AppsInToss SDK**is displayed. * At the top of the Unity menu, **AIT** a new item is added. * `Packages/Apps In Toss SDK/Runtime/SDK` under the path `AIT.*.cs` files are created. *** ### Package components The Apps in Toss Unity package provides both the **C# API Layer**and **JavaScript Bridge (.jslib)** to let you use the Apps in Toss SDK in a WebGL environment. #### C# API Wrapper This is an API provided so you can directly call Apps in Toss functions from Unity C# code. * It wraps the Apps in Toss API as C# methods for convenient use. * Internally, `DllImport("__Internal")`it links to JS functions during the WebGL build. * You can integrate Apps in Toss using only C# code, without any separate JavaScript. #### JavaScript Bridge (.jslib) `.jslib` The .jslib file serves as a bridge connecting C# and JavaScript in the Unity WebGL environment. * JS functions called from C# are defined in this file. * The logic that actually communicates with the Apps in Toss WebView SDK is also handled here. * It also supports JS → C# calls, allowing a two-way messaging structure. *** ### AIT Menu When the Apps in Toss Unity package is installed, the **AIT** menu is added to the top of the Unity Editor. In this menu, you can use most of the functions needed for the integration process, such as WebGL build, packaging, and running the test server. | menu | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Dev Server** | Runs a development test server. Mock bridge is enabled, so you can test in a local browser. | | **Production Server** | Runs a local server with production settings. You can perform tests similar to the actual deployment environment. | | **Build & Package** | WebGL build + `.ait` Packaging runs at once. This is the option used most frequently. | | **Publish** | `.ait` Upload the file to the Apps in Toss console. A deployment key must be registered in Configuration. | | **Clean** | Deletes previous build artifacts. | | **Open Build Output** | Opens the folder where the build artifacts are saved. | | **Configuration** | Sets build options related to Apps in Toss mini-app integration. | | **Debug** | You can check logs or inspect the internal state. | *** ### Configuration After installing the SDK, in the Unity Editor menu `AIT` > `Configuration`click it to open the settings panel. #### Required settings | Configuration | Description | | ----------------- | ---------------------------------------------------------------- | | **App ID** | Registered in the Apps in Toss console `appName`must be the same | | **App icon URL** | Image URL displayed as the mini-app icon (required) | | **Display name** | App name displayed on the loading screen | | **Primary color** | Brand color (used for progress bars, etc.) | {% hint style="info" %} * **App ID**must match the one registered in the Apps in Toss console `appName`must be the same. * **Icon**is not required during testing, but it must be registered for actual deployment. * Granite and Vite-related items in the server settings are used when testing sandbox apps. {% endhint %} For detailed settings for each build option, please refer to the build profile documentation. *** ### First build #### 1. Check the settings 1. `AIT` > `Configuration` Check the settings in the menu. 2. **App icon URL**Make sure it is entered (required). #### 2. Run the development server During development, use Dev Server mode: 1. `AIT` > `Dev Server` > `Start Server` Click the menu item. 2. The Unity WebGL build runs automatically. 3. After the build completes, the local development server starts. 4. It opens automatically in the browser, or you can access it via the URL shown in the console. #### 3. Production build To create a deployment build: 1. `AIT` > `Build & Package` Click the menu item. 2. After the build completes `ait-build/dist/` You can check the results in the folder. #### 4. Deployment To deploy to the Apps in Toss platform: 1. `AIT` > `Publish` Click the menu item. 2. The deployment key must be set (in Configuration). *** ### Using the SDK If you install the Apps in Toss Unity SDK, you can directly `AIT.*` call the APIs from C# code. You can use Apps in Toss features with only Unity code, without writing a JS Bridge yourself. Most Apps in Toss APIs are async: ```csharp var result = await AIT.SomeApi(options); ``` * If successful, a result model specific to the API is returned. * If it fails, `AITException`an exception may occur, so exception handling is needed. You can find the full list of available AIT APIs in the Apps in Toss SDK reference. The WebView SDK's `getDeviceId`is called in the Unity SDK `AIT.GetDeviceId()`as GetDeviceId Please refer to the API usage patterns document for detailed usage patterns. **Example** ```csharp using AppsInToss; using UnityEngine; using System.Threading.Tasks; public class GameManager : MonoBehaviour { async void Start() { try { // Query device ID string deviceId = await AIT.GetDeviceId(); Debug.Log($"Device ID: {deviceId}"); // Check platform OS PlatformOS os = await AIT.GetPlatformOS(); Debug.Log($"Platform: {os}"); // Check network status NetworkStatus status = await AIT.GetNetworkStatus(); Debug.Log($"Network: {status}"); } catch (AITException ex) { Debug.LogError($"API call failed: {ex.Message} (code: {ex.Code})"); } } // Haptic feedback example public async void VibrateDevice() { try { var options = new GenerateHapticFeedbackOptions { style = "medium" }; await AIT.GenerateHapticFeedback(options); Debug.Log("Haptic feedback generated"); } catch (AITException ex) { Debug.LogError($"Haptic feedback failed: {ex.Message}"); } } } ``` {% hint style="info" %} **Check the sample code** The files below are sample code for E2E testing, where you can see how in-app ads / in-app purchases are actually used. * [In-app ads sample](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Tests~/E2E/SharedScripts/Runtime/AdV2Tester.cs) * [In-app purchase sample](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Tests~/E2E/SharedScripts/Runtime/IAPv2Tester.cs) {% endhint %} *** ### Test The Apps in Toss AIT API **does not work in a regular browser environment.** Features are available only in the Apps in Toss runtime environment. There are two testable environments: #### 1. Test in the sandbox app This is a test app provided to verify features during development. You can run a Unity WebGL build and check whether the AIT API connects properly. * Download the sandbox app #### 2. Test after uploading the .ait file 1. In the AIT menu `Build & Package`as a `.ait` generate the file. 2. [Apps in Toss console](https://apps-in-toss.toss.im/)Upload it to 3. Run the mini-app using the QR code. For details, please refer to the Testing in the Toss app document. --- # 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/integration.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.