# 内嵌水晶球数据 (/zh-CN/realtime-media/usage-analytics/build/embed-and-maintain-data-service/embeded) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). **水晶球内嵌**功能可以在你的内部系统中快速嵌入水晶球功能,仅需少量开发成本即可实现。具体包括: - 直接在内部系统中查看[水晶球功能列表页面](/zh-CN/realtime-media/usage-analytics/build/embed-and-maintain-data-service/embeded),例如通话调查列表页面。 - 直接在内部系统中查看[通话调查详情页面](/zh-CN/realtime-media/usage-analytics/build/embed-and-maintain-data-service/embeded),包含通话体验质量页面和端到端详情页面。 - 通过设置水晶球内嵌页面属性,在内部系统中实现你的业务功能。例如,结合内部系统的分级权限配置,为不同等级的员工设置不同水晶球内嵌页面的访问权限。 :::warning[注意] 目前支持内嵌的水晶球功能包括通话调查、数据洞察、实时监控和告警通知。 ::: ## 前提条件 [#前提条件] 使用水晶球内嵌功能前,你需要完成如下准备: - 已有安全可靠且有账号控制权限的内部系统。 - 已订阅[水晶球套餐包](/zh-CN/realtime-media/usage-analytics/reference/billing#套餐包详情),且订阅的套餐包支持内嵌你需要的水晶球功能。 ## 使用步骤 [#使用步骤] ### 访问内嵌设置 [#访问内嵌设置] 按以下步骤完成访问内嵌设置: 1. 登录[控制台](https://console.shengwang.cn/),点击左侧菜单栏中的水晶球。 2. 在页面左上方的下拉菜单中选择你要查看的项目。 3. 点击页面右上角的头像,在下拉菜单中点击**内嵌设置**。 ![控制台中的内嵌设置入口](https://web-cdn.agora.io/docs-files/1677148345336) ### 第一步:获取水晶球功能页面 URL [#第一步获取水晶球功能页面-url] 选择你想内嵌的水晶球功能后,下方的示例代码(以 Node.js 为例)将实时更新,参考示例代码在服务端发送 HTTP 请求以获取水晶球功能页面的 URL。 ![获取水晶球功能页面 URL 的示例代码](https://web-cdn.agora.io/docs-portal/img/analytics/embeded-step1.png) #### 获取内嵌专用 ID 和密钥 [#获取内嵌专用-id-和密钥] 调用本文介绍的水晶球内嵌 RESTful API 前,你需要在 `clientId` 和 `clientSecret` 参数中填入水晶球内嵌专用的客户 ID 和客户密钥。该客户 ID 和客户密钥与水晶球 RESTful API 鉴权时使用的客户 ID 和客户密钥不同,你需要[前往申请](https://console-v1.shengwang.cn/credentials)。 - `clientId`: 客户 ID - `clientSecret`: 客户密钥 #### 获取水晶球功能列表页面 URL [#获取水晶球功能列表页面-url] 调用此方法,你可以获取水晶球功能列表页 URL,例如通话调查页面 URL。 **数据格式** 请求和响应的格式为 JSON。 **基本信息** | 请求基本信息 | 描述 | | :----------- | :-------------------------------------------------- | | 方法 | POST | | 请求 URL | `https://analytics-lab.agora.io/api/getEmbedLocation` | **请求包体参数** | 参数 | 描述 | | :------ | :---------------------------------------------------------- | | feature | [embeded-slot-1-2-1 details](#table-slot-embeded-slot-1-2-1) | **embeded-slot-1-2-1 details** 内嵌的水晶球功能。支持设为以下值: - `callSearch`:通话调查功能。 - `realtimeMonitoring`:实时监控功能。 - `dataInsightsPlus`:数据洞察 Plus。 - `dataInsightUsage`:数据洞察-用量概览功能。 - `dataInsightQuality`:数据洞察-质量概览功能。 **请求示例** 以内嵌通话调查功能为例: ```json { "feature": "callSearch" } ``` **响应参数** | 参数 | 描述 | | :---- | :------------------------------------------------------- | | token | 动态密钥。有效期为 2 小时,你需要每 2 小时更新动态密钥。 | **响应示例** ```text https://analytics-lab.agora.io/analytics/call/search?token=xxxxxxxxxxxxxxxxxxxxxx ``` #### 获取通话调查详情页面 URL [#获取通话调查详情页面-url] 将以下参数与 URL 拼接,即可获取通话调查详情页面 URL: URL: https://analytics-lab.agora.io/api/analytics/research | 参数 | 描述 | | --- | --- | | token | 动态密钥,从上一步获取的水晶球功能列表 URL 中获得。 | | cname | [embeded-markdown-3-2-1 details](#table-slot-embeded-markdown-3-2-1) | | fromUid | (选填)发送端用户 ID。 | | toUid | (选填)接收端用户 ID。 | | fromTs | (选填)查询开始时间,Unix 时间戳 (秒)。设置后,你可以查询该时间点(包含)之后的通话。 | | toTs | (选填)查询结束时间,Unix 时间戳 (秒)。设置后,你可以查询该时间点(包含)之前的通话。 | **embeded-markdown-3-2-1 details** 频道名称。 **Note** 需填写正确的频道名称。如果频道名称不存在,你会获取通话搜索页面,但搜索结果为空。 :::warning[注意] - 根据查询参数的设置,你会获取以下两种通话详情页面: - 如果只填写了正确的 `cname`,你会获取通话体验质量页面。 - 如果填写了正确的 `cname`、`fromUid` 和 `toUid`,你会获取通话的端到端详情页面。 - 如果 `cname` 的搜索结果包含多个通话,则获取的是通话搜索页面。 - 如果不设置 `fromTs` 和 `toTs`,则默认显示最近 3 天的搜索结果。 ::: 拼接示例: https://analytics-lab.agora.io/api/analytics/research?token=xxxxxxxxxxxxxxxxxxxxxx&cname=xxxxxxxxxxxxxxxxxxxxxxxx&fromUid=xxxxxx&toUid=xxxxxx 拼接完成后,你需要内嵌通话调查详情页面 URL 至客户端。详见[内嵌水晶球页面至客户端](/zh-CN/realtime-media/usage-analytics/build/embed-and-maintain-data-service/embeded)。 ### 第二步:添加属性至水晶球功能列表页面 URL [#第二步添加属性至水晶球功能列表页面-url] 在**页面属性**菜单,你可以设置水晶球内嵌页面的如下属性: - 语言:选择**中文**或 **English**。 - 时区:选择**本地时区**或 **UTC 时区**。 - 项目权限:选择**任意项目**或**指定项目**。 - 任意项目:员工可访问该账号下开通了对应功能的任意项目。 - 指定项目:员工仅可访问该账号下开通了对应功能的指定项目。选择指定项目后,你需要在下方**默认项目**列表中指定一个可访问的项目。 - 默认项目:声网默认将当前项目设置为内嵌页面的默认项目,你可以修改默认项目。 设置页面属性时,下图中代码会实时更新。 :::warning[注意] 内嵌设置无法保存,页面刷新后会恢复默认设置。完成设置后,请及时拷贝代码。 ::: ![带页面属性的内嵌 URL 拼接示例代码](https://web-cdn.agora.io/docs-files/1684752885693) 页面属性代码中包含如下参数: | 参数 | 描述 | | --- | --- | | locale | [embeded-slot-4-2-1 details](#table-slot-embeded-slot-4-2-1) | | timezone | [embeded-slot-4-3-1 details](#table-slot-embeded-slot-4-3-1) | | showProjectSelector | [embeded-slot-4-4-1 details](#table-slot-embeded-slot-4-4-1) | | projectId | [embeded-markdown-4-4-1 details](#table-slot-embeded-markdown-4-4-1) | **embeded-slot-4-2-1 details** 语言。 - `zh`: 中文。 - `en`: 英文。 **embeded-slot-4-3-1 details** 时区。 - `UTC`: UTC 时区。 - `Local`: 本地时区。 **embeded-slot-4-4-1 details** 是否在页面上显示项目选择下拉框: - `true`: 显示。 - `false`: 不显示。 **embeded-markdown-4-4-1 details** (选填)项目 ID。 **Note** 只有对指定项目设置访问权限时需要填写此字段。 将上述参数与之前获取的[水晶球功能列表页面 URL](/zh-CN/realtime-media/usage-analytics/build/embed-and-maintain-data-service/embeded) 拼接,即可获取含页面属性的水晶球功能列表页面 URL。拼接示例:https://analytics-lab.agora.io/analytics/call/search?token=xxxxxxxxxxxxxxxxxxxxxx&locale=zh&timezone=UTC&showProjectSelector=true&projectId=xxxxxxxxx ### 第三步:内嵌水晶球页面至客户端 [#第三步内嵌水晶球页面至客户端] 在你的客户端开发平台添加代码,以 JSX 为例: ![通过 iframe 内嵌水晶球页面的 JSX 示例](https://web-cdn.agora.io/docs-files/1677211708693) 将[通话调查详情页面 URL](/zh-CN/realtime-media/usage-analytics/build/embed-and-maintain-data-service/embeded) 或[拼接的水晶球功能列表页面 URL](/zh-CN/realtime-media/usage-analytics/build/embed-and-maintain-data-service/embeded) 传入 `iframeUrl`,即可在客户端查看对应页面。 ## 常见问题 [#常见问题] Q: 为什么内嵌的页面是空白的? A: 浏览器会对网页进行安全识别。当你在网页中内嵌第三方页面时,部分浏览器会判定第三方页面不安全并将其拦截。解决方案如下: 1. 如果你的浏览器安装了广告屏蔽插件,你需要在插件中设置禁止过滤内嵌页面。 2. 如果你使用 Safari 浏览器,你需要进入**偏好设置** > **隐私** > **网站跟踪**,并取消勾选**阻止跨站跟踪**。