TOSS小程序webviewSDK

此部分原文 ，如果出现翻译错误请参考原文

::: tip 本指南将基于 Vite（React + TypeScript） 环境进行说明，以便更容易理解。 即使使用其他构建环境也完全没有问题。 :::

在现有 Web 项目中安装@apps-in-toss/web-framework后，您即可在 App-in-Toss Sandbox 中直接进行开发与发布。

安装

在现有 Web 项目中，根据您所使用的包管理器执行以下相应命令.

::: code-group

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


```sh [pnpm]
pnpm install @apps-in-toss/web-framework

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


:::

## 环境配置

可以通过执行 `ait init` 命令完成环境配置

1. 执行 `ait init` 命令

::: code-group

```sh [npm]
npx ait init

```sh [pnpm] pnpm ait init


```sh [yarn]
yarn ait init

:::

::: tip 若出现Cannot set properties of undefined (setting 'dev') 错误：

请在 package.json 的 scripts.dev 字段中填写您原本用于启动开发模式的命令，然后重新执行.

:::

  1. 选择 web-framework
  2. 输入应用名称(appName)

::: tip 在输入appName时请注意

  • 该名称需与您在 App-in-Toss Console 创建应用时所使用的名称保持一致.
  • 앱应用名称作为每个应用的唯一识别键.
  • appName 也用于深度链接路径，格式为 intoss://{appName}/path，或者用于测试和部署期间使用的应用程序特定地址。

  • 在 Sandbox 中进行测试时，请通过：intoss://{appName} 进入 但在“发布”页面通过二维码测试应用时，将使用：intoss-private://{appName} :::

  • 输入 Web 打包工具的 dev 命令.

  • 输入 Web 打包工具的 build 命令.
  • 输入 Web 开发服务器使用的端口号.

检查生成的文件

完成设置后，将生成如下 granite.config.ts 文件。

::: code-group

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

export default defineConfig({ appName: 'ping-pong', // 在 App-in-Toss Console 中设置的应用名称 brand: { displayName: '%%appName%%', // 请替换为在界面中显示的应用名称（韩文） primaryColor: '#3182F6', // 请替换为在界面中显示的应用主色 icon: null, // 请替换为在界面中显示的应用图标地址 }, web: { host: 'localhost', // 应用内 WebView 使用的 host port: 5173, commands: { dev: 'vite', // 启动开发模式 (也可以使用 webpack serve) build: 'vite build', // 构建命令（也可以使用 webpack） }, }, permissions: [], });


:::

* `brand`: 与应用品牌相关的配置。
  * `displayName`: 在 Bridge View 中显示的应用名称。
  * `icon`: 应用图标的图片地址，用于向用户传达应用品牌。
  * `primaryColor`: 在 Toss Design System（TDS）组件中使用的主色。请使用 RGB HEX 格式（例如：#3182F6）。
  * `bridgeColorMode`: Bridge View 的背景颜色类型。可选择白色背景的 `basic` 或深色背景的 `inverted`。
* `web.commands.dev` 字段：执行 `granite dev` 命令时同时运行的命令。请输入启动打包工具开发模式的命令。
* `web.commands.build` 字段：执行 `granite build` 命令时同时运行的命令。请输入打包工具的构建命令。
* `webViewProps.type`: 选项可设置以下三种值之一（译注：原文就只有下面两项）：

  * `partner`: 合作伙伴内容所使用的默认 WebView。如未设置其他值，则使用该值作为默认。
  * `game`: 用于游戏内容等需要全屏展示的场景，适用于占满可视区域的布局。


::: tip Web 构建注意事项

执行 `granite build` 时，会同时执行 `web.commands.build`，并基于该过程生成的构建产物创建 `.ait` 文件。其中，`web.commands.build` 的输出路径必须与 `granite.config.ts` 中的 `outdir` 保持一致。
`outdir` 的默认值为项目路径下的 `dist` 文件夹，您也可以根据需要在 `granite.config.ts` 中进行修改。请务必注意，如构建产物保存至与 `outdir` 不一致的路径，可能会导致发布流程无法正常进行。

:::

### WebView TDS 패키지 설치하기（译注：未翻译）

**TDS (Toss Design System)** 패키지는 웹뷰 기반 미니앱이 일관된 UI/UX를 유지하도록 돕는 토스의 디자인 시스템이에요.\
`@apps-in-toss/web-framework`를 사용하려면 TDS WebView 패키지를 추가로 설치해야 해요.\
모든 비게임 WebView 미니앱은 TDS 사용이 필수이며, 검수 승인 기준에도 포함돼요.

| @apps-in-toss/web-framework 버전 | 사용할 패키지              |
| -------------------------------- | -------------------------- |
| < 1.0.0                          | @toss-design-system/mobile |
| >= 1.0.0                         | @toss/tds-mobile           |

TDS에 대한 자세한 가이드는 [WebView TDS](https://tossmini-docs.toss.im/tds-mobile/)를 참고해주세요.

## 启动服务器

### 启动本地(local)开发服务器

启动本地开发服务器时，将同时运行 Web 开发服务器与 React Native 开发服务器。
Web 开发服务器会使用在 `granite.config.ts` 文件中 `web.commands.dev` 字段所配置的命令来启动。同时支持 HMR（Hot Module Replacement），可实时反映代码变更。

以下是用于启动开发服务器的命令:

使用 Granite 脚手架创建的服务，可通过 `dev` 脚本来启动本地服务器。
请在服务的根目录下执行以下命令.

::: code-group

```sh [npm]
npm run dev

```sh [pnpm] pnpm run dev


```sh [yarn]
yarn dev

执行命令后，将显示如下画面

::: tip 运行或构建时出现“[Apps In Toss Plugin] 插件选项无效” 错误 当出现“[Apps In Toss Plugin] 插件选项无效。请检查 granite.config.ts 配置。”时请检查 granite.config.ts 中的 icon 配置。 如果尚未确定应用图标，也可以暂时将其设置为空字符串 ''，即可继续进行测试.

[

...
displayName: 'test-app', // 화면에 노출될 앱의 한글 이름으로 바꿔주세요.
primaryColor: '#3182F6', // 화면에 노출될 앱의 기본 색상으로 바꿔주세요.
icon: '',// 화면에 노출될 앱의 아이콘 이미지 주소로 바꿔주세요.
...

疑似是想在tip里插代码结果没显示出来，这边就不翻译了] :::

使开发服务器可在真实设备上访问

若需要在真实设备上进行测试，需在启动打包工具时启用 --host 选项，并将 web.host 设置为真实设备可访问的网络地址。

```ts [granite.config.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: [], });


## 运行 Mini App（模拟器 / 真机）

:::info 需要准备
Mini App 必须通过 Sandbox App 执行，因此需要先安装 **Sandbox App（测试应用）**。
请安装 Sandbox App(译注：原文为下载页链接，请至原文进入下载页下载，本文不提供其沙盒app下载) 以便进行开发与测试。
:::

### 在 iOS 模拟器（Sandbox App）中运行

1. 启动 **App-in-Toss Sandbox App**
2. 在 Sandbox App 中执行 Scheme例如服务名称为 `kingtoss`，输入：`intoss://kingtoss` 并点击 「打开 Scheme」 按钮.

以下是在本地服务器启动后，通过 iOS 模拟器中的 Sandbox App 连接服务器的示例：
![](/assets/toss_mini_support/web_view_sdk/local-develop-ios-sim-example.mov)

### 在 iOS 真机上运行

#### 配置服务器地址

若要在 iPhone 上运行 **App-in-Toss Sandbox App**，iPhone 必须与本地服务器处于同一 Wi-Fi 网络环境。请按照以下步骤进行设置：

1) 启动 **Sandbox App** 时，**会出现「局域网」访问权限请求提示**，请点击 **「允许」**

![](/assets/toss_mini_support/web_view_sdk/local-develop-ios-permission.png)

2) **Sandbox App** 中会显示输入服务器地址的界面

