앱인토스 미니앱은 WebView SDK나 React Native SDK 중 하나로 만듭니다. 무엇을 고르느냐에 따라 설정 파일, 로컬 테스트 환경, 따라야 할 SDK 버전이 모두 달라지니 시작 전에 차이를 정리해 둡니다.
두 SDK가 같은 부분
두 SDK는 Granite를 공통 런타임으로 씁니다. Granite는 미니앱 실행 환경을 초기화하고 토스 앱과의 통신을 맡습니다. SDK는 카메라, 위치, 결제 UI 같은 네이티브 기능을 미니앱에서 쓰게 해 주는 다리이고, 로그인 토큰 검증이나 결제 승인처럼 서버끼리 주고받는 일은 mTLS로 보호되는 서버 API가 맡습니다.
서버가 꼭 있어야 하는 것은 아닙니다. SDK만으로도 미니앱을 만들 수 있고, 토스 로그인이나 토스페이처럼 서버 간 통신이 필요한 기능을 쓸 때만 자체 서버를 붙입니다. 어느 SDK든 빌드 결과물을 올리고 검수를 거쳐 출시하며, iframe은 쓸 수 없습니다. YouTube 영상을 넣는 용도만 예외입니다.
어떤 미니앱에 어떤 SDK가 맞나
WebView SDK는 이미 운영 중인 웹 서비스를 토스 앱에서 빠르게 실행할 때 맞습니다. WebView 안에서는 일반적인 웹 API 사용을 제한하지 않습니다.
React Native SDK는 네이티브 수준의 성능이나 토스 앱과의 통합이 필요할 때 씁니다. 토스 앱의 네이티브 UI와 결이 맞는 화면, 복잡한 애니메이션이나 제스처가 필요하거나, 팀에 React Native 경험이 있을 때 고릅니다. 다만 네이티브 모듈이 필요한 라이브러리는 앱인토스가 지원하는 범위 안에서만 쓸 수 있습니다.
| 구분 | WebView SDK | React Native SDK |
|---|---|---|
| 맞는 경우 | 운영 중인 웹 서비스를 옮길 때 | 네이티브 수준 UI, 복잡한 애니메이션·제스처 |
| 패키지 | @apps-in-toss/web-framework | @apps-in-toss/framework |
| 현재 SDK | 3.x | 2.x |
| 설정 파일 | apps-in-toss.config.ts | granite.config.ts |
| 화면 이동 | 쓰던 웹 라우터 규칙 그대로 | 파일 기반 라우팅 |
| 로컬 확인 | 로컬 브라우저와 devtools | 샌드박스 앱 |
| 디자인 시스템 | @toss/tds-mobile | @toss/tds-react-native |
고르기 전에 확인할 제약
- 렌더링: 서버 사이드 렌더링(SSR)은 쓸 수 없고 CSR이나 SSG만 됩니다. SSR에 기대는 웹 서비스라면 정적 빌드로 바꿀 수 있는지 먼저 봅니다.
- 통신: API는 https, WebSocket은
wss://만 씁니다. - 보안: 외부에서 받은 코드를
eval처럼 실행하거나,window.location.replace같은 히스토리 조작으로 자사 사이트로 보내는 방식은 쓸 수 없습니다. - 화면 이동: WebView는 프로젝트의 웹 라우터 규칙을 그대로 따릅니다. React Native는
pages아래 파일 경로가intoss://앱이름/경로로 이어지는 파일 기반 라우팅을 씁니다. 자세한 동작은 화면 이동 문서에 있습니다. - React Native 프로젝트는 Granite 1.x로 만들어야 합니다. 다른 버전은 앱인토스 개발 환경과 맞지 않습니다.
- React Native는 샌드박스 앱을 iOS 시뮬레이터, 같은 Wi-Fi의 iOS 실기기, adb로 포트를 연결한 Android 기기에서 띄워 확인합니다. TDS React Native는 로컬 브라우저에서 동작하지 않습니다.
SDK 버전: WebView는 3.x, React Native는 2.x
WebView SDK 3.x는 WebView 프로젝트 구조를 바꾼 업데이트입니다. 파라미터와 반환값은 2.x와 같지만 SDK 내부 처리가 서버로 옮겨져, SDK 문제가 생겨도 미니앱을 다시 배포하지 않고 앱인토스 서버에서 고쳐 반영할 수 있게 됐습니다. 개발자센터 FAQ는 WebView와 Unity 프로젝트에 2026년 9월 14일까지 3.x로 올리라고 안내했으니, 새 WebView 프로젝트는 3.x로 시작합니다.
2.x에서 옮긴다면 npx ait migrate v3가 설정 파일을 apps-in-toss.config.ts로 바꾸고 package.json의 dev, build 스크립트를 고쳐 줍니다. webViewProps는 webView로, outdir은 webBundleDir로 이름이 바뀌고, build 스크립트에는 ait build가 들어가야 합니다.
React Native는 현재 SDK 2.x만 지원합니다. SDK 2.x는 React 19.2.3과 React Native 0.84.0을 쓰므로, 쓰려는 라이브러리가 이 버전에서 동작하는지 먼저 확인합니다. WebView 미니앱은 React 18을 유지해도 됩니다. SDK 1.x로 빌드한 번들은 2026년 3월 23일 이후 콘솔에 올릴 수 없습니다.
개발 흐름에서 SDK 선택이 어디에 오는지는 앱인토스 미니앱 개발 가이드에서 볼 수 있습니다.