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

빌드 커스터마이징 ​

SDK는 2단계 빌드 시스템을 사용해요:

Unity WebGL 빌드 (1단계)  →  Granite 패키징 (2단계)  →  최종 배포 패키지
       webgl/                     ait-build/                ait-build/dist/
단계설명커스터마이징
1단계 Unity WebGL 빌드Unity 프로젝트를 WebGL로 빌드해요빌드 프로필에서 설정 변경
2단계 Granite 패키징WebGL 출력을 Apps in Toss 배포 패키지로 변환해요아래의 커스터마이징 가능한 파일 참조

1단계: Unity WebGL 빌드 ​

SDK는 빌드 시작 시 Unity PlayerSettings를 자동으로 구성해요. 대부분의 설정은 별도 조작 없이 최적값이 적용돼요.

자동 구성 항목 ​

항목기본값비고
WebGL 템플릿PROJECT:AITTemplate자동 선택
압축 포맷프로필에 따라 다름Dev Server: Disabled, 나머지: Brotli
메모리 크기Unity 2022.3: 512MB / Unity 6: 1024MB자동 설정
스레딩비활성화모바일 브라우저 호환성
데이터 캐싱비활성화
링커 타겟Wasm
Stripping Level프로필에 따라 다름Dev Server: Minimal, 나머지: High
Development Build프로필에 따라 다름Dev Server: 활성화, 나머지: 비활성화

2단계: 패키징 커스터마이징 ​

SDK는 WebGL 빌드의 다양한 측면을 커스터마이징할 수 있도록 지원해요.
커스터마이징은 SDK 업데이트 시에도 자동으로 보존돼요.

커스터마이징 가능한 파일 ​

파일위치커스터마이징 방법
index.htmlAssets/WebGLTemplates/AITTemplate/마커 영역에 스크립트/스타일 추가
vite.config.tsAssets/WebGLTemplates/AITTemplate/BuildConfig~/USER_CONFIG 섹션에 플러그인 추가
granite.config.tsAssets/WebGLTemplates/AITTemplate/BuildConfig~/USER_CONFIG 섹션에 설정 추가
package.jsonAssets/WebGLTemplates/AITTemplate/BuildConfig~/dependencies에 npm 패키지 추가
tsconfig.jsonAssets/WebGLTemplates/AITTemplate/BuildConfig~/compilerOptions 커스터마이징 (jsx, paths 등)
src/ 폴더Assets/WebGLTemplates/AITTemplate/BuildConfig~/TypeScript/React 컴포넌트 구조화

index.html 커스터마이징 ​

index.html에서 USER_HEAD와 USER_BODY_END 마커 영역에 커스텀 스크립트나 스타일을 추가할 수 있어요.

HEAD 영역 추가 ​

html
<!-- USER_HEAD_START - 이 영역에 사용자 커스텀 스크립트/스타일을 추가하세요 -->
<script src="https://www.gstatic.com/firebasejs/10.7.0/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.7.0/firebase-analytics-compat.js"></script>
<link rel="stylesheet" href="custom-styles.css" />
<!-- USER_HEAD_END -->

BODY 끝 영역 추가 ​

html
<!-- USER_BODY_END_START - 이 영역에 사용자 커스텀 스크립트를 추가하세요 -->
<script>
  firebase.initializeApp({
    apiKey: 'your-api-key',
    projectId: 'your-project-id',
  });
  firebase.analytics();
</script>
<!-- USER_BODY_END_END -->

npm 패키지 추가 ​

BuildConfig~/package.json의 dependencies에 필요한 패키지를 추가하세요:

json
{
  "dependencies": {
    "@apps-in-toss/web-framework": "2.4.1",
    "lodash-es": "^4.17.21",
    "firebase": "^10.7.0"
  }
}

빌드 시 SDK 패키지와 사용자 패키지가 자동으로 머지돼요.

Vite 플러그인 추가 ​

