SDK 포팅

SDK 포팅은 Unity 프로젝트를 앱인토스 환경에 가장 빠르게 포팅하는 방법입니다.
Unity 전용으로 제공되는 앱인토스 유니티 패키지를 설치하면,
Vite 프로젝트 구성이나 JS Bridge 구현 없이 바로 앱인토스 기능을 사용할 수 있어요.

SDK 포팅이란?

SDK 포팅은 앱인토스 연동에 필요한 과정을 Unity 안에서 자동으로 처리하는 방식이에요.

WebView SDK 연동을 위한 JS Bridge가 기본 포함되어 있어요.
Unity에서 바로 C# 코드로 앱인토스 API를 호출할 수 있어요.
WebGL 빌드부터 .ait 파일 생성까지 한 번에 자동화돼요.

따라서 기존처럼 Vite 프로젝트를 만들고 WebGL을 감싸거나 postMessage를 직접 구현할 필요가 없어요.

언제 사용하면 좋을까요?

Unity 코드만으로 앱인토스 미니앱 포팅을 끝내고 싶을 때
JS Bridge를 직접 작성하고 싶지 않을 때
앱인토스 기능을 C# 코드에서 바로 호출하고 싶을 때
자동화된 빌드로 빠르게 .ait 파일을 만들고 싶을 때

패키지 구성요소

앱인토스 유니티 패키지는 WebGL 환경에서 앱인토스 SDK를 사용할 수 있도록
C# API Layer와 JavaScript Bridge(.jslib) 두 가지를 함께 제공합니다.

1. C# Header (C# API Wrapper)

Unity C# 코드에서 앱인토스 기능을 직접 호출할 수 있도록 제공되는 API입니다.

앱인토스 API를 C# 메서드로 감싸 편리하게 사용할 수 있어요.
내부적으로 DllImport("__Internal")를 사용해 WebGL 빌드 시 JS 함수와 연결돼요.
별도의 JavaScript 없이 C# 코드만으로 앱인토스를 연동할 수 있어요.

예시:

csharp

public static async Task<string> GetClipboardText()
{
#if UNITY_WEBGL && !UNITY_EDITOR
    var tcs = new TaskCompletionSource<string>();
    string callbackId = AITCore.Instance.RegisterCallback<string>(
        result => tcs.TrySetResult(result),
        error => tcs.TrySetException(error)
    );
    __getClipboardText_Internal(callbackId, "string");
    return await tcs.Task;
#else
    // Unity Editor mock implementation
    UnityEngine.Debug.Log($"[AIT Mock] GetClipboardText called");
    await Task.CompletedTask;
    return "";
#endif
}
#if UNITY_WEBGL && !UNITY_EDITOR
        [System.Runtime.InteropServices.DllImport("__Internal")]
        private static extern void __getClipboardText_Internal(string callbackId, string typeName);
#endif

2. JavaScript Bridge (.jslib)

.jslib 파일은 Unity WebGL 환경에서 C#과 JavaScript를 연결하는 브릿지 역할을 합니다.

C#에서 호출하는 JS 함수들이 이 파일에 정의돼요.
실제로 앱인토스 WebView SDK와 통신하는 로직도 여기에서 처리돼요.
JS → C# 호출 역시 지원해 양방향 메시징 구조를 만들 수 있어요.

예시:

