SDK 3.x 마이그레이션

localStorage 사용 시 마이그레이션을 잠시 보류해 주세요.

SDK 2.x에서 브라우저 localStorage를 직접 사용하고 있는 경우, SDK 3.x로 마이그레이션하면 기존 localStorage 데이터에 접근할 수 없습니다.

기존 데이터 유지가 필요한 경우에는 별도 안내 전까지 SDK 3.x 마이그레이션을 보류해 주세요.

@apps-in-toss/web-framework에서 제공하는 Storage API를 사용하고 있거나 기존 localStorage 데이터 유지가 필요하지 않은 경우에는 정상적으로 마이그레이션할 수 있습니다.

SDK 3.x는 WebView 프로젝트의 구조를 개선한 업데이트예요. 설정 파일 이름과 일부 프로퍼티가 변경되며, 클라이언트 SDK가 고도화됐어요. 파라미터와 반환값은 SDK 2.x와 동일하고, SDK 내부 처리 로직을 클라이언트가 아닌 서버에서 처리하도록 변경했어요.

SDK 이슈가 발생해도 파트너사의 재배포 없이 앱인토스 서버에서만 수정하고 반영할 수 있어요. SDK 3.x는 미니앱 생태계의 안정성을 높이고, SDK를 안정적인 버전으로 유지하기 위해서예요.

---

변경 사항 요약

항목	변경 전	변경 후
설정 파일 이름	granite.config.ts	apps-in-toss.config.ts
brand 설정	displayName, primaryColor, icon 포함	primaryColor만 유지
webViewProps	type 프로퍼티 포함	webView로 이름 변경, type 삭제
outdir	outdir	webBundleDir
web 설정	설정 파일 내 web.commands 포함	삭제 후 package.json으로 이동
테스트 환경	샌드박스 앱 설치·로그인 필요	로컬 브라우저(AIT Devtools)로 바로 테스트

---

패키지 업데이트

먼저 @apps-in-toss/web-framework를 3.x 버전으로 업데이트해요.

npm

npm install @apps-in-toss/web-framework

yarn

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

pnpm

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

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

• @toss/tds-mobile
• @toss/tds-mobile-ait

npm

npm install @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

yarn

yarn add @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

pnpm

pnpm add @toss/tds-mobile@2.4.1 @toss/tds-mobile-ait@2.4.1

---

자동 마이그레이션

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

npx

npx ait migrate v3

yarn

yarn ait migrate v3

pnpm

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를 제외한 나머지 프로퍼티를 삭제하세요.

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

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

3. webViewProps → webView로 변경

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

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

// 변경 후
webView: {},

4. outdir → webBundleDir로 변경

// 변경 전
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를 함께 실행하도록 추가해요.

// package.json 변경 예시
{
  "scripts": {
    "dev": "vite --port 3000",
    "build": "vite build && ait build"
  }
}

---

변경 전후 예시

변경 전(granite.config.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)

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 테스트 환경

3. 새로운 테스트 환경이 제공돼요

기존에는 샌드박스 앱을 설치하고 로그인해야 했고, 샌드박스 앱이 수시로 업데이트될 때마다 다시 업데이트해야 하는 번거로움이 있었어요. SDK 3.x부터는 이 과정 없이 로컬 브라우저만 띄우면 바로 테스트할 수 있어요. 설정 방법은 아래 테스트 환경을 참고하세요.

---

테스트 환경

새로운 프로젝트를 스캐폴딩했거나, 2.x 버전에서 3.x로 마이그레이션한 경우에는 AIT Devtools가 자동으로 설정돼요.

아래 명령어를 통해 로컬 브라우저로 바로 확인할 수 있어요. localhost 링크를 로컬 브라우저로 열어서 미니앱 동작 여부를 확인해 주세요.

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn dev

---

테스트 환경 수동 세팅

SDK 3.0.1 버전에서 마이그레이션했다면 AIT Devtools를 수동으로 설정해야 해요. 아래 단계를 따라 설정해 주세요.

1. 패키지 설치

npm

npm install -D @apps-in-toss/devtools

pnpm

pnpm add -D @apps-in-toss/devtools

yarn

yarn add -D @apps-in-toss/devtools

2. 번들러 설정

Vite를 사용하는 경우 vite.config.ts에 Devtools 플러그인을 추가해요.

다른 번들러를 사용하는 경우에는 @apps-in-toss/devtools/unplugin에서 제공하는 해당 번들러용 어댑터를 사용해 설정 파일에 추가해야 해요. 예를 들어 aitDevtools.vite(), aitDevtools.webpack()처럼 사용할 수 있어요.

아래 코드는 Vite 번들러를 사용할 때의 설정 예시예요.

import aitDevtools from "@apps-in-toss/devtools/unplugin";

export default defineConfig({
  plugins: [
    aitDevtools.vite(),
    react(),
    babel({ presets: [reactCompilerPreset()] }),
  ],
});

3. 테스트하기

서비스를 실행한 뒤 로컬 브라우저로 접근해요. 우측 하단에 AIT Devtools가 보이면 정상적으로 설정된 상태이며, 이 화면에서 바로 미니앱 동작을 테스트할 수 있어요.

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn dev

---

마이그레이션 체크리스트

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

---

문의

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