水晶球的水晶球内嵌功能帮助你快速在你的内部系统中嵌入水晶球功能,仅需少量开发成本即可实现以下功能:

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

前提条件

  1. 已有安全可靠且有账号控制权限的内部系统。
  2. 项目中已开启需内嵌的功能,例如通话调查。
  3. 联系 sales@agora.io 为你的项目开通水晶球内嵌功能,并获取水晶球内嵌的客户 ID 与客户密钥。
  • 水晶球内嵌的客户 ID 与客户密钥与水晶球 RESTful API 的客户 ID 和客户证书不同。
  • 为保证数据安全,使用该功能期间,开发者需配合声网在约定时间内完成产品的改造或升级。
  • 使用步骤

    第一步:访问内嵌设置

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

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

    3. 进入需内嵌的功能页面,例如通话调查。

    4. 点击页面右侧内嵌悬浮按钮,访问内嵌设置

    第二步:获取水晶球功能页面 URL

    参考下图代码,在服务端发送 HTTP 请求获取水晶球功能页面的 URL。

    1. HTTP 基本认证

    发送请求时,你需要通过 clientIdclientSecret 获取 Authorization 字段并填入 HTTP 请求头部。

    • clientId: 客户 ID
    • clientSecret: 客户密钥
    水晶球内嵌的客户 ID 与客户密钥与水晶球 RESTful API 的客户 ID 和客户证书不同,你需要联系 sales@agora.io 获取水晶球内嵌的客户 ID 与客户密钥。

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

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

    基本信息

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

    请求参数

    包体参数

    参数 描述
    feature 内嵌的水晶球功能。当前仅支持 callSearch,即通话调查功能。

    请求示例

    {
    "feature": "callSearch"
    }

    响应参数

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

    响应示例

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

    3. 获取通话调查详情页面 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,你会获取通话体验质量页面。
      • 如果填写了正确的 cnamefromUidtoUid,你会获取通话的端到端详情页面。
  • 如果多个通话有相同的 cname,获取的是通话开始时间距离当前时刻最近的通话详情页面。
  • 如果不设置 fromTstoTs,则默认显示最近 14 天的搜索结果。
  • 拼接示例如下:

    https://analytics-lab.agora.io/api/analytics/research?token=xxxxxxxxxxxxxxxxxxxxxx&cname=xxxxxxxxxxxxxxxxxxxxxxxx&fromUid=xxxxxx&toUid=xxxxxx

    拼接完成后,你需要内嵌通话调查详情页面 URL 至客户端。详见内嵌水晶球页面至客户端

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

    页面属性菜单,你可以设置水晶球内嵌页面的如下属性:

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

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

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

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

    参数 描述
    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

    第四步:内嵌水晶球页面至客户端

    选择客户端开发平台,复制下图代码片段至客户端。

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