> 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 We’ve organized only the essentials, in order, from installing the SDK to launching the first build. Using Apps in Toss Unity SDK, you can port a Unity project to a mini app without configuring a separate Vite project or implementing a JS Bridge. A loading screen is included by default in the SDK, and runtime events such as time to first interaction, frame stalls, errors/exceptions, and memory warnings are automatically collected without user code (for details, [SDK event logging](https://developers-apps-in-toss.toss.im/documentation/unity/add-features/metrics) see note). ### Install the SDK #### Install with Package Manager 1. In the Unity Editor `Window` > `Package Manager` Open 2. top left `+` Click the 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 your 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 Minimum Unity 2021.3 is required, and Unity 6 or later is recommended. All versions after 2021.3 are supported. ### SDK configuration 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 the platform API in C# methods in the form of `DllImport("__Internal")`uses it to connect with JS functions during WebGL builds. * **JS Bridge** (`.jslib`) — This defines the JS functions called from C#, and the logic that actually communicates with the Apps in Toss WebView SDK is here. Both layers are already included in the SDK, so there is no code for you to write directly. ### Installation ref management At the end of the URL `#...` part **installation ref**is. UPM fetches the commit pointed to by this ref as-is, so what you put here determines “when and how it updates.” #### Choosing a ref | ref form | Example | Behavior | | --------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- | | Immutable release tag | `#release/vX.Y.Z` | Permanently pinned to a specific commit. Guarantees reproducible builds and isolates you from unintended updates | | Branch | `#main` | Automatic updater detects changes whenever HEAD moves and shows an update prompt | | Prerelease channel | `#beta`, `#beta-perf` | Moving branch. No automatic update prompt appears, so you must manage updates 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 prearranged 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). #### Re-pull the moving ref to the latest UPM locks git dependencies to `Packages/packages-lock.json`are set to **commit hash.** So `#main`Even if you pinned a moving ref like , reopening Unity alone won't update it. You must unlock it in one of two ways. * **Remove and re-add in Package Manager** — remove the package and add it again with the same URL, and the ref will be reinterpreted. The simplest way. * **Unlock lock** — `Packages/packages-lock.json`in `im.toss.apps-in-toss-unity-sdk` of the item `"hash"` If you delete the value and save, Unity will reinterpret the ref. #### Move to another ref `Packages/manifest.json`Change only the URL fragment in and save it. If the dependency string changes, UPM will resolve the package from scratch, so in that case you don't need the unlocking step above. * Pilot participation: `#release/vX.Y.Z` → `#beta` or `#beta-perf` * Return to stable: `#beta` → `#release/vX.Y.Z` When you revert to the immutable release tag, the automatic updater will track that stable ref again. ### Settings After installing the SDK, in the Unity Editor menu `AIT` > `Configuration`Click to open the settings window. | Settings | 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 displayed as the only required item | | **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** | Image URL to be displayed as the mini app icon. If entered, `http://` or `https://`must start with | ### AIT menu After SDK installation is complete, a `AIT` menu is added to the top of the Unity Editor. | menu | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Dev Server** | Under it are Start / Stop / Restart Server / Restart Server (server-only). `server-only`restarts only the server without rebuilding | | **Production Server** | Under it are Start / Stop / Restart Server / Restart Server (server-only). `server-only`restarts only the server without rebuilding | | **Build & Package** | WebGL build and `.ait` runs packaging at once | | **Publish** | Generated `.ait` uploads the file to the Apps in Toss platform. `Configuration`The deployment key must be set in | | **Clean** | `webgl/`, `ait-build/` deletes the folder containing build artifacts | | **Open Build Output** | opens the folder where the build artifacts are stored | | **Reset Loading Screen** | Restores the loading screen to the SDK default template. For details, [Loading screen customization](https://developers-apps-in-toss.toss.im/documentation/unity/build/loading-screen-customization) Note | | **Configuration** | Opens the mini-app integration settings window such as app ID and display name | | **Install Sentry SDK** | Installs the Sentry Unity SDK. For details, [Sentry integration](https://developers-apps-in-toss.toss.im/documentation/unity/add-features/sentry-integration) Note | | **Report an issue** | Opens a window to report a problem | | **Check for Updates...** | Manually checks whether there is a new SDK release | | **Debug** | Contains debug submenus such as SDK status reset and forced refresh of the WebGL template | The differences in devtools and compression settings between Dev Server and Production Server, and each build profile are [Build Profiles](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles)documented there. ### First build All build entry points are `AIT` are in the menu. How each entry point builds differently and what it does is [Build Profiles](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`Mock SDK and panel run together, so you can mock platform API calls in the browser without the Toss app and directly control mock status from the panel. 1. `AIT` > `Dev Server` > `Start Server` Click 2. Unity WebGL build runs automatically 3. When the build is finished, the local development server starts 4. The browser opens automatically, or you can access 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 results in #### Check on a real device (Deploy Test) To verify the actual Toss app environment (camera, payments, ads, etc.) that can't be checked with browser mocks, use Deploy (Test) on a real device. 1. `AIT` > `Deploy (Test)` Click 2. The 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 (the memo `[Test]` prefix is automatically added) 4. When deployment is finished, scan the QR code in the window that appears with the Toss app or access it via the URL to check it on a real 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 is complete, use the “Open Console” button in the window that appears to go to the Apps in Toss console 3. Request review/release for the build you just deployed in the console — `ait deploy` itself always deploys only to the console QR test environment, and the actual release happens only through this console process ### SDK usage examples The SDK API uses the async/await pattern. `Awaitable`and `Task` What is returned among , and how to handle timeouts and error codes is [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)documented there. #### Query device information ```csharp using AppsInToss; using UnityEngine; public class GameManager : MonoBehaviour { async void Start() { try { // Retrieve device ID string deviceId = await AIT.GetDeviceId(); Debug.Log($"Device ID: {deviceId}"); // Retrieve 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**: In-app purchases require a payment approval callback to be specified. If not specified, 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)Please read the in-app purchase section of first. #### 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}"); } } } ``` ### Testing The SDK API actually goes through the bridge only in WebGL builds, and even then mostly works properly only in the Apps in Toss app environment. In Unity Editor, the Editor mock just returns default values. For details, [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns)the **Mock** section. The procedure for checking a local build with a sandbox app is [Troubleshooting](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/faq) is organized in the document's “It works on Dev Server but not on Production” section. For final verification before release, `.ait` use the file upload test. 1. `AIT` > `Build & Package`as `.ait` Create a file. 2. [Apps in Toss console](https://apps-in-toss.toss.im/)upload it to. 3. Check by running the mini app with a QR code. If there is something blocking you, [Troubleshooting](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/faq) Please refer to the documentation. ### 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 Profiles](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles) — differences in settings 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 fix 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.