Apps in Toss 플랫폼을 위한 Unity/Tuanjie 엔진 SDK입니다.
Unity 엔진 또는 Tuanjie 엔진으로 게임 프로젝트를 생성/열기한 후,
Unity Editor 메뉴바에서 Window - Package Manager - 오른쪽 상단 + 버튼 - Add package from git URL...을 클릭하여 본 저장소 Git 리소스 주소를 입력하면 됩니다.
- 최소 버전: Unity 2021.3 LTS
- 권장 버전: Unity 2022.3 LTS 이상
- Tuanjie Engine 지원
- WebGL 최적화: Apps in Toss 환경에 최적화된 WebGL 빌드
- 자동 변환: Unity 프로젝트를 Apps in Toss 미니앱으로 자동 변환
- 성능 최적화: 모바일 환경에 최적화된 성능 튜닝
- 결제: 토스페이 결제 연동 (
CheckoutPayment) - 사용자 인증: 앱 로그인 및 사용자 정보 (
AppLogin,GetUserKeyForGame) - 기기 정보: 기기 ID, 플랫폼, 네트워크 상태 조회
- 권한 관리: 카메라, 연락처 등 권한 요청 및 확인
- 위치 서비스: 현재 위치 조회
- 피드백: 햅틱 피드백, 클립보드 접근
- 공유: 컨텐츠 공유 기능
Package Manager에서 Git URL로 설치하거나, Packages/manifest.json에 직접 추가:
{
"dependencies": {
"im.toss.apps-in-toss-unity-sdk": "https://github.com/toss/apps-in-toss-unity-sdk.git#release/v1.5.2"
}
}Unity Editor에서 Apps in Toss > Build & Deploy Window 메뉴를 클릭하여 설정 패널을 열고:
- 앱 ID 입력
- 아이콘 URL 입력 (필수)
- 빌드 설정 구성
SDK API는 async/await 패턴을 사용합니다:
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 Task RequestPayment()
{
try
{
var options = new CheckoutPaymentOptions {
// 결제 옵션 설정
};
CheckoutPaymentResult result = await AIT.CheckoutPayment(options);
Debug.Log($"Payment result: {result.paymentKey}");
}
catch (AITException ex)
{
Debug.LogError($"결제 실패: {ex.Message}");
}
}
// 햅틱 피드백 예제
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 > Configuration메뉴에서 설정 확인- 메뉴에서 원하는 작업 선택:
AIT > Dev Server > Start Server: 로컬 개발 서버 실행AIT > Production Server > Start Server: 프로덕션 환경 로컬 확인AIT > Build & Package: 배포용 패키지 생성AIT > Publish: Apps in Toss에 배포
- 빌드 완료 후
ait-build/dist/폴더에서 결과물 확인
SDK는 각 작업 메뉴별로 다른 빌드 설정(프로필)을 자동 적용합니다.
| 작업 | Mock 브릿지 | 디버그 심볼 | 디버그 콘솔 | LZ4 압축 |
|---|---|---|---|---|
| Dev Server | ✅ 활성화 | Embedded | ✅ 활성화 | ✅ 활성화 |
| Production Server | ❌ 비활성화 | External | ❌ 비활성화 | ✅ 활성화 |
| Build & Package | ❌ 비활성화 | External | ❌ 비활성화 | ✅ 활성화 |
| Publish | ❌ 비활성화 | External | ❌ 비활성화 | ✅ 활성화 |
- Mock 브릿지: 로컬 브라우저에서 테스트할 때 네이티브 API 없이 동작하도록 Mock 구현 사용
- 디버그 심볼:
External은 심볼을 별도 파일로 분리하여 빌드 크기 감소,Embedded는 빌드에 포함 - 디버그 콘솔: 개발/테스트용 콘솔 UI 활성화
- LZ4 압축: 빌드 속도 향상을 위한 LZ4 압축 사용
AIT > Configuration 메뉴에서 각 프로필의 설정을 변경할 수 있습니다:
- "빌드 프로필" 섹션 확장
- 원하는 프로필(Dev Server, Production Server 등)을 펼치기
- 각 옵션의 체크박스를 변경
- 변경 사항은 자동 저장됨
CI/CD 환경이나 자동화 스크립트에서 환경 변수를 통해 빌드 프로필 설정을 오버라이드할 수 있습니다.
| 환경 변수 | 설명 | 값 |
|---|---|---|
AIT_DEBUG_CONSOLE |
디버그 콘솔 활성화 | true/false |
사용 예시:
# 로컬 테스트
AIT_DEBUG_CONSOLE=true ./run-local-tests.sh --all
# Unity 직접 실행
AIT_DEBUG_CONSOLE=true /Applications/Unity/Hub/Editor/2022.3.62f1/Unity.app/Contents/MacOS/Unity \
-quit -batchmode -projectPath ./MyProject \
-executeMethod AITConvertCore.CommandLineBuildGitHub Actions 예시:
- name: Build with Debug Console
env:
AIT_DEBUG_CONSOLE: "true"
run: |
unity -executeMethod E2EBuildRunner.CommandLineBuild ...빌드 시작 시 적용된 프로필이 Console에 출력됩니다:
[AIT] ========================================
[AIT] 빌드 프로필: Dev Server
[AIT] ========================================
[AIT] Mock 브릿지: 활성화
[AIT] 디버그 심볼: Embedded
[AIT] 디버그 콘솔: 활성화
[AIT] LZ4 압축: 활성화
[AIT] ========================================
SDK는 시스템에 Node.js가 설치되어 있지 않아도 자동으로 내장 Node.js를 다운로드합니다. 다운로드 다이얼로그가 표시되면 "다운로드"를 선택하세요.
Build & Deploy Window에서 앱 아이콘 URL을 반드시 입력해야 합니다. 이 URL은 Apps in Toss 앱에서 미니앱 아이콘으로 표시됩니다.
SDK API는 WebGL 빌드에서만 실제로 동작합니다. Unity Editor에서는 Mock 구현이 호출되어 테스트 로그만 출력됩니다. 실제 동작은 WebGL로 빌드 후 Apps in Toss 앱에서 확인하세요.
저장소를 클론한 후, Git hooks를 활성화하세요:
./.githooks/setup.sh이 스크립트는 .meta 파일 누락 검사를 위한 pre-commit hook을 설정합니다.
Unity 패키지의 Editor/, Runtime/, WebGLTemplates/ 디렉토리 내 모든 파일은 반드시 .meta 파일이 함께 있어야 합니다.
- pre-commit hook: 커밋 시 자동으로
.meta파일 누락 검사 - CI 검사: PR 생성 시 GitHub Actions에서 자동 검증
.meta 파일이 누락된 경우:
- Unity Editor에서 프로젝트를 열어 자동 생성
- 또는 기존
.meta파일을 참고하여 수동 생성 (고유 GUID 필요)
모든 커밋 메시지는 한국어로 작성합니다:
<타입>: <설명>
타입 예시:
기능: 새로운 기능 추가수정: 버그 수정개선: 기존 기능 개선리팩토링: 코드 구조 개선문서: 문서 변경테스트: 테스트 추가/수정빌드: 빌드 설정 변경
예시:
기능: 사용자 인증 API 추가
수정: WebGL 빌드 오류 해결
개선: 빌드 성능 최적화