기존 웹 프로젝트에 SDK 연동하기

이미 운영 중인 웹 프로젝트에 SDK를 직접 설치해 미니앱으로 전환할 수 있어요.

---

1. SDK 설치 및 초기화하기

SDK를 설치한 뒤 환경을 초기화해 주세요.

npm

npm install @apps-in-toss/web-framework
npx ait init

pnpm

pnpm add @apps-in-toss/web-framework
pnpm ait init

yarn

yarn add @apps-in-toss/web-framework
yarn ait init

---

2. 설정 파일 수정하기

프로젝트를 생성하면 granite.config.ts 파일이 자동으로 만들어져요. appName, displayName, icon을 앱인토스 콘솔에 등록한 앱 정보와 동일하게 수정해 주세요.

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'my-mini-app', // 콘솔에 입력한 appName을 입력하세요.
  brand: {
    displayName: '앱 이름', // 콘솔에 입력한 앱 이름을 입력하세요.
    primaryColor: '#FF91D5', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
    icon: '', // 콘솔에서 업로드한 이미지의 URL을 입력하세요.(콘솔의 앱 정보에서 업로드한 이미지를 우클릭해 링크 복사 후 넣어주세요)
  },
  web: {
    host: 'localhost',
    port: 5173,
    commands: {
      dev: 'vite dev',
      build: 'vite build',
    },
  },
  permissions: [],
  outdir: 'dist',
});

중요해요

• appName은 각 앱을 식별하는 고유한 키로 사용돼요.
• intoss://{appName} 형태의 딥링크 경로나 테스트·배포 시에도 사용돼요.
• 샌드박스 앱에서 테스트할 때도 intoss://{appName}으로 접근해요. 단, 출시하기 메뉴의 QR 코드로 테스트할 때는 intoss-private://{appName}이 사용돼요.

---

3. TDS 설치하기

TDS(Toss Design System) WebView 패키지를 사용하면 토스 디자인 시스템 기반의 컴포넌트를 쉽게 적용할 수 있어요.

npm

npm install @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18

pnpm

pnpm add @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18

yarn

yarn add @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18

TDS 컴포넌트 사용법과 가이드는 TDS WebView 문서를 확인해 주세요.

---

4. 프로젝트 실행하기

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn dev

---

5. 미니앱 실행하기

개발 서버가 실행되면 샌드박스 앱에서 미니앱을 확인할 수 있어요. 로컬 샌드박스 앱에서 테스트하는 자세한 방법은 샌드박스앱 문서를 확인해 주세요.

실기기에서 개발 서버 접근하기

실기기에서 테스트하려면 번들러 실행 시 --host 옵션을 활성화하고, web.host를 실기기에서 접근할 수 있는 네트워크 주소로 설정해야 해요.

import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'ping-pong',
  web: {
    host: '192.168.0.100', // 실기기에서 접근할 수 있는 IP 주소로 변경
    port: 5173,
    commands: {
      dev: 'vite --host', // --host 옵션 활성화
      build: 'vite build',
    },
  },
  permissions: [],
});

설정이 완료되면 실기기에서 다음 순서로 진행해 주세요.

1. 샌드박스 앱 설치하기를 참고해 기기에 맞는 샌드박스 앱을 설치해요.
2. 샌드박스 앱에서 Metro 서버 주소를 web.host에 설정한 IP 주소로 변경해요.
3. intoss://{appName} 딥링크로 미니앱에 접근해요.

---

6. 디버깅하기

Android — Chrome DevTools

준비가 필요해요

디바이스에서 디버깅하려면 USB 디버깅을 먼저 활성화해야 해요. 설정 → 시스템 → 휴대전화 정보 → 개발자 옵션 → USB 디버깅 활성화

1. Android 에뮬레이터나 실기기에서 미니앱을 실행해요.
2. Chrome 브라우저에서 chrome://inspect/#devices 페이지를 열어요.
3. Remote Target에서 디버깅할 WebView 콘텐츠 아래 inspect 버튼을 선택해요.
4. 일반 웹 페이지를 디버깅하듯 WebView 콘텐츠를 디버깅할 수 있어요.

iOS — Safari 개발자 도구

준비가 필요해요

• Safari 개발자 메뉴를 활성화해야 해요. Safari 환경설정 → 고급 탭 → 웹 개발자를 위한 기능 보기 체크박스 활성화
• 디바이스에서 디버깅하려면 Web Inspector(웹 검사기)를 활성화해야 해요. 설정 → Safari → 고급 → Web Inspector 활성화
• 개발자용 메뉴에 디바이스가 표시되지 않으면 Safari를 재시작해 보세요.

1. iOS 시뮬레이터 또는 실기기에서 미니앱을 실행해요.
2. Safari 상단 메뉴 개발자용 → [디바이스 이름] → [앱 이름] → [URL - 제목]을 선택해요.
3. 웹에서 디버깅하듯 WebView 콘텐츠를 디버깅할 수 있어요.

---

7. 빌드하고 토스앱에서 최종 테스트하기

샌드박스 앱에서 개발과 기본 검증이 끝나면 npm run build로 앱 번들을 생성한 뒤, 콘솔에 업로드해 최종 테스트를 진행해 주세요. 토스앱 테스트를 완료해야 출시 요청을 보낼 수 있어요. 자세한 방법은 토스앱 테스트하기 문서를 참고해 주세요.

---

8. 출시하기

출시하는 방법은 미니앱 출시 문서를 참고해 주세요.