[앱인토스] WebView 미니앱 테스트 방법

앱인토스 WebView 미니앱을 개발하면서 테스트 환경 구성에서 생각보다 삽질을 많이 했어요.

공식 문서만으로는 파악하기 어려운 부분들이 있거든요.

특히 iOS 무선 테스트 설정과 배포 후 실기기 테스트 과정이 처음엔 헷갈리기 쉬운데, 직접 겪은 내용을 단계별로 정리했어요.

 

1. 개발 환경 구성

: 기본적으로 apps-in-toss/web-framework 의 프레임워크를 사용하고, 빌드 번들 파일(배포용 패키지)의 설정을 해줍이다.

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

 

npx ait init 명령어를 실행하면 granite.config.ts 파일이 생성됩니다.

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

export default defineConfig({
  appName: 'my-app',           // 앱인토스 콘솔에서 등록한 앱 이름과 동일해야 함
  brand: {
    displayName: '내 앱 이름',
    primaryColor: '#3182F6',
    icon: '',
  },
  web: {
    host: 'localhost',
    port: 5173,
    commands: {
      dev: 'vite',
      build: 'vite build',
    },
  },
  permissions: [],
  webViewProps: {
    type: 'partner',           // partner | external | game
  },
});

appName이 추후 intoss://{appName} 형태의 딥링크에 사용됩니다.

 

2. 테스트 하기

: 앱인토스 미니앱은 일반 브라우저에서 테스트할 수 없습니다. 반드시 앱인토스 샌드박스 앱을 통해서만 테스트 가능합니다. 테스트 방식은 크게 두 가지로 나뉩니다.

 

방식	스킴	용도	위치
로컬 개발 서버 연결	intoss://{appName}	개발 중에 실시간 테스트	샌드박스 내에서 테스트
배포 버전 테스트	intoss-private://{appName}?_deploymentId=...	빌드 후 배포본 테스트	실제 toss 앱에서 테스트

 

2-1. 로컬 개발 테스트

1) Android 

: 기기를 USB로 연결한 후, 다음의 명령어로 포트를 설정합니다.

# 포트 포워딩 설정
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173

# 연결 확인
adb reverse --list

 

샌드박스 내에서 다음과 같이 스팀에 intoss://{appName} 을 입력하면 테스트가 가능하다.

 

 

2) iOS 테스트 

: 기기연결 없이 mac과 같은 WiFi에 접속되어있으면 무선으로 테스트가 가능합니다.

granite.config.ts에서 host를 IP 주소로 변경

web: {
  host: '190.100.20.100',  // 실기기에서 접근 가능한 IP
  port: 5173,
  commands: {
    dev: 'vite --host',   // --host 옵션 필수
    build: 'vite build',
  },
},

granite 에서 설정한 IP 주소를 Metro 서버에 설정.

 

3. 배포 후 테스트

: 샌드박스에서 기기별로 테스트를 끝내고, 빌드 번들 파일을 만들어 실제 환경에서 테스트를 해봅니다.

npm run build

 

다음의 배포 파일이 생성됨

토스 사이트에서 다음과 같이 등록하면, 테스트를 할 수 있는 QR 코드를 줍니다.

그걸 실제 TOSS 앱에서 열어보면 실서버에서 테스트 할 수 있습니다.

 

 

 

마지막은 나의 앱이 통과되길 바라는 것 ㅋ

두구두구두구...

 

자주 발생하는 문제

Android adb 연결이 안 될 때

USB 디버깅이 활성화되어 있는지 확인하세요. 설정 → 개발자 옵션 → USB 디버깅 ON

 

iOS에서 앱이 안 열릴 때

granite.config.ts의 host IP가 실제 Mac의 IP와 일치하는지 확인하세요.
같은 WiFi 네트워크인지도 반드시 확인이 필요해요.

 

배포 후 QR 코드로 열었는데 빈 화면

빌드 결과물 경로 설정이 잘못된 경우가 많아요.
npm run build 후 생성된 파일 경로와 콘솔 등록 경로가 일치하는지 확인하세요.

 

 

마무리

로컬 테스트 → 샌드박스 → 배포 후 실기기 테스트 순서로 진행하면 앱인토스 WebView 미니앱 개발 사이클을 안정적으로 돌릴 수 있어요. iOS 무선 테스트가 처음엔 낯설지만 한 번 세팅해두면 훨씬 편해집니다.