v3

@apps-in-toss/web-framework 3.0.0 to latesthas been deployed. Now npm install @apps-in-toss/web-frameworkwhen you run it, 3.0.0 will be installed.

3.0.0 is a major update that has reorganized the SDK structure for web mini app development. In this document, you can see the differences between 2.x and 3.0.0.

At a glance

• We reorganized the public API around domain objects. Existing functions grouped by domain remain deprecated and continue to work without code changes.
• The package is lighter. The installation size has been reduced from about 27MB to about 660KB.
• The config file granite.config.tsin apps-in-toss.config.tshas changed to npx ait migrate v3 You can convert it automatically with a command.
• The sandbox app does not support 3.0. We plan to support devtools that mock APIs. Until then, please test in the Toss app with the QR code issued from the console.

Domain object API

The public APIs in 3.0.0 are grouped into feature-based domain objects. Existing individual functions grouped by domain have been deprecated, so please use the domain members for the same functionality.

// 2.x style — it works, but a deprecated warning is shown.
import { openCamera } from "@apps-in-toss/web-framework";
const image = await openCamera();

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

Existing functions work exactly the same as in 2.x, from the function name to the inputs and outputs. So 2.x code compiles and works in 3.0 without changes. However, deprecated labels appear in the editor, and new code is recommended to be written using domain members.

Mapping between existing APIs and domain members

Domain	Existing API (deprecated)	New 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
Share	getTossShareLink	Share.createLink
Share	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

SafeAreaInsetsis SafeAreais an object like this. You can continue using the existing names as they are.

APIs that remain unchanged

The following APIs are not grouped into domains and are provided in their existing form. You can keep using them without deprecation.

• Object-style APIs: IAP, Storage, TossAds, GoogleAdMob, Analytics, partner
• Ads: loadFullScreenAd, showFullScreenAd
• Permissions: getPermission, requestPermission, openPermissionDialogand permission error classes
• Events: appsInTossEvent, graniteEvent, tdsEvent
• Environment: isMinVersionSupported, getAppsInTossGlobals

Newly added APIs

• PermissionError: the common parent class for permission errors has been exposed. error instanceof PermissionErrorso you can handle all permission errors at once.
• TossPay Domain objects: In 2.x, checkoutPayment there were only individual functions like these, but in 3.0 TossPay.authorize, TossPay.authorizeSubscriptionthey are grouped into

Differences in behavior between existing functions and domain members

We didn't just change the names; we also improved some behavioral contracts. Please check the following differences when migrating.

• Constant-style APIs are read as properties, not called as functions. For example getLocale()is Device.localebecomes, getDeviceId()is Environment.deviceIdbecomes.
• Domain members, in Toss app versions that do not support them, UNSUPPORTED_APP_VERSION or UNSUPPORTED_OS_VERSION throw an error with the code. Existing functions, according to the 2.x contract, undefinedor 'ERROR' return the same values. For example getAnonymousKeywhen it fails 'ERROR'returns, but User.getAnonymousKeythrows an error. error.codeyou can branch on it and show guidance like "Please update the Toss app".
• Share.createLinktakes an object argument. getTossShareLink(path, ogImageUrl)is Share.createLink({ path, ogImageUrl })becomes.
• IAP.createOneTimePurchaseOrder The product identifier in the response skuis used. productId The field has been deprecated.

Config file changes

The config file name granite.config.tsin apps-in-toss.config.tshas changed, and some options have changed.

2.x (granite.config.ts)	3.0 (apps-in-toss.config.ts)	Description
web (host, port, commands)	removed	The development server and build execution have been moved from the SDK package.json to scripts.
brand.displayName, brand.icon	removed	brandcontains primaryColorare all that remain.
webViewProps	webView	The name has changed. The sub-options are the same, and typeonly that was removed.
webViewProps.type	removed	The WebView frame type option has been removed.
outdir	webBundleDir	Only the name has changed. The default value is distthe same as

The config type name also AppsInTossWebConfigin AppsInTossConfighas changed to

The web development server and build now package.json run directly from scripts.

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

Package structure changes

Item	2.x	3.0
Installation size	about 27MB	about 660KB
Module format	ESM only	ESM + CJS dual
dependencies	13	4 (@apps-in-toss/cli, @webview-bridge/web, semver, valibot)
License	only the LICENSE file	Apache-2.0 specified

CJS environments (requireand older bundlers) can now use it too, and with fewer dependencies, installation is faster and there is less worry about version conflicts with other packages.

Sandbox and development environment mocking

The sandbox app does not support 3.0. Instead, we are preparing to provide devtools soon so you can mock APIs in a local development environment without the sandbox app.

Until then, please test mini apps built with 3.0 in the Toss app using the QR code issued from the Apps in Toss console.

Migrating to 3.0.0

We provide an automatic migration command. The config file conversion and package.json script restructuring are handled automatically.

npx ait migrate v3

This command performs the following tasks.

• granite.config.tsthe apps-in-toss.config.tsconverts to (brandis primaryColorkeeps only, webViewPropsis webViewchanges to, outdiris webBundleDirchanges to, web deletes the block).
• package.jsonof dev, build Reconstructs the scripts.
• If validation before conversion fails, it does not change the file and tells you the cause and how to fix it.

After migration, upload the bundle to the console and test it in the Toss app using the QR code.

Please be sure to check

• If you release a bundle built with SDK 3.x, you cannot roll back to 2.x. Please test thoroughly with the QR code before releasing.
• From 3.0, mini apps run in https://<appName>.web.tossmini.com(live) and https://<appName>.private-web.tossmini.com(QR test) Origins. Please register both domains in the API server's CORS allowlist.
• If you use TDS, @toss/tds-mobileand @toss/tds-mobile-aitplease update it to 2.4.1 or later as well.
• 3.0.0-rc.1 and rc.2 cannot be installed due to dependency issues. Be sure to use the official 3.0.0 version.