> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.
本文介绍如何安装并使用扣子编程低代码 Web SDK，开发者可以参考本文档在自己开发的网站中快速集成一个扣子低代码 AI 应用，为网站集成智能服务。
## 功能简介 {#8b5dd000}
:::tip 说明
扣子编程提供两种不同的 Web SDK，分别适用于 AI 编程项目和低代码应用。本文档适用于低代码项目，如需在网站中嵌入 AI 编程搭建的智能体或工作流，请参见[Web SDK（AI 编程）](/developer_guides/vibe_coding_websdk)。
:::
**核心优势**：
* **无缝集成：** 将已发布的低代码应用作为独立组件嵌入 Web 页面。
* **开箱即用：** 集成后，低代码应用的 UI 和逻辑**无需二次开发**即可运行。
* **快速部署：** 通过简单的代码引入，可在几分钟内完成集成。
**场景示例**：
Web SDK 适用于需要在各类网站或 Web 页面中快速集成完整 AI 应用的场景，例如：
* 在内部业务系统中嵌入业务流程 AI 辅助工具，例如报销单填写助手等。
* 在电商平台嵌入交易辅助工具，例如 AI 导购/推荐助手等。
* 在内容平台嵌入内容处理工具，例如文本生成、信息提炼工具等。
## 体验 UI Builder {#1e1ae071}
你可以在[扣子 Playground 的 Web SDK](https://www.coze.cn/open/playground/uibuilder) 页面体验 Web SDK 的使用效果。
::::cols
@col 50
@col 50
::::
## 准备工作 {#469bfeef}
### 环境要求 {#bd8c134e}
Web SDK 的浏览器兼容性及运行环境要求如下表所示。
| | | \
|**浏览器** |**版本限制** |
|---|---|
| | | \
|Chrome | 87.0 及以上 |
| | | \
|Edge | 88.0 及以上 |
| | | \
|Safari | 14.0 及以上 |
| | | \
|Firefox | 78.0 及以上 |
### 获取访问密钥 {#1175b318}
访问密钥用于 Web SDK 的身份认证与鉴权。扣子编程提供多种类型的鉴权方式，你可以根据使用场景选择对应的鉴权方式：
* **体验或调试场景**：建议开发者生成一个短期的个人访问令牌（PAT），快速跑通 Web SDK 的整体流程。 具体步骤请参见[添加个人访问令牌](https://www.coze.cn/open/docs/developer_guides/pat)。
* **线上环境**：线上环境应使用 OAuth 鉴权或 SAT 鉴权，详细说明请参考[鉴权方式概述](https://www.coze.cn/open/docs/developer_guides/authentication)。
### 权限要求 {#89cedc43}
访问密钥必须被授予指定的权限，才能使用 Web SDK 的各项能力。Web SDK 所需的权限列表如下：
| | | | \
|**密钥类型** |**PAT / SAT /普通 OAuth** | **渠道 OAuth 访问密钥** |
|---|---|---|
| | | | \
|权限点 |\
| |* Bot管理 |\
| | * chat |\
| |* 会话管理 |\
| | * listConversation |\
| | * createConversation |\
| | * editConversation |\
| |* 对话 |\
| | * cancelChat |\
| |* 文件 |\
| | * uploadFile |\
| |* 消息 |\
| | * listMessage |\
| |* 工作流 |\
| | * getMetadata |\
| |* 智能音视频 |\
| | * createTranscription |* botChat |\
| | |* listConversation |\
| | |* createConversation |\
| | |* editConversation |\
| | |* uploadFile |\
| | |* listConversationMessage |\
| | |* cancelConversationChat |\
| | |* createTranscription |\
| | | |\
| | | |\
| | | |\
| | | |
## 快速开始 {#d80f86d5}
### 步骤一：发布并获取安装代码 {#275beb81}
1. 将应用发布为 Web SDK，具体步骤请参见[发布为 Web SDK](/guides/app_publish_ui_builder)。
2. 在低代码应用的编排页面单击右上角的**版本记录**图标，选择指定版本的**更多**图标，选择**发布结果**。
3. 确认 Web SDK 发布成功后，单击**安装指引**。
4. 根据页面提示复制安装代码。此代码将在后续安装 Web SDK 时使用。
### 步骤二：安装 SDK {#da504b1b}
将步骤一中复制好的安装代码粘贴到网页的 标签内，当页面加载时，Web SDK 的 JavaScript 代码会被自动加载并初始化。
```XML
```
### 步骤三：配置客户端属性 {#e793a9bc}
你需要配置 Web SDK 的初始化参数、用户信息和 UI 效果。
#### 客户端属性示例代码 {#a17af55e}
配置 Web SDK 客户端属性的示例代码如下：
```TypeScript
const cozeWebSDK = new CozeWebSDK.AppWebSDK({
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
appId: '740849137970326****',
container: '#app',
// 用户信息
userInfo: {
id: '12345',
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.***.png',
nickname: '小明',
},
ui: {
className: 'my-client'
}
})
```
#### 初始化配置 {#2b6f5334}
配置 Web SDK 的初始化参数，包括访问密钥、低代码应用 ID 和渲染的容器。
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|token |String |必选 |pat_zxzSAzxawer234zASNElEglZxcm*** |指定使用的访问密钥。 |\
| | | | |调试场景可直接使用准备工作中添加的访问密钥；正式上线时建议通过 SAT 或 OAuth 实现鉴权逻辑，并将获取的访问密钥填写在此处。 |
| | | | | | \
|appId |String |必选 |740849137970326**** |低代码应用的 ID。在低代码应用编排页面的 URL 中，project-ide 参数之后的字符串就是 appId。 |
| | | | | | \
|container |String |必选 |#app |\
| | | | |网页中承载 Web SDK 所有交互内容的元素的 CSS 选择器，Web SDK 会将其所有交互内容渲染至该元素内部。 |\
| | | | |例如：Web SDK 的安装代码中定义了承载元素 ``，则 `container`的值为 `#app`。 |
#### 用户信息 {#c53c3b28}
`userInfo` 参数用于配置和低代码应用对话的用户的信息，包含用户头像、昵称和用户 ID，用于在应用交互中标识用户。
你可以通过引用变量的方式在应用中动态获取用户的头像和昵称，具体请参见[引用变量](/guides/set_content_parameters#fcd50edb)。
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|url |String |必选 |https://example.com/avatars/user123.png |用户头像的 URL 地址，必须是一个可公开访问的地址。SDK 会通过该地址加载并显示用户头像。 |\
| | | | | |
| | | | | | \
|nickname |String |必选 |小明 |用户的昵称，将在应用界面中显示，用于区分不同的对话用户。 |
| | | | | | \
|id |String |可选 |user_123456 |用户的 ID，即用户在你的网站或应用中的账号 ID。未指定时，Web SDK 会自动为用户分配一个用户 ID。 |\
| | | | |该参数用于在对话时标识具体的用户。 |
#### UI 效果 {#c9db0f49}
Web SDK 初始化后，会在页面中生成一个用于承载应用内容的 iframe 元素，`ui.className` 的值会被添加到该 iframe 的 `class` 属性中。开发者可通过这个类名，自定义该 iframe 的显示样式，实现与页面整体风格的适配。
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|className |String |可选 |coze-app-sdk |为 Web SDK 渲染到页面中的 iframe 元素指定 CSS 类名，开发者可以通过这个类名，自定义样式。 |\
| | | | |不配置时，iframe 使用 Web SDK 的默认样式。 |\
| | | | |例如，若设置为 `coze-app-sdk`，则可在 CSS 中通过 `.coze-app-sdk` 选择器定义该 iframe 的样式，具体示例请参见[完整示例代码](/developer_guides/ui_builder_web_sdk#bd7ded32)。 |
### 步骤四：销毁客户端 {#a3374378}
当用户关闭或退出应用时，调用 `destroy` 方法销毁客户端以释放资源、清理界面。
```TypeScript
```
## 完整示例代码 {#bd7ded32}
以下是一段完整的 Web SDK 的代码示例。
:::: tabs
@tab index.html
```HTML
```
@tab index.js
```TypeScript
const cozeWebSDK = new CozeWebSDK.AppWebSDK({
token: 'pat_zxzSAzxawer234zASNElEglZxcmWJ5ouCcq12gsAAsqJGALlq7hcOqMcPFV3wEVDiqjrg****',
appId: '740849137970326****',
container: '#app',
// 用户信息，用于在对话中标识用户身份
userInfo: {
id: '12345',
url: 'https://lf-coze-web-cdn.coze.cn/obj/coze-web-cn/obric/coze/favicon.***.png',
nickname: '小明',
},
// UI配置：用于自定义应用界面的样式
ui: {
className: 'coze-app-sdk'
}
})
```
@tab main.css
```CSS
/* 基础样式：设置页面整体布局 */
html, body {
height: 100%; /* 让页面高度占满整个浏览器窗口，避免出现垂直滚动空白 */
margin: 0; /* 清除浏览器默认的外边距，消除页面边缘的空白间隙 */
}
/* 自定义Web SDK iframe的样式（类名与JS中ui.className保持一致） */
.coze-app-sdk {
box-sizing: border-box; /* 盒模型规则：iframe的宽高会包含内容、内边距和边框，避免添加样式后整体尺寸变大 */
padding: 4px; /* 为iframe内部内容添加4px内边距，避免内容紧贴边缘 */
}
```
::::
## 常见问题 {#58c9f024}
### Chat SDK 和 Web SDK（低代码） 有什么区别？ {#3335b710}
Chat SDK 和 Web SDK（低代码） 均为扣子编程提供的 SDK，区别如下：
* **支持的应用类型不同**
* Web SDK（低代码）：仅支持**低代码应用**，且用户界面为 Web 端，不支持小程序端。
* Chat SDK：支持**智能体**和**低代码应用**两种类型，支持小程序端。
* **功能特性差异**
* Web SDK（低代码）：低代码应用发布 Web SDK 时，会将低代码应用的**用户界面（UI）和业务逻辑**完整打包发布，集成后可直接在网站中呈现应用的现成交互界面，开发者无需二次开发页面。
* Chat SDK：低代码应用发布 Chat SDK 时，仅包含智能体/低代码应用中的对话流、对话容器部分（Chatbot 类），不包含应用用户界面，主要用于实现用户与 AI 智能体或应用的对话相关功能。