> 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-zh/integration/sdk-3.x.md).

# SDK 3.x 迁移

{% hint style="info" %}
 **`localStorage` 使用时请暂时暂停迁移。**

在 SDK 2.x 中的浏览器 `localStorage`如果直接使用，迁移到 SDK 3.x 后将无法访问现有 `localStorage` 数据。

如果需要保留现有数据，请在另行通知前暂停 SDK 3.x 迁移。

`@apps-in-toss/web-framework`由其提供的 `存储` API，或者如果正在使用现有 `localStorage` 数据且不需要保留，可以正常迁移。
{% endhint %}

SDK 3.x 是对 WebView 项目结构进行改进的更新。\
配置文件名称和部分属性发生了变化，客户端 SDK 也得到了升级。\
参数和返回值与 SDK 2.x 保持一致，并将 SDK 内部处理逻辑从客户端改为在服务器端处理。

即使发生 SDK 问题，也无需合作伙伴重新发布，只需在 Apps in Toss 服务器上修改并应用即可。\
SDK 3.x 是为了提升 mini app 生态的稳定性，并将 SDK 保持为稳定版本。

***

### 变更概要

| 项目             | 变更前                                      | 变更后                        |
| -------------- | ---------------------------------------- | -------------------------- |
| 配置文件名称         | `granite.config.ts`                      | `apps-in-toss.config.ts`   |
| `brand` 设置     | `displayName`, `primaryColor`, `icon` 包含 | `primaryColor`仅保留          |
| `webViewProps` | `类型` 包含属性                                | `webView`重命名为， `类型` 删除     |
| `outdir`       | `outdir`                                 | `webBundleDir`             |
| `web` 设置       | 在配置文件中 `web.commands` 包含                 | 删除后 `package.json`迁移到      |
| 测试环境           | 需要安装并登录沙盒应用                              | 可直接通过本地浏览器（AIT Devtools）测试 |

***

### 更新包

先 `@apps-in-toss/web-framework`升级到 3.x 版本。

{% tabs %}
{% tab title="npm" %}

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}
{% endtabs %}

如果使用 TDS(Toss Design System)，请将以下两个包更新到 2.4.1 版本。

* `@toss/tds-mobile`
* `@toss/tds-mobile-ait`

{% tabs %}
{% tab title="npm" %}

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}
{% endtabs %}

***

### 自动迁移

执行以下命令后，配置文件转换和 `package.json` 脚本更新会自动处理。

{% tabs %}
{% tab title="npx" %}

```sh
npx ait migrate v3
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn ait migrate v3
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm ait migrate v3
```

{% endtab %}
{% endtabs %}

执行后 `apps-in-toss.config.ts` 会生成文件， `package.json`中 `dev`, `build` 脚本会更新。\
迁移完成后，请确认 mini app 在本地浏览器中是否正常运行。

***

### 手动迁移

`apps-in-toss.config.ts`如果未生成或值不正确，请查看手动迁移指南。

#### 1. 更改配置文件名称

`granite.config.ts` 将文件名 `apps-in-toss.config.ts`更改为。

#### 2. `brand` 整理配置

`brand` 在配置中 `primaryColor`删除除其以外的其余属性。

```ts
// 变更前
brand: {
  displayName: '应用名称',
  primaryColor: '#3182F6',
  icon: 'https://...',
},

// 变更后
brand: {
  primaryColor: '#3182F6',
},
```

#### 3. `webViewProps` → `webView`更改为

`webViewProps`的名称 `webView`改为， `类型` 删除该属性。

```ts
// 变更前
webViewProps: {
  type: 'partner',
},

// 变更后
webView: {},
```

#### 4. `outdir` → `webBundleDir`更改为

```ts
// 变更前
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`并一并执行。

```json
// package.json 更改示例
{
  "scripts": {
    "dev": "vite --port 3000",
    "build": "vite build && ait build"
  }
}
```

***

### 变更前后示例

#### 变更前(granite.config.ts)

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

```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 版本。\
请充分通过二维码测试后再发布。

#### 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 链接，确认 mini app 是否正常运行。

{% tabs %}
{% tab title="npm" %}

```shellscript
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```shellscript
pnpm run dev
```

{% endtab %}

{% tab title="yarn" %}

```shellscript
yarn dev
```

{% endtab %}
{% endtabs %}

***

### 测试环境手动设置

如果是从 SDK 3.0.1 版本迁移，则需要手动配置 AIT Devtools。\
请按照以下步骤进行设置。

#### 1. 安装包

{% tabs %}
{% tab title="npm" %}

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}
{% endtabs %}

#### 2. 打包器设置

如果使用 Vite `vite.config.ts`请在其中添加 Devtools 插件。

如果使用其他打包器， `@apps-in-toss/devtools/unplugin`提供的对应打包器适配器添加到配置文件中。例如 `aitDevtools.vite()`, `aitDevtools.webpack()`可以这样使用。

下面的代码是使用 Vite 打包器时的配置示例。

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

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

#### 3. 测试

启动服务后，通过本地浏览器访问。如果右下角能看到 AIT Devtools，说明已正常配置，可以直接在此界面测试 mini app 的运行。

{% tabs %}
{% tab title="npm" %}

```shellscript
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```shellscript
pnpm run dev
```

{% endtab %}

{% tab title="yarn" %}

```shellscript
yarn dev
```

{% endtab %}
{% endtabs %}

***

### 迁移检查清单

* [ ] `granite.config.ts`将 `apps-in-toss.config.ts`重命名为
* [ ] `brand`中 `primaryColor`只保留，其他已删除
* [ ] `webViewProps`将 `webView`更改为 `类型`已删除
* [ ] `outdir`将 `webBundleDir`更改为
* [ ] `web` 删除设置并将命令 `package.json`迁移到
* [ ] `build` 脚本中 `ait build`已包含
* [ ] 构建正常运行
* [ ] 已在测试环境(AIT Devtools)中确认正常运行
* [ ] 已将 bundle 上传到 Apps in Toss 控制台
* [ ] 已在 Toss App 中完成测试

***

### 咨询

有关迁移的问题，请通过 Channel Talk 或社区咨询。


---

# 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-zh/integration/sdk-3.x.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.