v3

@apps-in-toss/web-framework 3.0.0 最新已发布为。现在 npm install @apps-in-toss/web-framework运行后会安装 3.0.0。

3.0.0 是为 Web 迷你应用开发重新整理了 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。在此之前，请用控制台发放的二维码在 Toss App 中测试。

领域对象 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
剪贴板	getClipboardText	Clipboard.getText
剪贴板	setClipboardText	Clipboard.setText
设备	fetchAlbumItems	Device.getAlbumItems
设备	fetchAlbumPhotos	Device.getPhotos
设备	fetchContacts	Device.getContacts
设备	getCurrentLocation	Device.getLocation
设备	getLocale	Device.locale
设备	getPlatformOS	Device.os
设备	generateHapticFeedback	Device.triggerHaptic
设备	openCamera	Device.openCamera
设备	openURL	Device.openURL
设备	startUpdateLocation	Device.subscribeLocation
环境	getDeviceId	Environment.deviceId
环境	getGroupId	Environment.groupId
环境	getOperationalEnvironment	Environment.environment
环境	getTossAppVersion	Environment.tossAppVersion
环境	env.getDeploymentId	Environment.deploymentId
环境	getSchemeUri	Environment.initialURL
环境	getNetworkStatus	Environment.getNetworkStatus
环境	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
通知	requestNotificationAgreement	Notification.requestAgreement
推广	grantPromotionReward	Promotion.grantReward
推广	contactsViral	Promotion.openContactsInvite
评价	requestReview	Review.request
安全区域	getSafeAreaInsets	SafeArea.get
安全区域	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.sendMessage
TossAuth	appLogin	TossAuth.login
TossAuth	getIsTossLoginIntegratedService	TossAuth.isIntegrated
TossAuth	appsInTossSignTossCert	TossAuth.sign
TossPay	checkoutPayment	TossPay.authorize
TossPay	requestTossPayPaysBilling	TossPay.authorizeSubscription
用户	getAnonymousKey	User.getAnonymousKey
用户	getConsentedUserData	User.getConsentedData
用户	getDeclaredAgeRange	User.getDeclaredAgeRange

SafeAreaInsets是 安全区域等对象。可以继续使用原来的名称。

保持不变的 API

以下 API 不按领域分组，而是保持原有形式提供。可以继续使用，无需担心 deprecated。

• 对象型 API： IAP, 存储, 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变为。
• 在不支持的 Toss App 版本中，领域成员会 UNSUPPORTED_APP_VERSION 或 UNSUPPORTED_OS_VERSION 代码的错误。旧函数按 2.x 合约会返回 undefined或 'ERROR' 等值。例如 getAnonymousKey失败时会 'ERROR'返回，但 User.getAnonymousKey会抛出错误。 error.code可以按此分支显示“请更新 Toss App”等提示。
• 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	名称已更改。子选项保持不变， 类型仅被移除。
webViewProps.type	删除	WebView frame type 选项已消失。
outdir	webBundleDir	只是名称变了。默认值为 dist保持不变。

配置类型名称也从 AppsInTossWebConfig中 AppsInTossConfig改为。

Web 开发服务器和构建现在直接在 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。相反，我们正准备尽快提供 devtools，以便即使没有沙盒应用，也能在本地开发环境中模拟 API。

在此之前，请用 Apps in Toss 控制台发放的二维码在 Toss App 中测试用 3.0 制作的迷你应用。

迁移到 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 重构脚本。
• 如果转换前验证失败，不会修改文件，并会告知原因和解决方法。

迁移后请将 bundle 上传到控制台，并通过二维码在 Toss App 中测试。

请务必确认

• 使用 SDK 3.x 构建的 bundle 发布后，无法回滚到 2.x。请在通过二维码充分测试后再发布。
• 从 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 正式版。