> 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/getting-started.md). # Getting started This covers, in order, only what you need to install the SDK and get your first build running. If you use Apps in Toss Unity SDK, you can port a Unity project into a mini app without separately setting up a Vite project or implementing a JS Bridge. The loading screen is built into the SDK by default, and runtime events such as time to first interaction, frame stalling, errors/exceptions, and memory warnings are automatically collected without user code (for details, see [SDK event logging](https://developers-apps-in-toss.toss.im/documentation/unity/add-features/metrics) reference). ### SDK installation #### Install with Package Manager 1. In the Unity Editor, `Window` > `Package Manager` Open 2. top left `+` Click button 3. `Add package from git URL...` Select 4. Enter Git URL: ``` https://github.com/toss/apps-in-toss-unity-sdk.git#release/v3.0.3 ``` #### Edit manifest.json directly of the project `Packages/manifest.json`Add the dependency to ```json { "dependencies": { "im.toss.apps-in-toss-unity-sdk": "https://github.com/toss/apps-in-toss-unity-sdk.git#release/v3.0.3" } } ``` #### Supported Unity versions At minimum, Unity 2021.3 is required, and Unity 6 or later is recommended. All versions after 2021.3 are supported. ### SDK structure Apps in Toss Unity SDK provides two layers together so you can use platform APIs in a WebGL environment. * **C# API Layer** (`Runtime/SDK/`) — `AIT.*` Wraps platform APIs in C# methods in the form of. Internally, `DllImport("__Internal")`uses it to connect to JS functions when building for WebGL. * **JS Bridge** (`.jslib`) — JS functions called from C# are defined here, and the logic that actually communicates with the Apps in Toss WebView SDK lives here. Both layers are already included in the SDK, so there is nothing for you to write yourself. ### Managing the install ref At the end of the URL `#...` part is **install ref**. UPM fetches the commit pointed to by this ref as-is, so what you put here determines "when and how it is updated." #### Choosing a ref | ref format | example | Behavior | | --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- | | Immutable release tag | `#release/vX.Y.Z` | Permanently pinned to a specific commit. Ensures reproducible builds and isolates you from unintended updates | | Branch | `#main` | Whenever HEAD moves, the auto-updater detects the change and shows an update prompt | | prerelease channel | `#beta`, `#beta-perf` | Moving branch. No automatic update prompt appears, so you must manage it manually | > **Recommended**: For service deployments, use immutable release tags. Available tags are [GitHub Releases](https://github.com/toss/apps-in-toss-unity-sdk/releases). prerelease channels are announced only to pre-arranged pilot participants. [beta channel](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Documentation~/BetaChannel.md)and [perf beta channel](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Documentation~/PerfBetaChannel.md)for reference. #### Pull the moving ref up to date again UPM pins git dependencies `Packages/packages-lock.json`to **to a commit hash.** So `#main`even if you pinned it to a moving ref like, reopening Unity alone will not update it. You must unlock it in one of two ways. * **Remove and re-add in Package Manager** — If you remove the package and add it again with the same URL, the ref is re-resolved. This is the simplest method. * **Unlock** — `Packages/packages-lock.json`in `im.toss.apps-in-toss-unity-sdk` item's `"hash"` If you clear the value and save, Unity will re-resolve the ref. #### Switch to another ref `Packages/manifest.json`change only the URL fragment and save. If the dependency string changes, UPM re-resolves the package from scratch, so in that case you don't need the unlock step above. * Pilot participation: `#release/vX.Y.Z` → `#beta` or `#beta-perf` * Return to stable: `#beta` → `#release/vX.Y.Z` If you revert to an immutable release tag, the auto-updater will track that stable ref again. ### Configuration After installing the SDK, in the Unity Editor menu `AIT` > `Configuration`Click to open the settings window. | Configuration | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **App ID** | The app ID issued on the Apps in Toss platform. Only letters, numbers, and hyphens can be used, and in the settings window `*`is the only required item shown as | | **Display name** | App name displayed on the loading screen | | **Version** | `x.y.z` format | | **Primary color** | Brand color. Used for progress bars, etc. | | **Icon URL** | The image URL to display as the mini app icon. If entered `http://` or `https://`must start with | ### AIT Menu Once SDK installation is complete, at the top of the Unity Editor `AIT` a menu is added. | menu | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Dev Server** | It contains Start / Stop / Restart Server / Restart Server (server-only). `server-only`restarts only the server without rebuilding | | **Production Server** | It contains Start / Stop / Restart Server / Restart Server (server-only). `server-only`restarts only the server without rebuilding | | **Build & Package** | WebGL build and `.ait` run packaging in one go | | **Publish** | Generated `.ait` Upload the file to the Apps in Toss platform. `Configuration`A deployment key must be set in | | **Clean** | `webgl/`, `ait-build/` Delete the build output folder | | **Open Build Output** | Open the folder where the build output is stored | | **Reset Loading Screen** | Restore the loading screen to the SDK's default template. For details, see [Loading screen customization](https://developers-apps-in-toss.toss.im/documentation/unity/build/loading-screen-customization) Note | | **Configuration** | Open the mini app integration settings window for app ID, display name, etc. | | **Install Sentry SDK** | Install Sentry Unity SDK. For details, see [Sentry integration](https://developers-apps-in-toss.toss.im/documentation/unity/add-features/sentry-integration) Note | | **Report an issue** | Open a window to report an issue | | **Check for Updates...** | Manually check whether there is a new SDK release | | **Debug** | Contains debug submenus such as SDK state reset and forced WebGL template refresh | The differences in Dev Server and Production Server, and each build profile's devtools/compression settings, are [Build profile](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles)documented there. ### First build All build entry points are `AIT` in the menu. How each entry point builds differently is [Build profile](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles)documented there. #### Check with the development server Use Dev Server during development. `@apps-in-toss/devtools`The Mock SDK and panel run together, so you can verify platform API calls as mocks in the browser without the Toss app and directly control the mock state from the panel. 1. `AIT` > `Dev Server` > `Start Server` Click 2. Unity WebGL build runs automatically 3. When the build finishes, the local development server starts 4. The browser opens automatically, or connect via the URL shown in the console #### Create a deployment package 1. `AIT` > `Build & Package` Click 2. After the build finishes, `ait-build/dist/`Check the output in #### Check on a physical device (Deploy Test) Use Deploy (Test) to verify the real Toss app environment (camera, payments, ads, etc.) on a physical device, which cannot be checked with the browser mock. 1. `AIT` > `Deploy (Test)` Click 2. A deployment key must be set. `AIT` > `Configuration`Enter it in 3. After an incremental build `ait deploy`is deployed to the console QR test environment (in memo `[Test]` the prefix is added automatically) 4. After deployment finishes, scan the QR code in the popup with the Toss app or open the URL to check on a physical device #### Release to the platform (Deploy Production) To expose it to real users, redeploy with a clean build and then request review in the console. 1. `AIT` > `Deploy (Production)` Click (same as Deploy (Test), but clean build + memo `[Production]` prefix) 2. When deployment finishes, use the "Open Console" button in the popup to go to the Apps in Toss console 3. In the console, request review/release for the build you just deployed — `ait deploy` Deploy (Test) itself only ever deploys to the console QR test environment; actual release happens only through this console procedure ### SDK usage examples The SDK API uses the async/await pattern. `Awaitable`and `Task` which of the following is returned, and how to handle timeouts and error codes, [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)documented there. #### Get device information ```csharp using AppsInToss; using UnityEngine; public class GameManager : MonoBehaviour { async void Start() { try { // Query device ID string deviceId = await AIT.GetDeviceId(); Debug.Log($"Device ID: {deviceId}"); // Check platform OS string 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.ErrorCode})"); } } } ``` #### Payment request ```csharp using AppsInToss; using UnityEngine; using System.Threading.Tasks; public class PaymentManager : MonoBehaviour { public async Task RequestPayment() { try { var options = new CheckoutPaymentOptions { PayToken = "your-pay-token" }; CheckoutPaymentResult result = await AIT.CheckoutPayment(options); Debug.Log($"Payment success: {result.Success}"); } catch (AITException ex) { Debug.LogError($"Payment failed: {ex.Message}"); } } } ``` > **Important**: For in-app purchases, you must specify a payment approval callback. If you don't, all payments will be treated as payment failures. [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)First read the in-app purchase section of #### Haptic feedback ```csharp using AppsInToss; using UnityEngine; public class FeedbackManager : MonoBehaviour { public async void VibrateDevice() { try { var options = new HapticFeedbackOptions { Type = HapticFeedbackType.Tap }; await AIT.GenerateHapticFeedback(options); Debug.Log("Haptic feedback generated"); } catch (AITException ex) { Debug.LogError($"Haptic feedback failed: {ex.Message}"); } } } ``` ### Test The SDK API actually goes through the bridge only in WebGL builds, and even then it works properly only in the Apps in Toss app environment in most cases. In the Unity Editor, the Editor mock just returns default values. For details, see [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)of **Mock** section. The procedure for checking a local build with a sandbox app [Troubleshooting](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/faq) is summarized in the document's "Works in Dev Server but not in Production" section. For final verification before deployment, `.ait` use file upload tests. 1. `AIT` > `Build & Package`as a `.ait` Create a file. 2. [Apps in Toss console](https://apps-in-toss.toss.im/)Upload to. 3. Run the mini app via QR code to verify it. If you get stuck, [Troubleshooting](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/faq) refer to the document. ### Related documents * [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns) — async/await, error handling, Mock * [Build profile](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles) — configuration differences by build entry point * [Build customization](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-customization) — modifying web entry points, adding external libraries * [Loading screen customization](https://developers-apps-in-toss.toss.im/documentation/unity/build/loading-screen-customization) — replacing the loading screen * [Troubleshooting](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/faq) — common sticking points and how to solve them --- # 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/getting-started.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.