内嵌水晶球数据

水晶球内嵌功能可以在你的内部系统中快速嵌入水晶球功能，仅需少量开发成本即可实现。具体包括：

• 直接在内部系统中查看水晶球功能列表页面，例如通话调查列表页面。
• 直接在内部系统中查看通话调查详情页面，包含通话体验质量页面和端到端详情页面。
• 通过设置水晶球内嵌页面属性，在内部系统中实现你的业务功能。例如，结合内部系统的分级权限配置，为不同等级的员工设置不同水晶球内嵌页面的访问权限。

注意

目前支持内嵌的水晶球功能包括通话调查、数据洞察、实时监控和告警通知。

前提条件

使用水晶球内嵌功能前，你需要完成如下准备：

• 已有安全可靠且有账号控制权限的内部系统。
• 已订阅水晶球套餐包，且订阅的套餐包支持内嵌你需要的水晶球功能。

使用步骤

访问内嵌设置

按以下步骤完成访问内嵌设置：

1. 登录控制台，点击左侧菜单栏中的水晶球。

2. 在页面左上方的下拉菜单中选择你要查看的项目。

3. 点击页面右上角的头像，在下拉菜单中点击内嵌设置。

第一步：获取水晶球功能页面 URL

选择你想内嵌的水晶球功能后，下方的示例代码（以 Node.js 为例）将实时更新，参考示例代码在服务端发送 HTTP 请求以获取水晶球功能页面的 URL。

获取内嵌专用 ID 和密钥

调用本文介绍的水晶球内嵌 RESTful API 前，你需要在 clientId 和 clientSecret 参数中填入水晶球内嵌专用的客户 ID 和客户证书。该客户 ID 和客户密钥与水晶球 RESTful API 认证时使用的客户 ID 和客户密钥不同，你需要前往申请。

• clientId: 客户 ID
• clientSecret: 客户密钥

获取水晶球功能列表页面 URL

调用此方法，你可以获取水晶球功能列表页 URL，例如通话调查页面 URL。

数据格式 请求和响应的格式为 JSON。

基本信息

请求基本信息	描述
方法	POST
请求 URL	https://analytics-lab.agora.io/api/getEmbedLocation

请求包体参数

参数	描述
feature	内嵌的水晶球功能。支持设为以下值： callSearch：通话调查功能。 realtimeMonitoring：实时监控功能。 dataInsightsPlus：数据洞察 Plus。 dataInsightUsage：数据洞察-用量概览功能。 dataInsightQuality：数据洞察-质量概览功能。

请求示例

以内嵌通话调查功能为例：

HTTP

{
"feature": "callSearch"
}

响应参数

参数	描述
token	动态密钥。有效期为 2 小时，你需要每 2 小时更新动态密钥。

响应示例

HTTP

https://analytics-lab.agora.io/analytics/call/search?token=xxxxxxxxxxxxxxxxxxxxxx

获取通话调查详情页面 URL

将以下参数与 URL 拼接，即可获取通话调查详情页面 URL：

URL: https://analytics-lab.agora.io/api/analytics/research

参数	描述
token	动态密钥，从上一步获取的水晶球功能列表 URL 中获得。
cname	频道名称。 Note 需填写正确的频道名称。如果频道名称不存在，你会获取通话搜索页面，但搜索结果为空。
fromUid	（选填）发送端用户 ID。
toUid	（选填）接收端用户 ID。
fromTs	（选填）查询开始时间，Unix 时间戳 （秒）。设置后，你可以查询该时间点（包含）之后的通话。
toTs	（选填）查询结束时间，Unix 时间戳 （秒）。设置后，你可以查询该时间点（包含）之前的通话。

注意

• 根据查询参数的设置，你会获取以下两种通话详情页面：
  • 如果只填写了正确的 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 至客户端。详见内嵌水晶球页面至客户端。

第二步：添加属性至水晶球功能列表页面 URL

在页面属性菜单，你可以设置水晶球内嵌页面的如下属性：

• 语言：选择中文或 English。
• 时区：选择本地时区或 UTC 时区。
• 项目权限：选择任意项目或指定项目。
  • 任意项目：员工可访问该账号下开通了对应功能的任意项目。
  • 指定项目：员工仅可访问该账号下开通了对应功能的指定项目。选择指定项目后，你需要在下方默认项目列表中指定一个可访问的项目。
• 默认项目：声网默认将当前项目设置为内嵌页面的默认项目，你可以修改默认项目。

设置页面属性时，下图中代码会实时更新。

注意

内嵌设置无法保存，页面刷新后会恢复默认设置。完成设置后，请及时拷贝代码。

页面属性代码中包含如下参数：

参数	描述
locale	语言。 zh: 中文。 en: 英文。
timezone	时区。 UTC: UTC 时区。 Local: 本地时区。
showProjectSelector	是否在页面上显示项目选择下拉框： true: 显示。 false: 不显示。
projectId	（选填）项目 ID。 Note 只有对指定项目设置访问权限时需要填写此字段。

将上述参数与之前获取的水晶球功能列表页面 URL 拼接，即可获取含页面属性的水晶球功能列表页面 URL。拼接示例：https://analytics-lab.agora.io/analytics/call/search?token=xxxxxxxxxxxxxxxxxxxxxx&locale=zh&timezone=UTC&showProjectSelector=true&projectId=xxxxxxxxx

第三步：内嵌水晶球页面至客户端

在你的客户端开发平台添加代码，以 JSX 为例：

将通话调查详情页面 URL 或拼接的水晶球功能列表页面 URL 传入 iframeUrl，即可在客户端查看对应页面。

常见问题

Q: 为什么内嵌的页面是空白的？

A: 浏览器会对网页进行安全识别。当你在网页中内嵌第三方页面时，部分浏览器会判定第三方页面不安全并将其拦截。解决方案如下：

1. 如果你的浏览器安装了广告屏蔽插件，你需要在插件中设置禁止过滤内嵌页面。
2. 如果你使用 Safari 浏览器，你需要进入偏好设置 > 隐私 > 网站跟踪，并取消勾选阻止跨站跟踪。