BuildConfig~/vite.config.ts의 USER_CONFIG 섹션에서 Vite 플러그인을 추가할 수 있어요:

typescript
//// USER_CONFIG_START ////
const userConfig = defineConfig({
  plugins: [
    // 사용자 플러그인 추가
  ],
  define: {
    __CUSTOM_FLAG__: JSON.stringify(true),
  },
});
//// USER_CONFIG_END ////

tsconfig.json 커스터마이징 ​

BuildConfig~/tsconfig.json을 생성해서 TypeScript 컴파일러 옵션을 커스터마이징할 수 있어요.
프로젝트 옵션과 SDK 필수 옵션이 자동으로 머지돼요:

json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "paths": {
      "@/*": ["./src/*"]
    },
    "baseUrl": "."
  },
  "include": ["src", "*.ts", "*.tsx"]
}

INFO

SDK 필수 옵션(moduleResolution, esModuleInterop)은 SDK 값으로 강제 적용되어 호환성이 보장돼요.

React/TypeScript 컴포넌트 사용 ​

BuildConfig~/ 폴더에 src/ 등 하위 폴더 구조를 생성해서 TypeScript/React 컴포넌트를 구조화할 수 있어요.

폴더 구조 예시 ​

Assets/WebGLTemplates/AITTemplate/
├── index.html                    ← USER_BODY_END에서 tsx 파일 참조
└── BuildConfig~/
    ├── package.json              ← React 의존성 추가
    ├── tsconfig.json             ← jsx 옵션 추가
    ├── vite.config.ts            ← React 플러그인 추가
    └── src/
        ├── main.tsx              ← 진입점
        └── components/
            └── GameUI.tsx        ← React 컴포넌트

1. package.json에 React 의존성 추가 ​

json
{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^4.0.0"
  }
}

2. tsconfig.json 생성 ​

json
{
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src"]
}

3. vite.config.ts에 플러그인 추가 ​

typescript
//// USER_CONFIG_START ////
import react from '@vitejs/plugin-react';

const userConfig = defineConfig({
  plugins: [react()],
});
//// USER_CONFIG_END ////

4. index.html에서 진입점 참조 ​

html
<!-- USER_BODY_END_START -->
<script type="module" src="./src/main.tsx"></script>
<!-- USER_BODY_END_END -->

5. React 컴포넌트 작성 ​

BuildConfig~/src/main.tsx:

tsx
import React from 'react';
import { createRoot } from 'react-dom/client';

function GameUI() {
  return <div id="game-ui">게임 UI</div>;
}

const container = document.getElementById('ui-root');
if (container) {
  createRoot(container).render(<GameUI />);
}

빌드 결과물 구조 ​

2단계 패키징이 완료되면 ait-build/ 디렉토리에 다음과 같은 구조가 생성돼요:

ait-build/
├── index.html              ← Unity 플레이스홀더 치환 완료
├── public/
│   ├── Build/              ← Unity WebGL 빌드 파일
│   ├── TemplateData/       ← 스타일, 이미지
│   ├── Runtime/            ← 플랫폼 브릿지 (appsintoss-unity-bridge.js)
│   └── StreamingAssets/    ← StreamingAssets (있는 경우)
├── src/                    ← 사용자 TypeScript 코드 (있는 경우)
├── package.json            ← SDK + 사용자 의존성 머지
├── vite.config.ts          ← SDK + 사용자 설정 머지
├── granite.config.ts       ← 앱 메타데이터 플레이스홀더 치환 완료
├── tsconfig.json           ← SDK + 사용자 옵션 머지
└── dist/                   ← 최종 배포 패키지 (granite build 결과)

SDK 업데이트 시 동작 ​

SDK를 업데이트해도 사용자 커스터마이징은 자동으로 보존돼요:

상황동작
마커가 있는 템플릿사용자 영역 보존, SDK 영역만 업데이트
마커가 없는 이전 템플릿새 템플릿으로 교체 + 수동 마이그레이션 안내