Web Widget 宿主 API

标准安装

标准安装异步加载并自动初始化。聊天 iframe 只在访客首次打开时加载。

<script async src="https://support.example.com/support/embed.js" data-widget-key="YOUR_WIDGET_KEY"></script>

页面只允许挂载一个 IMCoreWidget。需要在 loader 下载完成前调用 API 时，使用管理后台“安装代码”中的高级安装片段；它会先建立调用队列。

生命周期

IMCoreWidget.init();    // data-auto-init="false" 时手动初始化
IMCoreWidget.open();
IMCoreWidget.close();
IMCoreWidget.show();    // 显示组件，保留会话
IMCoreWidget.hide();    // 隐藏组件，保留会话
IMCoreWidget.destroy(); // 移除 DOM；再次 init() 会重新创建

除 getState() 外，方法都返回 IMCoreWidget，可以链式调用。

访客与业务上下文

应从已登录的宿主应用读取资料。访客资料只用于展示和客户 360，不作为认证凭据；服务端仍会签发独立的匿名 guest ID 和短期 JWT。

IMCoreWidget.setVisitor({
  name: 'Ada',
  email: 'ada@example.com',
  phone: '+86 138 0000 0000',
  avatar: 'https://example.com/ada.png',
  fields: {
    member_level: 'gold',
    account_id: 'account-42'
  }
});

IMCoreWidget.setSessionVariables({
  order_id: 'order-123',
  product_sku: 'sku-7'
});

fields 与 session variables 最多各 50 项；键最长 64 字符，值最长 512 字符。服务端会再次验证长度和类型。

loader 初始化时自动采集当前页面的 URL 路径（不含 query/hash）、标题、referrer 路径和语言，避免查询参数中的 token 或隐私数据被自动上传。SPA 路由变化后调用：

IMCoreWidget.updateContext();

也可以显式传值：

IMCoreWidget.updateContext({
  url: location.href,
  title: document.title,
  language: document.documentElement.lang
});

事件

const unsubscribe = IMCoreWidget.on('ready', (state) => {});
IMCoreWidget.on('open', (state) => {});
IMCoreWidget.on('close', (state) => {});
IMCoreWidget.on('visibility_changed', ({ open, visible }) => {});
IMCoreWidget.on('connection_changed', ({ connection }) => {});
IMCoreWidget.on('message', ({ direction, messageID, senderID }) => {});
IMCoreWidget.on('unread_count_changed', ({ unread }) => {});
IMCoreWidget.on('handover_changed', ({ stage }) => {});
IMCoreWidget.on('error', ({ code, message }) => {});

unsubscribe();
// 或 IMCoreWidget.off('ready', handler)

当前状态可同步读取：

const state = IMCoreWidget.getState();

状态包含 initialized、ready、open、visible、connection、unread、stage、visitor 和 context。

安全与部署

为每个 widget 配置精确的允许来源，例如 https://shop.example.com。
宿主 CSP 至少需要允许 widget 域名的 script-src、connect-src 和 frame-src。高级安装包含内联队列脚本，需要 nonce 或 hash；严格 CSP 网站可保留标准安装，并在外部业务脚本的 load 回调后调用 API。
loader 和 iframe 双向通信都会校验精确 origin、发送窗口和消息类型，不接受任意命令透传。
不要把密码、支付卡数据、access token 或其他秘密放进 visitor fields/session variables。