v3

@apps-in-toss/web-framework 3.0.0을 latest로 배포했어요. 이제 npm install @apps-in-toss/web-framework를 실행하면 3.0.0이 설치돼요.

3.0.0은 웹 미니앱 개발에 맞게 SDK 구조를 새로 정비한 메이저 업데이트예요. 이 문서에서 2.x와 3.0.0의 차이를 확인할 수 있어요.

한눈에 보기

공개 API를 도메인 객체 중심으로 재편했어요. 도메인으로 묶인 기존 함수는 deprecated로 유지되어 코드 수정 없이 그대로 동작해요.
패키지가 가벼워졌어요. 설치 크기가 약 27MB에서 약 660KB로 줄었어요.
설정 파일이 granite.config.ts에서 apps-in-toss.config.ts로 바뀌었어요. npx ait migrate v3 명령으로 자동 변환할 수 있어요.
샌드박스 앱은 3.0을 지원하지 않아요. API를 모킹하는 devtools를 지원할 예정이에요. 그 전까지는 콘솔에서 발급한 QR코드로 토스 앱에서 테스트해 주세요.

도메인 객체 API

3.0.0의 공개 API는 기능 단위 도메인 객체로 묶여요. 도메인으로 묶인 기존 개별 함수는 deprecated 되었으니, 같은 기능의 도메인 멤버를 사용해 주세요.

// 2.x 방식 — 동작하지만 deprecated 경고가 표시돼요.
import { openCamera } from "@apps-in-toss/web-framework";
const image = await openCamera();

// 3.0 방식
import { Device } from "@apps-in-toss/web-framework";
const image = await Device.openCamera();

기존 함수는 함수 이름부터 받는 값, 돌려주는 값까지 2.x와 똑같이 동작해요. 그래서 2.x 코드는 수정 없이 3.0에서 컴파일되고 동작해요. 다만 에디터에서 deprecated 표시가 나타나고, 새 코드는 도메인 멤버로 작성하는 것을 권장해요.

기존 API와 도메인 멤버 대응표

도메인

기존 API (deprecated)

새 API

Clipboard

getClipboardText

Clipboard.getText

Clipboard

setClipboardText

Clipboard.setText

Device

fetchAlbumItems

Device.getAlbumItems

Device

fetchAlbumPhotos

Device.getPhotos

Device

fetchContacts

Device.getContacts

Device

getCurrentLocation

Device.getLocation

Device

getLocale

Device.locale

Device

getPlatformOS

Device.os

Device

generateHapticFeedback

Device.triggerHaptic

Device

openCamera

Device.openCamera

Device

openURL

Device.openURL

Device

startUpdateLocation

Device.subscribeLocation

Environment

getDeviceId

Environment.deviceId

Environment

getGroupId

Environment.groupId

Environment

getOperationalEnvironment

Environment.environment

Environment

getTossAppVersion

Environment.tossAppVersion

Environment

env.getDeploymentId

Environment.deploymentId

Environment

getSchemeUri

Environment.initialURL

Environment

getNetworkStatus

Environment.getNetworkStatus

Environment

getServerTime

Environment.getServerTime

File

saveBase64Data

File.saveBase64

File

openPDFViewer

File.openPDFViewer

Game

openGameCenterLeaderboard

Game.openLeaderboard

Game

submitGameCenterLeaderBoardScore

Game.setLeaderboardScore

Game

getGameCenterGameProfile

Game.getUserProfile

Game

getUserKeyForGame

User.getAnonymousKey

Game

grantPromotionRewardForGame

Promotion.grantReward

Notification

requestNotificationAgreement

Notification.requestAgreement

Promotion

grantPromotionReward

Promotion.grantReward

Promotion

contactsViral

Promotion.openContactsInvite

Review

requestReview

Review.request

SafeArea

getSafeAreaInsets

SafeArea.get

SafeArea

SafeAreaInsets.subscribe

SafeArea.subscribe

Screen

closeView

Screen.close

Screen

setScreenAwakeMode

Screen.setAwakeMode

Screen

setSecureScreen

Screen.setSecure

Screen

setIosSwipeGestureEnabled

Screen.setIosSwipeBack

Screen

setDeviceOrientation

Screen.setOrientation

getTossShareLink

Share.createLink

share

Share.sendMessage

TossAuth

appLogin

TossAuth.login

TossAuth

getIsTossLoginIntegratedService

TossAuth.isIntegrated

TossAuth

appsInTossSignTossCert

TossAuth.sign

TossPay

checkoutPayment

TossPay.authorize

TossPay

requestTossPayPaysBilling

TossPay.authorizeSubscription

User

getAnonymousKey

User.getAnonymousKey

User

getConsentedUserData

User.getConsentedData

User

getDeclaredAgeRange

User.getDeclaredAgeRange

SafeAreaInsets는 SafeArea와 같은 객체예요. 기존 이름 그대로 계속 쓸 수 있어요.

그대로 유지되는 API

다음 API는 도메인으로 묶이지 않고 기존 형태 그대로 제공돼요. deprecated 없이 계속 사용하면 돼요.

객체형 API: IAP, Storage, TossAds, GoogleAdMob, Analytics, partner
광고: loadFullScreenAd, showFullScreenAd
권한: getPermission, requestPermission, openPermissionDialog와 권한 에러 클래스
이벤트: appsInTossEvent, graniteEvent, tdsEvent
환경: isMinVersionSupported, getAppsInTossGlobals

