이 내용이 도움이 되었나요?

시작하기 ​

앱인토스 미니앱은 웹 기반으로 동작해요. Unity 게임을 미니앱으로 만들려면 프로젝트를 WebGL로 빌드해야 해요.
WebGL 빌드를 통해 Unity 게임이 브라우저에서 실행 가능한 형태로 변환되고, 이를 앱인토스 환경에서 미니앱으로 제공할 수 있어요.

Unity 전용으로 제공되는 앱인토스 유니티 패키지를 설치하면,
Vite 프로젝트 구성이나 JS Bridge 구현 없이 WebGL 빌드부터 미니앱 패키징까지 한 번에 처리할 수 있어요.

SDK 연동이란? ​

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

  • WebView SDK 연동을 위한 JS Bridge가 기본으로 포함돼 있어요.
  • Unity에서 C# 코드로 앱인토스 API를 바로 호출할 수 있어요.
  • WebGL 빌드부터 .ait 파일 생성까지 한 번에 자동화돼요.
  • 크래시 발생률, 로딩 시간, FPS 같은 게임 성능 메트릭이 자동으로 수집돼요.

미니앱을 Unity로 개발한다면, Unity SDK를 기준으로 진행하는 걸 권장해요.

SDK 설치 ​

방법 1: Package Manager (권장) ​

  1. Unity Editor에서 Window > Package Manager를 열어요.

  1. 왼쪽 상단 + 버튼을 클릭하고 Add package from git URL...을 선택해요.
  2. Git URL을 입력하고 Install을 눌러 설치해요.
https://github.com/toss/apps-in-toss-unity-sdk.git

버전 고정

특정 버전을 고정하려면 #release/v2.4.5와 같이 릴리즈 태그를 사용하세요.
릴리즈 목록은 GitHub Releases에서 확인할 수 있어요.

방법 2: manifest.json 직접 수정 ​

프로젝트의 Packages/manifest.json 파일에 직접 추가할 수도 있어요:

json
{
  "dependencies": {
    "im.toss.apps-in-toss-unity-sdk": "https://github.com/toss/apps-in-toss-unity-sdk.git#release/v2.4.5"
  }
}

지원 Unity 버전 ​

  • 최소 버전: Unity 2021.3
  • 권장 버전: Unity 6 이상
  • Unity 2021.3 이후의 모든 버전을 지원해요.

설치 완료 확인 ​

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

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

패키지 구성요소 ​

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

C# API Wrapper ​

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

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

JavaScript Bridge (.jslib) ​

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

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

AIT 메뉴 ​

앱인토스 유니티 패키지가 설치되면 Unity Editor 상단에 AIT 메뉴가 추가돼요.
이 메뉴에서 WebGL 빌드, 패키징, 테스트 서버 실행 등 연동 과정에 필요한 대부분의 기능을 사용할 수 있어요.

메뉴설명
Dev Server개발용 테스트 서버를 실행해요. Mock 브릿지가 활성화되어 로컬 브라우저에서 테스트할 수 있어요.
Production Server프로덕션 설정으로 로컬 서버를 실행해요. 실제 배포 환경과 유사한 테스트를 진행할 수 있어요.
Build & PackageWebGL 빌드 + .ait 패키징을 한 번에 실행해요. 가장 자주 사용하는 옵션이에요.
Publish.ait 파일을 앱인토스 콘솔로 업로드해요. Configuration에 배포 키가 등록되어야 해요.
Clean이전 빌드 결과물을 삭제해요.
Open Build Output빌드 결과물이 저장된 폴더를 바로 열어요.
Configuration앱인토스 미니앱 연동과 관련된 빌드 옵션을 설정해요.
Debug로그를 확인하거나 내부 상태를 점검할 수 있어요.

설정 (Configuration) ​

SDK 설치 후 Unity Editor 메뉴에서 AIT > Configuration을 클릭해서 설정 패널을 열어요.

필수 설정 ​

설정설명
앱 ID앱인토스 콘솔에 등록한 appName과 동일해야 해요
앱 아이콘 URL미니앱 아이콘으로 표시될 이미지 URL (필수)
표시 이름로딩 화면에 표시될 앱 이름
기본 색상브랜드 색상 (진행률 바 등에 사용)

TIP

  • 앱 ID는 앱인토스 콘솔에 등록한 appName과 동일해야 해요.
  • 아이콘은 테스트 단계에서는 없어도 되지만, 실제 배포 시에는 반드시 등록해야 해요.
  • 서버 설정의 Granite, Vite 관련 항목은 샌드박스 앱 테스트 시 이용돼요.

빌드 옵션별 상세 설정은 빌드 프로필 문서를 참고해 주세요.

첫 번째 빌드 ​

1. 설정 확인 ​

  1. AIT > Configuration 메뉴에서 설정을 확인해요.
  2. 앱 아이콘 URL이 입력되어 있는지 확인해 주세요 (필수).

2. 개발 서버 실행 ​

개발 단계에서는 Dev Server 모드를 사용해요:

  1. AIT > Dev Server > Start Server 메뉴를 클릭해요.
  2. Unity WebGL 빌드가 자동으로 실행돼요.
  3. 빌드 완료 후 로컬 개발 서버가 시작돼요.
  4. 브라우저에서 자동으로 열리거나, 콘솔에 표시된 URL로 접속할 수 있어요.

3. 프로덕션 빌드 ​

배포용 빌드를 생성하려면:

  1. AIT > Build & Package 메뉴를 클릭해요.
  2. 빌드 완료 후 ait-build/dist/ 폴더에서 결과물을 확인할 수 있어요.

4. 배포 ​

Apps in Toss 플랫폼에 배포하려면:

  1. AIT > Publish 메뉴를 클릭해요.
  2. 배포 키가 설정되어 있어야 해요 (Configuration에서 설정).

SDK 사용하기 ​

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

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

csharp
var result = await AIT.SomeApi(options);
  • 성공 시 API별 결과 모델이 반환돼요.
  • 실패 시 AITException이 발생할 수 있어 예외 처리가 필요해요.

사용 가능한 전체 AIT API 목록은 앱인토스 SDK 레퍼런스에서 확인할 수 있어요.
웹뷰 SDK의 getDeviceId는 Unity SDK에서 AIT.GetDeviceId()처럼 PascalCase로 호출해요.

자세한 사용 패턴은 API 사용 패턴 문서를 참고해 주세요.

예제 ​

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}");
        }
    }
}

샘플 코드 확인하기

아래 파일들은 인앱광고 / 인앱결제를 실제로 어떻게 사용하는지 확인할 수 있는 E2E 테스트용 샘플 코드예요.

테스트하기 ​

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

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

1. 샌드박스 앱에서 테스트 ​

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

2. .ait 파일 업로드 후 테스트 ​

  1. AIT 메뉴에서 Build & Package로 .ait 파일을 생성해요.
  2. 앱인토스 콘솔에 업로드해요.
  3. QR 코드로 미니앱을 실행해요.

자세한 방법은 토스앱에서 테스트하기 문서를 참고해 주세요.