OpenMax
免费试用

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 后,用户要重新登录。