合从文档中心

Appearance

接入代码与配置项 ​

一段 script 标签装上聊天窗，一个就绪回调拿到全部命令。这是网页接入渠道全部的接入层配置。

接入代码 ​

从工作台 设置 > 渠道管理 > 选择渠道 > 安装代码 复制，贴到页面 </body> 之前：

html
<script async
  src="https://assets.aihecong.com/sdk/hecong.js"
  data-channel-id="0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b">
</script>

聊天窗读取 script 标签上的 data-* 属性自行完成初始化，你这边不用写初始化代码。

可配的属性只有两个 ​

属性必填说明
data-channel-id✅渠道编号，工作台复制出来的代码里已经填好
data-language访客界面语言，BCP 47 标记如 zh-CN / en / ja

多语言站点在每个语言版本的页面上传对应的 data-language。填了不认识的值不会出问题，会自动回落到访客的浏览器语言。

其余配置都在工作台

按钮文案与位置、主题色、欢迎语、快捷按钮、询前表单、对话评价，全部在工作台里可视化配置。代码里传不进去，也不需要传 —— 运营改文案不用等发版。

拿到命令对象 ​

要传客户身份、监听事件或者程序化开关聊天窗，在上面那段 script 之后加一段：

html
<script>
  window.hecong = window.hecong || function (c) { (window.hecong.q = window.hecong.q || []).push(c) }
  window.hecong(function (hc) {
    hc.identify({ id: 'c9a1f0e2-7b34-4d58-9f61-0ab2d3c4e5f6', profile: { name: '张三' } })
  })
</script>

第一行是占位函数，照原样复制，不要改写。接入脚本带 async 异步加载，你的代码很可能先于它执行 —— 这一行保证 window.hecong 从一开始就存在，早调的回调先进队列，脚本就绪后依次执行。一个页面写一份就够，放在最早执行的那段脚本里；重复出现也无害，|| 守护会保留先写的那份，文档各页示例自带这一行只是为了能独立复制。

有了它，window.hecong(cb) 什么时机调都行：

  • 脚本还没加载完就调用，回调排队，就绪后依次执行
  • 已经就绪之后才调用，回调立即执行
  • 所以紧跟接入代码写、在标签管理器里异步注入、在单页应用的 useEffect 里、甚至路由切换之后再注册，都不会漏

回调参数 hc 就是命令对象，全部方法见接口速查。

更习惯用原生事件的话，也可以监听 hecong:ready：

js
window.addEventListener('hecong:ready', function (e) {
  e.detail.open()
})

e.detail 就是命令对象。注意它是一次性广播，监听要写在跟接入 script 标签同一处的内联脚本里，保证先于脚本加载执行；注册晚了就静默错过，不会报错。拿不准时序就用上面的 window.hecong(cb)，它没有这个限制。

本地开发与域名限制 ​

新建的渠道不限制域名，代码贴哪都能跑，本地 localhost 直接就能调通。

在工作台 设置 > 渠道管理 > 安全与隐私 里填了授权域名之后，才开始校验，没填进去的域名会拿到 401。填的时候注意：

要填的怎么写
本地开发localhost —— 只匹配主机名，不要带端口和协议
局域网真机调试填那台机器的 IP，如 192.168.1.7
一批子域*.example.com 匹配任意子域，但不包含 example.com 本身，裸域要另填一条

大小写不敏感。

内容安全策略 ​

多数网站没有配 CSP，这一节可以跳过。配了的话，把合从的域名整体放行：

script-src  https://*.aihecong.com
connect-src https://*.aihecong.com wss://*.aihecong.com
img-src     https://*.aihecong.com data: blob:
style-src   'unsafe-inline'
media-src   https://*.aihecong.com blob:

connect-src 的 https 和 wss 两条都要写，只写 https 会表现为聊天窗能加载但收不到消息。style-src 需要 'unsafe-inline'，聊天窗的样式注入在 Shadow DOM 内，作用域不会越出聊天窗。

服务端渲染的项目 ​

聊天窗依赖 document 和 window，不能在服务端执行。在 Next.js、Nuxt 这类框架里，把 script 标签放在只在浏览器执行的位置：

jsx
// app/layout.tsx
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          async
          src="https://assets.aihecong.com/sdk/hecong.js"
          data-channel-id="0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
          strategy="afterInteractive"
        />
        <Script id="hecong-stub" strategy="beforeInteractive">
          {'window.hecong = window.hecong || function (c) { (window.hecong.q = window.hecong.q || []).push(c) }'}
        </Script>
      </body>
    </html>
  )
}
vue
<!-- 放在 app.vue 这类整个应用只执行一次的位置，别放进会随路由反复挂载的组件 -->
<script setup>
onMounted(() => {
  window.hecong = window.hecong || function (c) { (window.hecong.q = window.hecong.q || []).push(c) }
  const s = document.createElement('script')
  s.async = true
  s.src = 'https://assets.aihecong.com/sdk/hecong.js'
  s.dataset.channelId = '0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b'
  document.body.appendChild(s)
})
</script>

两个片段里那行占位函数来自上文拿到命令对象 —— 组件里的 window.hecong(cb) 可能先于接入脚本执行，有这一行就什么时机调都行。Next.js 里它用 beforeInteractive，是为了抢在所有业务代码之前执行；主脚本维持 afterInteractive 不变。

合从不提供 npm 包

聊天窗只有 script 标签这一种接入方式，npm registry 上没有任何 @hecong/* 包。React、Vue 项目同样用上面的 script 标签，在组件里调 window.hecong(cb)，写法见 React 与 Vue 接入示例。

下一步 ​