在现有网页项目中集成 SDK

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

1. 安装并初始化 SDK

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

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

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

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

2. 修改配置文件

创建项目后 granite.config.ts 文件会自动生成。 appName, displayName, icon请修改为与注册到 Apps in Toss 控制台的应用信息相同。

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',
});

很重要

appName是用于识别各个应用的 唯一键。
intoss://{appName} 形式的深链接路径，以及测试·发布时也会使用。
在沙盒应用中测试时也通过 intoss://{appName}进行访问。不过，在通过“发布”菜单的 QR 码测试时， intoss-private://{appName}会使用。

3. 安装 TDS

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

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

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

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

TDS 组件的使用方法和指南请 TDS WebView 文档查看。

4. 运行项目

npm run dev

pnpm run dev

yarn dev

5. 运行迷你应用

开发服务器启动后，就可以在沙盒应用中查看迷你应用。关于在本地沙盒应用中测试的详细方法，沙盒应用文档请查看。

在真机上访问开发服务器

要在真机上测试，运行打包器时请 --host 选项启用，并且 web.host需要设置为真机可访问的网络地址。

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: [],
});

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

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

6. 调试

Android — Chrome DevTools

需要准备

要在设备上调试，需先启用 USB 调试。 设置 → 系统 → 关于手机 → 开发者选项 → 启用 USB 调试

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

iOS — Safari 开发者工具

需要准备

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

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

7. 构建并在 Toss 应用中进行最终测试

在沙盒应用中完成开发和基本验证后 npm run build生成应用 bundle 后，请上传到控制台进行最终测试。必须完成 Toss 应用测试后才能发送发布申请。详细方法请参考测试 Toss 应用文档。

8. 发布

发布方法是迷你应用发布文档。