3) 在电脑上确认本地服务器的 IP 地址，输入该地址后保存.
* IP 地址保存一次后，即使重新启动应用也不会改变.
* 如果使用 macOS，可在终端执行 `ipconfig getifaddr en0` 命令获取本地服务器 IP 地址.

4) 点击 **「打开 Scheme」** 按钮

5) 当屏幕顶部显示 `Bundling {n}%...` 文本时，即表示已成功连接本地服务器.

![](/assets/toss_mini_support/web_view_sdk/local-develop-ios-example.mov)

::: details 手动允许本地网络访问

**如果未能授予 「局域网」 权限，可通过以下方法手动设置：**
1.在 iPhone 的 「设置」 应用中搜索 **App-in-Toss** 并进入.
2.找到 **「局域网」** 选项并开启.

![](/assets/toss_mini_support/web_view_sdk/local-develop-ios-enable-local-network.png)

:::

***

### 连接 Android 真机或模拟器

1. 使用 USB 将 Android 真机（手机或平板）连接到电脑。

2. 使用 adb 命令连接端口 `8081` 和 `5173`，并检查连接状态。

   **连接 8081 和 5173 端口**

   如果只有一台设备连接，只需执行以下命令即可。

   ```shell
   adb reverse tcp:8081 tcp:8081
   adb reverse tcp:5173 tcp:5173

如需连接特定设备，请添加 -s 选项和设备 ID：

   adb -s {设备ID} reverse tcp:8081 tcp:8081
   #示例: adb -s R3CX30039GZ reverse tcp:8081 tcp:8081
   adb -s {设备ID} reverse tcp:5173 tcp:5173
   #示例: adb -s R3CX30039GZ reverse tcp:5173 tcp:5173

检查连接状态

使用以下命令查看已连接的设备及端口：

   adb reverse --list
   # 已连接示例: UsbFfs tcp:8081 tcp:8081

如需查看特定设备，请添加 -s 选项：

   adb -s {设备ID} reverse --list
   #示例: adb -s R3CX30039GZ reverse --list

   # 已连接示例: UsbFfs tcp:8081 tcp:8081

  1. 在 App-in-Toss Sandbox App 中执行 Scheme. 例如服务名称为 kingtoss，输入：intoss://kingtoss 并点击执行按钮。

    以下是在 Android 模拟器中连接本地服务器后显示服务的示例.

results matching ""

    No results matching ""