> 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/ai-vibe-coding/zh/tutorials/webview.md).

# 在现有 Web 项目中集成 SDK

可以直接在已在运营的 Web 项目中安装 SDK，将其转换为迷你应用。

***

### 1. 安装并初始化 SDK

安装 SDK 后，请初始化环境。

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

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

{% endtab %}

{% tab title="pnpm" %}

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}
{% endtabs %}

***

### 2. 修改配置文件

创建项目后 `granite.config.ts` 文件会自动生成。 `appName`, `displayName`, `icon`请将其修改为与在 앱인토스 控制台中注册的应用信息一致。

```ts
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'my-mini-app', // 请填写在控制台中输入的 appName。
  brand: {
    displayName: '앱 이름', // 请填写在控制台中输入的应用名称。
    primaryColor: '#FF91D5', // 请改为将在界面上显示的应用主色。
    icon: '', // 请填写在控制台中上传的图片 URL。（请在控制台的应用信息中，右键点击上传的图片并复制链接后填入）
  },
  web: {
    host: 'localhost',
    port: 5173,
    commands: {
      dev: 'vite dev',
      build: 'vite build',
    },
  },
  permissions: [],
  outdir: 'dist',
});
```

{% hint style="info" %}
**很重要**

* `appName`是用于识别各个应用的 **唯一键**使用。
* `intoss://{appName}` 也用于 intoss\://{appName} 形式的深度链接路径以及测试·发布时。
* 即使在沙盒应用中测试时也 `intoss://{appName}`通过该地址访问。不过，在使用“发布”菜单的二维码测试时 `intoss-private://{appName}`会使用该地址。
  {% endhint %}

***

### 3. 安装 TDS

**TDS（Toss Design System）WebView** 使用该包可以轻松应用基于 Toss 设计系统的组件。

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

```sh
npm install @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm add @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn add @toss/tds-mobile @toss/tds-mobile-ait @emotion/react@^11 react@^18 react-dom@^18
```

{% endtab %}
{% endtabs %}

TDS 组件的使用方法和指南请 [TDS WebView 文档](https://tossmini-docs.toss.im/tds-mobile/)请查看。

***

### 4. 运行项目

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

```sh
npm run dev
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm run dev
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn dev
```

{% endtab %}
{% endtabs %}

***

### 5. 运行迷你应用

开发服务器启动后，可以在沙盒应用中查看迷你应用。关于在本地沙盒应用中测试的详细方法，请 [沙盒应用](https://appsintoss.gitbook.io/appsintoss-docs/landing-page/development/test/sandbox) 请查看文档。

#### 在真机上访问开发服务器

要在真机上测试，在启动打包器时 `--host` 选项，并 `web.host`将其设置为真机可访问的网络地址。

```ts
import { defineConfig } from '@apps-in-toss/web-framework/config';

export default defineConfig({
  appName: 'ping-pong',
  web: {
    host: '192.168.0.100', // 更改为真机可访问的 IP 地址
    port: 5173,
    commands: {
      dev: 'vite --host', // 启用 --host 选项
      build: 'vite build',
    },
  },
  permissions: [],
});
```

设置完成后，请在真机上按以下顺序进行。

1. 参考“安装沙盒应用”，安装适合设备的沙盒应用。
2. 在沙盒应用中将 Metro 服务器地址 `web.host`改为在 web.host 中设置的 IP 地址。
3. `intoss://{appName}` 通过深度链接访问迷你应用。

***

### 6. 调试

#### Android — Chrome DevTools

{% hint style="info" %}
**需要准备**

要在设备上调试，需先启用 USB 调试。 `设置 → 系统 → 手机信息 → 开发者选项 → 启用 USB 调试`
{% endhint %}

1. 在 Android 模拟器或真机上运行迷你应用。
2. 在 Chrome 浏览器中 `chrome://inspect/#devices` 打开页面。
3. 在 Remote Target 中，位于要调试的 WebView 内容下方 **inspect** 按钮。
4. 可以像调试普通网页一样调试 WebView 内容。

#### iOS — Safari 开发者工具

{% hint style="info" %}
**需要准备**

* 需要启用 Safari 开发者菜单。 `Safari 偏好设置 → 高级标签页 → 勾选“显示网页开发者功能”`
* 要在设备上调试，需要启用 Web Inspector（网页检查器）。 `设置 → Safari → 高级 → 启用 Web Inspector`
* 如果开发者菜单中未显示设备，请尝试重启 Safari。
  {% endhint %}

1. 在 iOS 模拟器或真机上运行迷你应用。
2. Safari 顶部菜单 `开发者用 → [设备名称] → [应用名称] → [URL - 标题]`进行选择。
3. 可以像在网页上调试一样调试 WebView 内容。

***

### 7. 构建并在 Toss App 中进行最终测试

在沙盒应用中完成开发和基础验证后 `npm run build`生成应用 bundle 后，请上传到控制台进行最终测试。完成 Toss App 测试后才能发送发布请求。详细方法请 [Toss App 测试](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/toss) 请参考文档。

***

### 8. 发布

发布方法请参考 [迷你应用发布](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/deploy) 请参考文档。


---

# 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/ai-vibe-coding/zh/tutorials/webview.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.