嵌入集成

如果你正在把 HENGSHI SENSE 集成到自己的门户、业务系统或 OEM 页面里，最常见的问题通常不是“能不能嵌入”，而是“嵌入后怎么和宿主系统协同工作”。这页把最常被客户和客服反复确认的问题集中整理出来。

嵌入链接应该从哪里开始拼？

建议始终先从产品页面里生成可用的分享/嵌入链接，再在这个基础上追加参数，而不是完全手写 URL。

• 已经完成登录打通时，通常从发布页或应用页的嵌入链接开始
• 需要在 URL 中指定认证方式时，再追加 activeAuth、reloadUser、jwtParam 等参数
• 需要控制页面表现时，再追加 header=false、pager=false、locale=en-US 这类参数

这样做更稳妥，因为路径层级、资源 hash 和可用参数会随着嵌入对象不同而变化。

相关文档：

• 嵌入样式定制化
• 外部控制嵌入 URL
• 嵌入页面的外部控制

嵌入 URL 常用参数有哪些？

最常见的是下面几类：

需求	常用参数	说明
指定语言	locale=en-US	适合多语言门户、OEM 场景
隐藏页面标题	header=false	常用于发布页嵌入
隐藏翻页器	pager=false	适合只保留内容区
同时隐藏标题和翻页器	copyright=false	等价于 header=false&pager=false
减少边距	chartPadding=0 或 padding=0	适合紧凑卡片式布局
公开链接传参	appParam=[...]	用于公开链接下的参数控制

如果你需要的是“嵌入后还能继续在系统内多层导航”，则要同时考虑嵌入层级参数，例如 L0 / L1 / L2 / L3 这类路径级控制。

宿主页面可以控制刷新、全屏或联动吗？

可以，但建议优先复用已有页面集成能力，而不是自己在宿主页面里重新实现一套交互。

• 刷新：优先使用 嵌入页面的外部控制 中已有的外部触发方式
• 全屏：优先由宿主页面控制 iframe 容器进入全屏，再配合嵌入页布局参数
• 语言切换：优先由宿主系统切换语言后，统一改写嵌入 URL 上的 locale

如果你发现“CLI 或外部脚本改了资源，但嵌入页没同步刷新”，通常更应该先排查宿主页面是否触发了刷新、当前页面是否走缓存，而不是先怀疑嵌入本身失效。

嵌入场景下为什么会遇到跨域问题？

最常见的原因是宿主系统域名和 HENGSHI SENSE 域名不同，而浏览器对 iframe、cookie、脚本访问都有同源限制。

通常按下面顺序处理：

1. 优先通过反向代理把宿主系统和 HENGSHI SENSE 放到同一主域或可控代理链路下
2. 必要时在系统配置里设置 ACCESS_CONTROL_ALLOW_ORIGIN
3. 如果还涉及宿主页面 JS 直接访问 iframe 内部对象，要先确认这件事是否本来就会被浏览器同源策略拦住

如果只是“页面能打开，但某些 JS 联动失败”，大概率不是 HENGSHI 页面没加载，而是浏览器不允许跨域脚本互访。

嵌入场景下，应该优先用 iframe 还是 API？

绝大多数项目，优先推荐 页面嵌入。

因为 iframe / 页面集成可以直接复用现成的图表、权限、筛选、发布和样式能力，实施成本更低，也更容易和产品升级保持一致。只有当你明确需要自己重建展示层、交互层或外部系统编排逻辑时，才建议继续往 API 集成方向走。

可以先看：

• 嵌入式数据分析场景解决方案
• 应用分享嵌入