Chat SDK 接入
在你的页面里放 OpenMax 会话:模板怎么选、token 不进浏览器的做法、常见坑。
Chat SDK 接入
需要在你的页面里放 OpenMax 会话(和人、和 agent 聊)时用。安装、组件、能力、凭据、scope、多语言、主题、卡片、实时连接的用法见 Chat SDK 文档(教程:入门和接入指南;参考:组件和 API);能不能用见调用平台能力「能力清单」。本页只写模板怎么选和参考实现的做法。
模板的选择
- 锁精确版本:四个包(
@openmaxai/chat、@openmaxai/chat-store、@openmaxai/chat-sdk、@openmaxai/chat-openmax)装同一个版本,依赖里写死版本号(不用^,也不用 dist-tag),升级时逐版看 CHANGELOG(所有导出都是实验性的)。现在是 3.0.0-beta.5。 - 用
{ adapter }写法:createChatHost({ adapter: createOpenMaxAdapter(config), cards, onUnauthorized, onEvent, profileCardActions })。不用 chat-openmax/react 的一行写法做模板:它不收 cards、onUnauthorized、onEvent、profileCardActions,业务卡、名片、凭据失效回调都做不出来。 - storage 设
"localStorage":默认的"memory"每次加载都算新设备、每次连上重推收件箱最早的 100 条。host.dispose()不要放进可能重复执行的 effect cleanup。 - 主题、语言接宿主:把宿主的语言(en / zh)映射成 en-US / zh-CN,主题的 mode 映射到 ChatRoot 的 colorScheme。
建议做法:token 不进浏览器
- SDK 的 baseUrl / wsUrl 指向本站同源网关,getToken 回占位串;OpenMax token 只在服务端,refresh token 加密存。网关的认证、路径、查询、请求头都按白名单放行,并限频(示例:REST 每人每分钟 120 次)。
- 网关要额外放行实时连接:换票接口
POST {baseUrl}/auth/ws-ticket(不在/api/v1下);WebSocket 地址上的 ticket、device_id 两个查询参数;WS 代理透传 Upgrade、Connection,改写或去掉 Origin。附件上传、下载地址不经网关,附件域名单独放行。 - 网关模式下 401 由网关自己处理:浏览器拿的是占位串,续不了;401 必须由网关在服务端刷新后重放,透传给浏览器会被判为凭据失效、停止实时连接。
- 用 OpenMax 登录时一并申请聊天相关 scope 和 offline_access。用应用 OAuth 令牌喂 SDK 是参考实现的做法,Chat SDK 文档只写了「个人 API Key 放服务端换短期令牌」。
踩过的坑
- chat-openmax 要自己包一层的地方(按 beta.5 核过):遇 forbidden 界面上不提示「实时已停」;identity.me 只认
/me;敏感内容拦截 SDK 没有;identity.members 遇 403 / 404 报错、不降级。 - 老 token 换不出新 scope:加了聊天 scope 后,用户要重新登录。