mergeInto(LibraryManager.library, {
    __getClipboardText_Internal: function(callbackId, typeName) {
        // 비동기 함수 (Promise 반환)
        var callback = UTF8ToString(callbackId);
        var typeNameStr = UTF8ToString(typeName);

        console.log('[AIT jslib] getClipboardText called, callbackId:', callback);

        try {
            var promiseResult = window.AppsInToss.getClipboardText();
            console.log('[AIT jslib] getClipboardText returned:', promiseResult, 'isPromise:', promiseResult && typeof promiseResult.then === 'function');

            if (!promiseResult || typeof promiseResult.then !== 'function') {
                // Promise가 아닌 경우 (undefined, null 등) - 즉시 응답
                console.log('[AIT jslib] getClipboardText did not return a Promise, sending immediate response');
                var payload = JSON.stringify({
                    CallbackId: callback,
                    TypeName: typeNameStr,
                    Result: JSON.stringify({ success: true, data: JSON.stringify(promiseResult), error: '' })
                });
                SendMessage('AITCore', 'OnAITCallback', payload);
                return;
            }

            promiseResult
                .then(function(result) {
                    console.log('[AIT jslib] getClipboardText resolved:', result);
                    var payload = JSON.stringify({
                        CallbackId: callback,
                        TypeName: typeNameStr,
                        Result: JSON.stringify({ success: true, data: JSON.stringify(result), error: '' })
                    });
                    SendMessage('AITCore', 'OnAITCallback', payload);
                })
                .catch(function(error) {
                    console.log('[AIT jslib] getClipboardText rejected:', error);
                    var payload = JSON.stringify({
                        CallbackId: callback,
                        TypeName: typeNameStr,
                        Result: JSON.stringify({ success: false, data: '', error: error.message || String(error) })
                    });
                    SendMessage('AITCore', 'OnAITCallback', payload);
                });
        } catch (error) {
            console.log('[AIT jslib] getClipboardText sync error:', error);
            var payload = JSON.stringify({
                CallbackId: callback,
                TypeName: typeNameStr,
                Result: JSON.stringify({ success: false, data: '', error: error.message || String(error) })
            });
            SendMessage('AITCore', 'OnAITCallback', payload);
        }
    },

});

설치 방법

앱인토스 유니티 패키지는 Unity Package Manager를 통해 Git URL로 설치할 수 있어요.
이 방법이 가장 간단하고, 패키지 업데이트도 쉽게 관리할 수 있기 때문에 권장해요.

1. Package Manager 열기

Unity 에디터에서 Window → Package Manager 를 선택합니다.

2. Git URL로 설치

왼쪽 상단의 + 버튼을 클릭하고
Add package from git URL... 을 선택한 뒤
제공된 Git URL을 입력하고 Install를 눌러 설치를 진행합니다.

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

3. 설치 완료 확인

설치가 정상적으로 완료되면:

