Connector SDK 适合自研网站、定制 CMS、Node 服务和需要自行实现站点代理的客户。它不是一个完整插件，而是一组接入 GrowthOS 的代码能力。 SDK 当前包含三类能力：
  • GrowthOSServerConnectorClient：用于服务端连接器、客户后端和自研插件，持有 GrowthOS site token。
  • GrowthOSBrowserWidgetClient：用于浏览器代码，只能请求客户站点代理，不能接触 site token。
  • GrowthOSChatWidget：用于自研网站的内置 AI 客服前端窗口，包含主题、语言、推荐问题、事件上报和人工消息轮询。

​
下载

名称版本更新时间获取方式
Connector SDK0.2.12026-06-08下载
不要在浏览器代码中使用 GrowthOS site token。site token 只能保存在客户服务端或连接器服务中。

​
安装与接口域名

npm install ./growthos-connector-0.2.1.tgz
生产开放接口域名是： 
https://open.tui161.com
SDK 的服务端 baseUrl 只需要传域名 origin。SDK 内部会自动拼接标准路径 /api/connector/v1。 
const connectorApiUrl = "https://open.tui161.com";
不要把 baseUrl 写成 https://open.tui161.com/api/connector/v1，否则会重复拼接路径。

​
激活连接器

激活阶段不需要 site token。客户提交授权码后，GrowthOS 返回站点身份和 site token，连接器需要把 token 安全保存在服务端。 
import { activateGrowthOSConnector } from "@growthos/connector";

const activation = await activateGrowthOSConnector(
  { baseUrl: process.env.GROWTHOS_CONNECTOR_API_URL! },
  {
    licenseCode: process.env.GROWTHOS_LICENSE_CODE!,
    domain: "https://customer.example",
    platform: "custom",
    siteName: "Customer Site",
    primaryLocale: "zh-CN",
    supportedLocales: ["zh-CN", "en-US"]
  }
);

const siteToken = activation.data.siteToken || activation.data.token;

​
服务端客户端

服务端客户端负责调用标准 SaaS Connector API。它可以放在客户后端、定制 CMS 插件、独立连接器服务或云函数里。 
import { createGrowthOSServerConnectorClient } from "@growthos/connector";

const growthos = createGrowthOSServerConnectorClient({
  baseUrl: process.env.GROWTHOS_CONNECTOR_API_URL!,
  token: process.env.GROWTHOS_SITE_TOKEN!,
  timeoutMs: 20000,
  retries: 1
});

const status = await growthos.getSiteStatus();
服务端客户端常用能力：
能力方法
查询站点状态getSiteStatus()
获取 AI 客服配置getChatConfig(locale)
发送 AI 客服消息sendMessage(input)
拉取会话消息listMessages(input)
获取人工在线状态getPresence(conversationId)
上报行为事件track()、trackBatch()
同步站点内容syncContent()、syncContentPages()
拉取 SEO/GEO overlaylistSeoOverlays()
领取云端任务claimNextJob()
完成云端任务completeJob()

​
浏览器代理客户端

浏览器客户端不直连 open.tui161.com，而是请求客户站点自己的代理接口。代理接口再由服务端携带 site token 转发到 GrowthOS。 
import { createGrowthOSBrowserWidgetClient } from "@growthos/connector";

const client = createGrowthOSBrowserWidgetClient({
  proxyBaseUrl: `${window.location.origin}/api/growthos`
});

await client.track("page_view");

const reply = await client.sendMessage({
  message: "你好，我想了解报价",
  locale: "zh-CN",
  sourcePage: location.pathname
});
浏览器客户端会自动维护 visitorId 和 conversationId，客户不需要在前端保存 site token。

​
内置 AI 客服窗口

对于无法使用 WordPress 插件的自研网站，可以直接使用 SDK 挂载完整 AI 客服窗口。 
import { createGrowthOSChatWidget } from "@growthos/connector";

const widget = createGrowthOSChatWidget({
  proxyBaseUrl: `${window.location.origin}/api/growthos`,
  theme: "light_blue",
  locale: "zh-CN",
  assistantName: "AI 客服",
  avatarUrl: "/ai-avatar.png",
  suggestedQuestions: ["什么价格？", "需要多久？", "售后如何？"]
});
窗口支持：
能力说明
主题预设teal、blue、emerald、violet、amber、rose、slate、light_teal、light_blue、light_amber、light_rose
自定义主题使用 theme: "custom" 和 themeTokens 覆盖颜色
推荐问题SaaS 配置或 SDK suggestedQuestions 都可以显示，点击后自动发送
多语言自动匹配浏览器语言、页面 html lang 或显式 locale
访客持久化自动保存 visitor ID、conversation ID 和最后消息时间
行为事件自动上报 page view、打开、关闭、用户发送消息
人工接管根据 presence 结果决定是否轮询人工回复
慢响应恢复AI 回复慢或请求中断时，会继续拉取会话消息恢复结果
常用控制方法： 
widget.open();
widget.close();
widget.reloadConfig();
widget.setTheme("teal");
widget.destroy();

​
客户站点代理接口

如果使用浏览器客户端或内置窗口，客户站点需要提供以下代理路径。路径前缀可以自定义，例如 /api/growthos。 
GET  /api/growthos/chat/config
POST /api/growthos/chat/messages
GET  /api/growthos/chat/messages
GET  /api/growthos/chat/presence
POST /api/growthos/events
代理服务端再转发到标准 SaaS 开放接口： 
GET  https://open.tui161.com/api/connector/v1/chat/config
POST https://open.tui161.com/api/connector/v1/chat/messages
GET  https://open.tui161.com/api/connector/v1/chat/messages
GET  https://open.tui161.com/api/connector/v1/chat/presence
POST https://open.tui161.com/api/connector/v1/events
服务端转发时必须附带 site token： 
Authorization: Bearer GROWTHOS_SITE_TOKEN

​
样式隔离

内置窗口默认启用 Shadow DOM，客户网站的大部分全局 CSS 不会影响窗口内部样式。 
createGrowthOSChatWidget({
  proxyBaseUrl: "/api/growthos",
  shadowDom: true
});
如果宿主应用必须直接覆盖内部样式，可以设置 shadowDom: false。这种模式下 SDK 仍使用 growthos-widget-* 命名空间，但样式走形风险会更高。 实际上线前建议在客户真实页面预览，重点检查：
  • 页面是否有很高的固定层级遮挡窗口。
  • CSP 是否允许 SDK 脚本和头像图片加载。
  • 全局 transform、zoom 或 iframe 是否影响固定定位。
  • 移动端视口高度是否压缩输入框。

​
可靠性默认值

SDK 默认包含：
  • 请求超时控制。
  • 瞬时错误重试和退避。
  • Retry-After 处理。
  • mutating 请求自动 idempotency key。
  • 标准化 ConnectorApiError。
  • 分页内容同步 helper。
重试只能覆盖网络抖动和短暂冲突。业务状态、token 泄露、接口权限和客户站点代理实现仍需要连接器服务自己保证。