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 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.jsonAdd the dependency to

{
  "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.

prerelease channels are announced only to pre-arranged pilot participants. beta channeland perf beta channelfor reference.

Pull the moving ref up to date again

UPM pins git dependencies Packages/packages-lock.jsonto to a commit hash. So #maineven 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.jsonin 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.jsonchange 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 > ConfigurationClick 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-onlyrestarts only the server without rebuilding
Production Server	It contains Start / Stop / Restart Server / Restart Server (server-only). server-onlyrestarts 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. ConfigurationA 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 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 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 profiledocumented there.

First build

All build entry points are AIT in the menu. How each entry point builds differently is Build profiledocumented there.

Check with the development server

Use Dev Server during development. @apps-in-toss/devtoolsThe 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 > ConfigurationEnter it in
3. After an incremental build ait deployis 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. Awaitableand Task which of the following is returned, and how to handle timeouts and error codes, API usage patternsdocumented there.

Get device information

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

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 patternsFirst read the in-app purchase section of

Haptic feedback

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 patternsof Mock section.

The procedure for checking a local build with a sandbox app Troubleshooting 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 & Packageas a .ait Create a file.
2. Apps in Toss consoleUpload to.
3. Run the mini app via QR code to verify it.

If you get stuck, Troubleshooting refer to the document.

Related documents

• API usage patterns — async/await, error handling, Mock
• Build profile — configuration differences by build entry point
• Build customization — modifying web entry points, adding external libraries
• Loading screen customization — replacing the loading screen
• Troubleshooting — common sticking points and how to solve them