Package Manager 목록에 AppsInToss SDK가 표시되고
Unity 메뉴 상단에 AIT 항목이 새로 추가돼요.
Packages/Apps In Toss SDK/Runtime/SDK 경로 아래에 AIT.*.cs 파일들이 생성돼요.
Packages/Apps In Toss SDK/Runtime/SDK/Plugins/*.jslib 파일도 함께 제공돼요.

AIT 메뉴 살펴보기

앱인토스 유니티 패키지가 설치되면 Unity 에디터 상단에 AIT 메뉴가 추가돼요.
이 메뉴에서 WebGL 빌드, 패키징(.ait 생성), 테스트 서버 실행 등 SDK 포팅 과정에 필요한 대부분의 기능을 사용할 수 있습니다.

아래는 각 메뉴의 기능이에요.

Dev Server

개발용 테스트 서버를 실행하거나 종료해요.
WebGL 빌드 결과물을 로컬 환경에서 빠르게 확인할 때 사용해요.

Production Server

서비스용(배포용) 환경에서 실행할 때 사용하는 서버 도구예요.
Dev Server와 달리, 디버깅 기능이나 Mock 브릿지가 비활성화되어 있어
최종 패키징 전에 실제 배포 환경과 유사한 테스트를 진행할 수 있어요.

Build

Unity 프로젝트를 WebGL로 빌드해요. SDK가 필요한 설정을 자동으로 적용해 WebGL 플레이어를 생성합니다.

Package

WebGL 빌드 결과물을 앱인토스 형식으로 패키징해요.
.ait 파일이 생성되며, 미니앱 QR 테스트나 배포에 사용돼요.

Build & Package

WebGL 빌드 + .ait 패키징을 한 번에 실행해요.
가장 자주 사용하는 옵션이에요.

Publish

생성된 .ait 파일을 앱인토스 콘솔로 업로드하는 기능이에요.
Configuration 에 배포 키(API Key)가 등록되어야해요.
테스트 또는 배포 단계에서 편리하게 사용할 수 있어요.

Clean

이전 빌드 결과물을 삭제해요.
깨끗한 상태에서 다시 빌드하고 싶을 때 사용합니다.

Open Build Output

빌드 결과물이 저장된 폴더를 바로 열어요.
WebGL 빌드 파일과 .ait 출력 파일을 빠르게 확인할 수 있어요.

Configuration

앱인토스 미니앱 포팅과 관련된 빌드 옵션을 설정하는 메뉴예요.
.ait 패키징을 위해 빌드 전 꼭 설정해야해요.

꼭 입력해야할 정보

아래 항목들은 .ait 패키지를 생성할 때 반드시 필요해요.

앱 ID
- 앱인토스 콘솔에 등록한 appName과 동일해야 해요.
표시 이름
- 앱에서 노출될 이름이에요.
아이콘
- 테스트 단계에서는 없어도 되지만, 실제 배포 시에는 반드시 등록해야 해요.

서버 설정의 Granite, Vite 관련 항목은 샌드박스앱 테스트시 이용돼요.

Debug

디버그 도구를 모아둔 메뉴예요.
로그를 확인하거나 내부 상태를 점검할 때 사용합니다.

SDK 사용하기

앱인토스 유니티 SDK를 설치하면 C# 코드에서 바로 AIT.* API를 호출할 수 있어요.
JS Bridge를 직접 작성할 필요 없이, 앱인토스 기능들을 Unity 코드만으로 사용할 수 있는 방식이에요.

아래는 가장 기본적인 API 호출 흐름과 예제입니다.

API 호출 기본 구조

앱인토스 API는 대부분 비동기(async) 방식으로 동작해요:

csharp

var result = await AIT.SomeApi(options);

성공 시 API별 결과 모델이 반환돼요.
실패 시 AITException이 발생할 수 있어 예외 처리가 필요해요.
WebView 환경에서 JS ↔ Unity 간 메시지 교환을 통해 실행돼요.

사용 가능한 전체 AIT API 목록은 앱인토스 SDK 레퍼런스에서 확인할 수 있어요.

Unity SDK에서는 모든 API를 AIT.* 형태로 동일하게 호출할 수 있어요.
예를 들어, 웹뷰 SDK의 getDeviceId 는 아래처럼 PascalCase로 호출해요.

csharp

var result = await AIT.GetDeviceId(options);

예제

csharp

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

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

            // 플랫폼 OS 조회
            PlatformOS os = await AIT.GetPlatformOS();
            Debug.Log($"Platform: {os}");

            // 네트워크 상태 확인
            NetworkStatus status = await AIT.GetNetworkStatus();
            Debug.Log($"Network: {status}");
        }
        catch (AITException ex)
        {
            Debug.LogError($"API 호출 실패: {ex.Message} (code: {ex.Code})");
        }
    }

    // 햅틱 피드백 예제
    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($"햅틱 피드백 실패: {ex.Message}");
        }
    }
}

사용 시 주의사항

앱인토스 AIT API는 일반 브라우저 환경에서는 작동하지 않아요.
앱인토스 실행 환경에서만 기능을 사용할 수 있어요.

테스트 가능한 환경은 다음 두 가지예요:

앱인토스 샌드박스 앱
- 개발 중 기능 검증을 위해 제공되는 테스트 앱이에요.
- Unity WebGL 빌드를 실행하고 AIT API가 정상적으로 연결되는지 확인할 수 있어요.
- 샌드박스앱은 여기에서 다운로드 받을 수 있어요.

자세한 테스트 방법은 여기를 참고해주세요.

.ait 파일 업로드 후 미니앱 테스트 실행
- AIT 메뉴에서 Build & Package로 .ait 파일 생성
- 앱인토스 콘솔에 업로드
- QR 코드로 미니앱 실행

자세한 테스트 방법은 여기를 참고해주세요.

SDK 포팅 ​

SDK 포팅이란? ​

언제 사용하면 좋을까요? ​

패키지 구성요소 ​

1. C# Header (C# API Wrapper) ​

2. JavaScript Bridge (.jslib) ​

설치 방법 ​

1. Package Manager 열기 ​

2. Git URL로 설치 ​

3. 설치 완료 확인 ​

AIT 메뉴 살펴보기 ​

Dev Server ​

Production Server ​

Build ​

Package ​

Build & Package ​

Publish ​

Clean ​

Open Build Output ​

Configuration ​

Debug ​

SDK 사용하기 ​

API 호출 기본 구조 ​

예제 ​

사용 시 주의사항 ​

SDK 포팅

SDK 포팅이란?

언제 사용하면 좋을까요?

패키지 구성요소

1. C# Header (C# API Wrapper)

2. JavaScript Bridge (.jslib)

설치 방법

1. Package Manager 열기

2. Git URL로 설치

3. 설치 완료 확인

AIT 메뉴 살펴보기

Dev Server

Production Server

Build

Package

Build & Package

Publish

Clean

Open Build Output

Configuration

Debug

SDK 사용하기

API 호출 기본 구조

예제

사용 시 주의사항