> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/v3.md).

# v3

`@apps-in-toss/web-framework` 3.0.0 `latest`has been deployed. Now `npm install @apps-in-toss/web-framework`If 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 check the differences between 2.x and 3.0.0.

### At a glance

* The public API has been reorganized around domain objects. Existing functions grouped by domain are kept deprecated and continue to work without code changes.
* The package is now lighter. The install size has been reduced from about 27MB to about 660KB.
* The configuration file `granite.config.ts`from `apps-in-toss.config.ts`has been changed to. `npx ait migrate v3` can be automatically converted with the command.
* The sandbox app does not support 3.0. We plan to support devtools for mocking APIs. Until then, please test in the Toss app using the QR code issued from the console.

### Domain object API

The public API in 3.0.0 is grouped into feature-based domain objects. Existing individual functions grouped by domain are deprecated, so please use the domain member for the same feature.

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

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

Existing functions behave exactly the same as 2.x, from the function name to the values they take and return. So 2.x code compiles and works in 3.0 without modifications. However, a deprecated marker appears in the editor, and new code is recommended to be written with domain members.

#### Existing API and domain member mapping

| 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`         |
| 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`      |

`SafeAreaInsets`is `SafeArea`an object like this. You can keep using the existing name as is.

#### APIs that remain unchanged

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

* Object-style APIs: `IAP`, `Storage`, `TossAds`, `GoogleAdMob`, `Analytics`, `partner`
* Ads: `loadFullScreenAd`, `showFullScreenAd`
* Permissions: `getPermission`, `requestPermission`, `openPermissionDialog`and permission error class
* Events: `appsInTossEvent`, `graniteEvent`, `tdsEvent`
* Environment: `isMinVersionSupported`, `getAppsInTossGlobals`

#### Newly added API

* `PermissionError`: The common parent class for permission errors has been exposed. `error instanceof PermissionError`can be used to handle all permission errors at once.
* `TossPay` Domain objects: In 2.x, `checkoutPayment` there were only individual functions, but in 3.0, `TossPay.authorize`, `TossPay.authorizeSubscription`they are grouped into.

#### Behavior differences between existing functions and domain members

It wasn't just the names that changed; some behavioral contracts were also improved. When migrating, please check the following differences.

* Constant-style APIs are read as properties, not called as functions. For example, `getLocale()`becomes `Device.locale`to, `getDeviceId()`is `Environment.deviceId`changes to.
* On Toss app versions that do not support domain members, `UNSUPPORTED_APP_VERSION` or `UNSUPPORTED_OS_VERSION` throws an error with the code. Existing functions, according to the 2.x contract, `undefined`or `'ERROR'` return values like these. For example, `getAnonymousKey`fails and `'ERROR'`returns, but `User.getAnonymousKey`throws an error. `error.code`You can branch on it and show guidance such as "Please update the Toss app".
* `Share.createLink`takes an object argument. `getTossShareLink(path, ogImageUrl)`becomes `Share.createLink({ path, ogImageUrl })`changes to.
* `IAP.createOneTimePurchaseOrder` The product identifier in the response is `sku`use. `productId` field is deprecated.

### Configuration file changes

The configuration file name `granite.config.ts`from `apps-in-toss.config.ts`has 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 moved from the SDK to `package.json` scripts. |
| `brand.displayName`, `brand.icon` | Removed                        | `brand`only `primaryColor`remains.                                                            |
| `webViewProps`                    | `webView`                      | The name has changed. The sub-options are the same, and `type`only type was removed.          |
| `webViewProps.type`               | Removed                        | The WebView frame type option has been removed.                                               |
| `outdir`                          | `webBundleDir`                 | Only the name has changed. The default value is `dist`is the same as.                         |

The configuration type name also `AppsInTossWebConfig`from `AppsInTossConfig`has been changed to.

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

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

### Package structure changes

| Item          | 2.x               | 3.0                                                                 |
| ------------- | ----------------- | ------------------------------------------------------------------- |
| Install 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       | LICENSE file only | `Apache-2.0` specified                                              |

CJS environments (`require`, and even in older bundlers) it can be used. With fewer dependencies, installation is faster and worries about version conflicts with other packages are reduced.

### Sandbox and development environment mocking

The sandbox app does not support 3.0. Instead, we're preparing to provide devtools soon so that APIs can be mocked in the local development environment even 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. Conversion of the configuration file and `package.json` script reorganization are handled automatically.

```bash
npx ait migrate v3
```

This command performs the following tasks.

* `granite.config.ts`to `apps-in-toss.config.ts`convert to (`brand`is `primaryColor`only keep, `webViewProps`is `webView`change to, `outdir`becomes `webBundleDir`change to, `web` delete the block).
* `package.json`'s `dev`, `build` restructure the scripts.
* If pre-conversion validation fails, it leaves the file unchanged 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 with the QR code.

#### Please make sure to check

* If you release a bundle built with SDK 3.x, you cannot roll back to 2.x. Please release only after thoroughly testing with the QR code.
* Starting with 3.0, mini-apps `https://<appName>.web.tossmini.com`(live) and `https://<appName>.private-web.tossmini.com`(QR test) run on the Origin. Please add both domains to the API server's CORS allowlist.
* If you use TDS, `@toss/tds-mobile`and `@toss/tds-mobile-ait`update both to 2.4.1 or later.
* 3.0.0-rc.1 and rc.2 cannot be installed due to dependency issues. Please be sure to use the official 3.0.0 release.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/v3.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.