새로 생긴 API

PermissionError: 권한 에러의 공통 부모 클래스가 공개됐어요. error instanceof PermissionError로 모든 권한 에러를 한 번에 처리할 수 있어요.
TossPay 도메인 객체: 2.x에서는 checkoutPayment 같은 개별 함수만 있었지만, 3.0에서는 TossPay.authorize, TossPay.authorizeSubscription으로 묶였어요.

기존 함수와 도메인 멤버의 동작 차이

이름만 바뀐 것이 아니라 일부 동작 계약도 개선했어요. 마이그레이션할 때 다음 차이를 확인해 주세요.

상수형 API는 함수 호출이 아니라 속성으로 읽어요. 예를 들어 getLocale()은 Device.locale로, getDeviceId()는 Environment.deviceId로 바뀌어요.
도메인 멤버는 지원하지 않는 토스 앱 버전에서 UNSUPPORTED_APP_VERSION 또는 UNSUPPORTED_OS_VERSION 코드를 가진 에러를 던져요. 기존 함수는 2.x 계약대로 undefined나 'ERROR' 같은 값을 반환해요. 예를 들어 getAnonymousKey는 실패하면 'ERROR'를 반환하지만, User.getAnonymousKey는 에러를 던져요. error.code로 분기해서 "토스 앱을 업데이트해 주세요" 같은 안내를 보여줄 수 있어요.
Share.createLink는 객체 인자를 받아요. getTossShareLink(path, ogImageUrl)은 Share.createLink({ path, ogImageUrl })로 바뀌어요.
IAP.createOneTimePurchaseOrder 응답의 상품 식별자는 sku를 사용해요. productId 필드는 deprecated 됐어요.

설정 파일 변경

설정 파일 이름이 granite.config.ts에서 apps-in-toss.config.ts로 바뀌었고, 일부 옵션이 변경됐어요.

2.x (granite.config.ts)

3.0 (apps-in-toss.config.ts)

설명

web (host, port, commands)

제거

개발 서버와 빌드 실행이 SDK에서 package.json 스크립트로 이동했어요.

brand.displayName, brand.icon

제거

brand에는 primaryColor만 남았어요.

webViewProps

webView

이름이 바뀌었어요. 하위 옵션은 동일하고 type만 제거됐어요.

webViewProps.type

제거

WebView frame type 옵션이 사라졌어요.

outdir

webBundleDir

이름만 바뀌었어요. 기본값은 dist로 동일해요.

설정 타입 이름도 AppsInTossWebConfig에서 AppsInTossConfig로 바뀌었어요.

웹 개발 서버와 빌드는 이제 package.json 스크립트에서 직접 실행해요.

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build && ait build",
    "deploy": "ait deploy"
  }
}

패키지 구조 변경

항목

2.x

3.0

설치 크기

약 27MB

약 660KB

모듈 포맷

ESM 전용

ESM + CJS 듀얼

dependencies

13개

4개 (@apps-in-toss/cli, @webview-bridge/web, semver, valibot)

라이선스

LICENSE 파일만

Apache-2.0 명시

CJS 환경(require, 구형 번들러)에서도 사용할 수 있게 됐고, 의존성이 줄어 설치가 빨라지고 다른 패키지와의 버전 충돌 걱정도 줄었어요.

샌드박스와 개발 환경 모킹

샌드박스 앱은 3.0을 지원하지 않아요. 대신 샌드박스 앱 없이도 로컬 개발 환경에서 API를 모킹할 수 있도록 devtools를 곧 제공하려고 준비하고 있어요.

그때까지 3.0으로 만든 미니앱은 앱인토스 콘솔에서 발급한 QR코드로 토스 앱에서 테스트해 주세요.

3.0.0으로 마이그레이션하기

자동 마이그레이션 명령을 제공해요. 설정 파일 변환과 package.json 스크립트 재구성이 자동으로 처리돼요.

npx ait migrate v3

이 명령은 다음 작업을 수행해요.

granite.config.ts를 apps-in-toss.config.ts로 변환해요 (brand는 primaryColor만 유지, webViewProps는 webView로 변경, outdir은 webBundleDir로 변경, web 블록 삭제).
package.json의 dev, build 스크립트를 재구성해요.
변환 전 검증에 실패하면 파일을 변경하지 않고 원인과 해결 방법을 알려줘요.

마이그레이션 후에는 콘솔에 번들을 업로드하고 QR코드로 토스 앱에서 테스트해 주세요.

꼭 확인해 주세요

SDK 3.x로 빌드한 번들을 출시하면 2.x로 롤백할 수 없어요. QR코드로 충분히 테스트한 후 출시해 주세요.
3.0부터 미니앱이 https://<appName>.web.tossmini.com(라이브)과 https://<appName>.private-web.tossmini.com(QR 테스트) Origin에서 실행돼요. API 서버의 CORS 허용 목록에 두 도메인을 등록해 주세요.
TDS를 사용한다면 @toss/tds-mobile과 @toss/tds-mobile-ait을 2.4.1 이상으로 함께 업데이트해 주세요.
3.0.0-rc.1과 rc.2는 의존성 문제로 설치할 수 없어요. 반드시 3.0.0 정식 버전을 사용해 주세요.

이전User.getDeclaredAgeRange

다음Events

도움이 되었나요?