> 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**and run. To turn a Unity game into a mini app, you need to build the project with **build it for WebGL**Doing a WebGL build converts the Unity game into a form that can run in the browser, and you can provide it as a mini app in the Apps in Toss environment.

provided exclusively for Unity, **Apps in Toss Unity package**Installing it lets you handle everything from WebGL build to mini app packaging at once, without setting up a Vite project or implementing a JS Bridge.

***

### Why use the Apps in Toss Unity SDK

Using the Apps in Toss Unity package gives you the benefits below.

* **Short porting time**: You can port a game developed in Unity to an Apps in Toss mini app easily and quickly, without setting up a separate Vite project or implementing a JS Bridge.
* **Improved stability and user experience**: By reducing loading time to one-fifth, you can improve mini app stability and provide users with a better experience.
* **See 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 in the SDK by default, so partners don't need to set one up separately.

{% hint style="info" %}
Real-world example In one specific game, when manual porting was used, loading time was as long as about 20 seconds, causing a lot of user drop-off and a surge in CS inquiries.

After switching to the Unity SDK, the loading time **1 second**was reduced, which greatly improved these issues.
{% endhint %}

***

### What is SDK integration?

SDK integration is a method that automatically handles the steps required for Apps in Toss integration inside Unity.

* For WebView SDK integration, **JS Bridge**is included by default.
* In Unity, **Apps in Toss API with C# code**can be called directly.
* From WebGL build to `.ait` file generation is automated all at once.
* Game performance metrics such as crash rate, loading time, and FPS are collected automatically.

If you develop 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 build WebGL manually or implement a JS Bridge without the Apps in Toss Unity package, [manual integration guide](/documentation/api-and-sdk-en/unity/manual-integration.md).
{% endhint %}

***

### Install the SDK

#### 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 to install.

```
https://github.com/toss/apps-in-toss-unity-sdk.git
```

{% hint style="info" %}
**Pinning a version**

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)here.
{% endhint %}

#### Method 2: Edit manifest.json directly

of your 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
* All versions from Unity 2021.3 onward are supported.

#### Check 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 **C# API Layer**and **JavaScript Bridge (.jslib)** together to enable use of the Apps in Toss SDK in a WebGL environment.

#### C# API Wrapper

An API provided so you can call Apps in Toss features directly from Unity C# code.

* You can conveniently use the Apps in Toss API by wrapping it as C# methods.
* Internally, `DllImport("__Internal")`is used to connect to JS functions during WebGL builds.
* You can integrate Apps in Toss with only C# code, without any separate JavaScript.

#### JavaScript Bridge (.jslib)

`.jslib` The file acts 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.
* JS → C# calls are also supported, allowing a bidirectional 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. From 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**        | Run the development test server. The mock bridge is enabled, so you can test in a local browser.                   |
| **Production Server** | Run the 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 often.                                   |
| **Publish**           | `.ait` Uploads 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 output is saved.                                                                  |
| **Configuration**     | Set build options related to Apps in Toss mini app integration.                                                    |
| **Debug**             | You can check logs or inspect internal status.                                                                     |

***

### Settings

After installing the SDK, in the Unity Editor menu `AIT` > `Configuration`click to open the settings panel.

#### Required settings

| Settings          | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| **App ID**        | registered in Apps in Toss Console `appName`must be the same as |
| **App icon URL**  | Image URL to be 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**is the one registered in Apps in Toss Console `appName`must be the same as
* **Icon**can be omitted 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 by build option, please refer to the build profile document.

***

### First build

#### 1. Check settings

1. `AIT` > `Configuration` Check the settings in the menu.
2. **App icon URL**Please make sure this is entered (required).

#### 2. Run the development server

During development, use Dev Server mode:

1. `AIT` > `Dev Server` > `Start Server` click the menu.
2. The Unity WebGL build runs automatically.
3. After the build is complete, 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 build for deployment:

1. `AIT` > `Build & Package` click the menu.
2. After the build is complete `ait-build/dist/` you can check the output in the folder.

#### 4. Deployment

To deploy to the Apps in Toss platform:

1. `AIT` > `Publish` click the menu.
2. A deployment key must be set (in Configuration).

***

### Using the SDK

After installing the Apps in Toss Unity SDK, you can directly `AIT.*` call APIs from C# code. You don't need to write a JS Bridge yourself; you can use Apps in Toss features with only Unity code.

Most Apps in Toss APIs operate asynchronously (async):

```csharp
var result = await AIT.SomeApi(options);
```

* On success, a result model for each API is returned.
* On failure, `AITException`may occur, so exception handling is required.

The full list of available AIT APIs can be found in the Apps in Toss SDK reference. The WebView SDK's `getDeviceId`in the Unity SDK is called `AIT.GetDeviceId()`in PascalCase.

For detailed usage patterns, please refer to the API usage patterns document.

**Example**

```csharp
using AppsInToss;
using UnityEngine;
using System.Threading.Tasks;

public class GameManager : MonoBehaviour
{
    async void Start()
    {
        try
        {
            // Retrieve device ID
            string deviceId = await AIT.GetDeviceId();
            Debug.Log($"Device ID: {deviceId}");

            // Retrieve 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 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 ad 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 %}

***

### Testing

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 functionality during development. You can run the Unity WebGL build and check whether the AIT API is connected properly.

* Download the sandbox app

#### 2. Test after uploading the .ait file

1. In the AIT menu `Build & Package`as `.ait` create a file.
2. [Appintos Console](https://apps-in-toss.toss.im/)Upload it to
3. Run the mini app with a QR code.

For detailed instructions, 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=<question>&goal=<endgoal>
```

`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.