앱인토스 개발자센터

Appearance

콘솔 바로가기

SDK 3.x 마이그레이션 ​

SDK 3.x는 WebView 프로젝트의 구조를 개선한 업데이트예요.
설정 파일 이름과 일부 프로퍼티가 변경되며, 기능 인터페이스는 2.x.x와 100% 동일해요.

변경 사항 요약 ​

항목변경 전변경 후
설정 파일 이름granite.config.tsapps-in-toss.config.ts
brand 설정displayName, primaryColor, icon 포함primaryColor만 유지
webViewPropstype 프로퍼티 포함webView로 이름 변경, type 삭제
outdiroutdirwebBundleDir
web 설정설정 파일 내 web.commands 포함삭제 후 package.json으로 이동

패키지 업데이트 ​

먼저 @apps-in-toss/web-framework를 3.x 버전으로 업데이트해요.
@beta 태그는 현재 3.0을 가리켜요.

sh
npm install @apps-in-toss/web-framework@beta
sh
yarn add @apps-in-toss/web-framework@beta
sh
pnpm add @apps-in-toss/web-framework@beta

TDS(Toss Design System)를 사용하는 경우, 아래 2가지를 2.4.1 버전으로 업데이트해 주세요.

  • @toss/tds-mobile
  • @toss/tds-mobile-ait
sh
npm install @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1
sh
yarn add @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1
sh
pnpm add @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

자동 마이그레이션 ​

아래 명령어를 실행하면 설정 파일 변환과 package.json 스크립트 업데이트가 자동으로 처리돼요.

sh
npx ait migrate v3
sh
yarn ait migrate v3
sh
pnpm ait migrate v3

실행 후 apps-in-toss.config.ts 파일이 생성되고, package.json의 dev, build 스크립트가 업데이트돼요.
마이그레이션이 완료되면 빌드 후 앱인토스 콘솔에 번들을 업로드해서 토스앱에서 테스트해 주세요.

자동 마이그레이션이 실패한 경우

apps-in-toss.config.ts가 생성되지 않거나 값이 올바르지 않으면 아래 수동 마이그레이션을 따르세요.

수동 마이그레이션 ​

1. 설정 파일 이름 변경 ​

granite.config.ts 파일 이름을 apps-in-toss.config.ts로 변경하세요.

2. brand 설정 정리 ​

brand 설정에서 primaryColor를 제외한 나머지 프로퍼티를 삭제하세요.

ts
// 변경 전
brand: {
  displayName: '앱 이름',
  primaryColor: '#3182F6',
  icon: 'https://...',
},

// 변경 후
brand: {
  primaryColor: '#3182F6',
},

3. webViewProps → webView로 변경 ​

webViewProps의 이름을 webView로 바꾸고, type 프로퍼티를 삭제하세요.

ts
// 변경 전
webViewProps: {
  type: 'partner',
},

// 변경 후
webView: {},

4. outdir → webBundleDir로 변경 ​

ts
// 변경 전
outdir: 'dist',

// 변경 후
webBundleDir: 'dist',

5. web 설정 삭제 후 package.json으로 이동 ​

web 설정 블록을 삭제하고, web.commands에 있던 커맨드를 package.json으로 옮기세요.

  • web.commands.dev → package.json의 dev 스크립트에 그대로 옮겨요.
  • web.commands.build → package.json의 build 스크립트에 옮기되, ait build를 함께 실행하도록 추가해요.
json
// package.json 변경 예시
{
  "scripts": {
    "dev": "vite --port 3000",
    "build": "vite build && ait build"
  }
}

변경 전후 예시 ​

변경 전(granite.config.ts) ​

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

export default defineConfig({
  appName: 'my-app',
  brand: {
    displayName: '내 앱',
    primaryColor: '#3182F6',
    icon: 'https://...',
  },
  web: {
    host: 'localhost',
    port: 3000,
    commands: {
      dev: 'vite --port 3000',
      build: 'vite build',
    },
  },
  webViewProps: {
    type: 'partner',
  },
  permissions: [],
  outdir: 'dist',
});

변경 후(apps-in-toss.config.ts) ​

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

export default defineConfig({
  appName: 'my-app',
  brand: {
    primaryColor: '#3182F6',
  },
  webView: {},
  permissions: [],
  webBundleDir: 'dist',
});

유의사항 ​

1. SDK 3.x 출시 후 롤백이 안돼요 ​

SDK 3.x 이상이 적용된 앱 번들을 출시하면 SDK 2.x 버전으로 롤백할 수 없어요.
QR코드로 충분히 테스트한 후 출시해 주세요.

2. CORS가 변경돼요 ​

SDK 3.x 버전부터는 CORS(Cross-Origin Resource Sharing)가 아래와 같이 변경돼요.
Origin 허용 목록에 다음 도메인을 등록하지 않으면 API 요청이 차단될 수 있어요. Origin 허용 목록에 다음 도메인을 등록하세요.

  • https://<appName>.web.tossmini.com : 실제 서비스 환경
  • https://<appName>.private-web.tossmini.com : 콘솔 QR 테스트 환경

마이그레이션 체크리스트 ​

  • granite.config.ts를 apps-in-toss.config.ts로 이름 변경했어요
  • brand에서 primaryColor만 남기고 나머지를 삭제했어요
  • webViewProps를 webView로 변경하고 type을 삭제했어요
  • outdir을 webBundleDir로 변경했어요
  • web 설정을 삭제하고 커맨드를 package.json으로 옮겼어요
  • build 스크립트에 ait build가 포함되어 있어요
  • 빌드가 정상 동작해요
  • 앱인토스 콘솔에 번들을 업로드했어요
  • 토스앱에서 테스트를 완료했어요

문의 ​

마이그레이션 관련 문의는 채널톡 또는 커뮤니티를 통해 문의해 주세요.