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

# 在现有网页项目中集成 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`请修改为与注册到 Apps in Toss 控制台的应用信息相同。

```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}`进行访问。不过，在通过“发布”菜单的 QR 码测试时， `intoss-private://{appName}`会使用。
  {% endhint %}

***

### 3. 安装 TDS

**TDS（Toss Design System）WebView** 包可以轻松应用基于 Toss Design System 的组件。

{% 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 应用中进行最终测试

在沙盒应用中完成开发和基本验证后 `npm run build`生成应用 bundle 后，请上传到控制台进行最终测试。必须完成 Toss 应用测试后才能发送发布申请。详细方法请参考 [测试 Toss 应用](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.