。当 `token` 未提供、已过期或鉴权失败时，SDK 会自动调用此方法获取新的访问令牌。 |
| | | | | | \
|**token** |String |否 |czs_hsk********** |访问令牌，用于 Web SDK 鉴权。若传入此参数，Web SD 将优先使用该令牌进行身份验证，优先级高于 `refreshToken`。若无特殊需求，推荐直接使用 `refreshToken` 以实现自动续期。 |
| | | | | | \
|**unauthorizedDescription** |String |否 |鉴权失败 |未授权或鉴权失败时，界面展示的提示文案。 |
| | | | | | \
|**onIframeReady** |() => void |否 |\ |Web SDK 内部 iframe 加载并初始化完成。 |
| | | | | | \
|**onIframeDestroy** |() => void |否 |\ |组件卸载或 iframe 被销毁。 |
| | | | | | \
|**onProjectInfoLoaded** |() => void |否 |\ |成功获取到 AI 编程智能体或工作流项目的基础信息（如名称、图标等）。 |
| | | | | | \
|**onTokenExpired** |() => void |否 |\ |当前 Token 已过期。 |
| | | | | | \
|**onTokenInvalid** |() => void |否 |\ |Token 校验失败（如格式错误、权限不足）。 |
| | | | | | \
|**onNetworkError** |() => void |否 |\ |Web SDK 内部请求发生网络故障。 |
| | | | | | \
|**onNotify** |() => void |否 |\ |接收到 Web SDK 发送的系统通知或状态变更。 |
* **updateConfig(config: Config): void; （更新 Web SDK 配置）**
```JavaScript
interface Config {
theme: string;
....
}
```
支持的配置项如下：
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|**theme** |String |否 |light |界面主题模式。取值如下： |\
| | | | |light（默认值）：明亮模式。 |\
| | | | |dark：暗黑模式。 |
| | | | | | \
|**className** |String |否 |coze-sdk-container |Web SDK 容器的 CSS 类名。 |
| | | | | | \
|**style** |String |否 |width: 100%; height: 600px; border: 1px solid #e5e7eb; border-radius: 8px; |设置 Web SDK 容器的内联样式，例如宽高、边框等。 |
| | | | | | \
|**unauthorizedDescription** |String |否 |鉴权失败 |未授权或鉴权失败时，界面展示的提示文案。 |
* **updateToken(token: string): void;**
```JavaScript
// 手动更新访问令牌。
cozeWebSDK.updateToken('YOUR_NEW_TOKEN');
```
* **destory(): void;**
```JavaScript
// 销毁 SDK 实例，移除 DOM 并解除所有事件监听。
cozeWebSDK.destroy();
```
### React 组件 {#33d6d246}
采用 React 组件 接入方式时，可参照以下操作步骤，同时结合对应的配置参考调整相关参数，确保接入效果符合需求。
#### 操作步骤 {#2d979767}
1. 安装 Web SDK 依赖包。
在项目根目录下执行以下命令：
```Bash
npm i @coze/web-sdk@latest
```
2. 引入并初始化组件。
在你的 React 应用中，引入 `CozeWebSDK`组件并进行基础配置。最简单的渲染方式如下：
```JavaScript
import { CozeWebSDK } from '@coze/web-sdk/react';
const CozeChatPage = () => {
return (
{
// 在 Token 过期时，自动获取 Token。
const data = await fetch('https://YOUR_SERVICE/GET_TOKEN_API');
const result = await data.json();
return result.token;
}}
/>
);
};
```
3. 配置 Token。
* **方式一：Token 过期时自动获取（推荐）**
出于安全考虑，Token 通常具有较短的有效期。建议使用 `refreshToken` 属性，让 SDK 在 Token 过期时自动获取 Token，避免用户对话中断。
```JavaScript
{
// 在 Token 过期时，自动获取 Token。
const data = await fetch('https://YOUR_SERVICE/GET_TOKEN_API');
const result = await data.json();
return result.token;
}}
/>
```
:::tip 说明
* 组件初始化完成后会立即调用一次`refreshToken`获取初始 Token。
* 当 Token 过期后，SDK 会自动调用`refreshToken`进行重试（最多等待 5000 毫秒）。
* 如果超时仍未获取到 Token，SDK 将上报`NETWORK_ERROR`事件。
:::
* **方式二：手动刷新 Token（不推荐）**
通过 React 的 State 来管理 Token。出于安全考虑，不推荐将 Token 作为 State 频繁更新。如果使用此方式，建议你在后端服务为 Token 设置较短的过期时间。
```JavaScript
// 填写准备工作中获取的 Token。
const [token, setToken] = useState('YOUR_TOKEN');
```
#### 配置参考 {#4a124046}
配置 CozeWebSDK 组件属性 ，以满足定制化需求。
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|**projectId** |String |是 |761559609158873**** |项目 ID，用于指定要加载的智能体或工作流。 |
| | | | | | \
|**theme** |String |否 |light |界面主题模式。取值如下： |\
| | | | |light（默认值）：明亮模式。 |\
| | | | |dark：暗黑模式。 |
| | | | | | \
|**className** |String |否 |coze-sdk-container |Web SDK 容器的 CSS 类名。 |
| | | | | | \
|**style** |String |否 |width: 100%; height: 600px; border: 1px solid #e5e7eb; border-radius: 8px; |设置 Web SDK 容器的内联样式，例如宽高、边框等。 |
| | | | | | \
|**wrapClassName** |String |否 |coze-sdk-wrapper |外层包装元素的 CSS 类名，可用于全局样式控制。 |
| | | | | | \
|**wrapStyle** |String |否 |margin: 20px auto; max-width: 1200px; |外层包装元素的内联样式，例如居中、最大宽度、外边距等。 |
| | | | | | \
|**refreshToken** |() => string | Promise |否 |async () => { const res = await fetch('/api/get-coze-token'); const data = await res.json(); return data.access_token; } |刷新访问令牌，支持返回字符串或 Promise。当 `token` 未提供、已过期或鉴权失败时，SDK 会自动调用此方法获取新的访问令牌。 |
| | | | | | \
|**token** |String |否 |czs_hsk********** |访问令牌，用于 Web SDK 鉴权。若传入此参数，Web SD 将优先使用该令牌进行身份验证，优先级高于 `refreshToken`。若无特殊需求，推荐直接使用 `refreshToken` 以实现自动续期。 |
| | | | | | \
|**unauthorizedDescription** |String |否 |鉴权失败 |未授权或鉴权失败时，界面展示的提示文案。 |
| | | | | | \
|**onIframeReady** |() => void |否 |\ |Web SDK 内部 iframe 加载并初始化完成。 |
| | | | | | \
|**onIframeDestroy** |() => void |否 |\ |组件卸载或 iframe 被销毁。 |
| | | | | | \
|**onProjectInfoLoaded** |() => void |否 |\ |成功获取到 AI 编程智能体或工作流项目的基础信息（如名称、图标等）。 |
| | | | | | \
|**onTokenExpired** |() => void |否 |\ |当前 Token 已过期。 |
| | | | | | \
|**onTokenInvalid** |() => void |否 |\ |Token 校验失败（如格式错误、权限不足）。 |
| | | | | | \
|**onNetworkError** |() => void |否 |\ |Web SDK 内部请求发生网络故障。 |
| | | | | | \
|**onNotify** |() => void |否 |\ |接收到 Web SDK 发送的系统通知或状态变更。 |
### Iframe {#a6b4f59d}
通过 Iframe 接入 Web SDK 的操作步骤如下。
1. 添加 Iframe 标签。
在你的 HTML 页面中添加一个 `