# 剑鱼埋点相关问题

::: tip

**2023/12/7**
* 新增埋点信息剑鱼自存储

**2023/6/7**
* 更新山川BI项目集成代码示例
* 移除文档AES加密相关内容

**2023/5/29**
* 更新山川BI项目集成说明及代码示例

* **2023/5/25**
* 新增山川BI项目集成说明及代码示例

**2023/3/11**
* 更新埋点集成方式
* 更新埋点字段

如需参照旧文档进行详细对比，[点这里](./index-old.html)
:::



## 埋点用途

目前项目中存在两个统计方式：**百度统计**、**荟聚统计**。

两者的区别：
* 百度统计主要用于延续之前的分析，可分析网站流量等数据指标。
* 荟聚统计用于统计**页面事件、页面访问**，以及运营用于营销活动、页面的使用。

## 如何在新项目中集成百度统计、荟聚统计

1. 如下加载对应**两**个JS文件引用

2. 修改对应环境路由，需确保对应环境存在 **common-module** 资源文件映射，能正确访问。

#### 代码示例
```
<!--S 【可选项】加载jquery获得更好的事件属性支持 -->
<script src="https://cdn-common.jianyu360.com/cdn/lib/jquery/3.5.1/jquery.min.js"></script>
<!--E 【可选项】加载jquery获得更好的事件属性支持 -->

<!--S 加载百度统计及剑鱼自定义埋点 -->
<script src="https://www.jianyu360.cn/common-module/public/head.js?v=版本号"></script>
<!--E 加载百度统计及剑鱼自定义埋点 -->
```

## 如何在山川BI项目中集成百度统计、荟聚统计

1. 在对应项目**资源**菜单，`public > hooks > custom.ts` 中加入下面示例代码。
2. 检查BI开发模式域名是否正确，当前为 `bidevtest` 或  `onlinesuccbi`

#### 代码示例
```

import "jquery";

// 剑鱼相关资源版本号，用于版本升级刷新缓存
const JyAssetsVersion = 120

// 解决页面阻塞问题
async function initIframeSupport() {
	const tempL = define.amd
	define.amd = false
	try {
		await import('https://www.jianyu360.cn/common-module/js/JianyuIframe.umd.min.js')
		new JianyuIframe.easyInjectIframePage({
			debug: true
		})
	} catch (e) {
		console.warn('t', e)
	}
	define.amd = tempL
}


// 剑鱼相关埋点注入
async function initTrackSupport() {
	// 判断是否开发环境
	const inDevStatus = location.origin.indexOf('bidevtest') !== -1 || location.origin.indexOf('onlinesuccbi') !== -1
	if (inDevStatus) return

	async function injectTrack() {
		if (document.readyState !== 'complete') return
		try {
			await import(location.origin + '/common-module/track/j-track.min.js?v=' + JyAssetsVersion)
		} catch (e) {
			console.warn('t', e)
		}
	}

	document.addEventListener('readystatechange', injectTrack);
	await injectTrack()
}

try {
	initIframeSupport()
	initTrackSupport()
} catch (e) {
	console.warn('track', e)
}
```
#### 操作示意图
![img_5.png](img_5.png)


## 如何验证是否成功集成

1. 访问页面
2. 打开开发者工具
3. 切换到 Network 面板并筛选或清空
4. 对页面元素进行点击操作
5. 验证是否新增请求及请求中内容是否与点击内容一致


#### 操作示意图
![img_3.png](img_3.png)

## 如何上传自定义埋点数据

集成SDK后，可以通过 `window.__EasyJTrack.addTrack` 函数自定义上报，默认包含页面基础字段，可覆盖。

#### 代码示例
```
window.__EasyJTrack.addTrack('自定义上报的埋点标识', {
    custom: '自定义上报的字段'
})
```

#### 效果图
![img_4.png](img_4.png)


## 荟聚统计相关

### 页面访问数据埋点

通过 JTrack SDK 针对荟聚平台原有的 open_page 字段进行了扩展，跟随每次进入页面的上报事件一同上报。

主要用途：
* 绑定用户信息，用于荟聚分析平台能使用 c_uid 进行对应关联。
* 更新替换页面自定义属性，如页面名称、页面Id，使其能在分析时进行便捷使用。

#### 使用示例
![使用示例](/images/track-hj-open-page.png)

#### 页面名称、ID定义数据

* 该数据由运营、研发、产品共同制定并纳入质量部门发版SOP流程进行维护。
* 可通过WPS文档、或企业微信文档进行查阅。 [页面信息表](https://www.kdocs.cn/l/cqmIGa3HPkf2)

![img.png](img.png)

表格包含以下字段：
* 页面URL (必填项)
* 页面功能简述
* 页面名称
* 产品名称
* 页面ID

转换后的JSON文件格式

```
[
  {
    "页面URL": "/page_workDesktop/work-bench/app/big/workspace/dashboard",
    "页面功能简述": "PC 工作桌面-首页",
    "产品名称": "",
    "页面名称": "工作桌面-首页",
    "页面ID": ""
  },
  {
    "页面URL": "/page_workDesktop/work-bench/page?link=https%3A%2F%2Fjybx-webtest.jydev.jianyu360.com%2Fjylab%2Fsupsearch%2Findex.html",
    "页面功能简述": "招招标采购公告、超前项目搜索",
    "产品名称": "",
    "页面名称": "信息搜索-招标采购搜索",
    "页面ID": ""
  }
]
```

::: warning
每次更新表格需同步维护更新对应的JSON文件，移动端对应 mobile.json，PC端对应 pc.json
:::


### 通用页面访问信息埋点

通过 head.js 注入 JTrack SDK，用于收集页面访问数据，并调用荟聚上报函数。

#### 上报自定义字段明细

|      字段       |  描述   |                        规则                         |
|:-------------:|:-----:|:-------------------------------------------------:|
|  c_platform   |  平台   |        PC、H5、APP、WeChatWeb、WeChatMP、Other         |
|   c_pageid    | 页面ID  |                  映射表中定义的**页面ID**                  |
|     c_url     | 页面URL |                       href                        |
|  c_pagename   | 页面名称  |                  映射表中定义的**页面名称**                  |
| c_productname | 产品名称  |                  映射表中定义的**产品名称**                  |
|    c_desc     | 页面功能简述  |                 映射表中定义的**页面功能简述**                 |
|    c_title    | 页面真实title(备用)  |                  document.title                   |

::: warning
这里需要注意， 剑鱼平台PC端目前可能存在同一页面，在工作桌面嵌入时，与独立访问时出现两个 c_url
:::

#### 荟聚平台分析使用示例
1. 访问登录荟聚分析平台
2. 选择进入 **分析 - 常用分析 - 行为分析**
3. 分析行为中，选择 **客户自定义事件 - 通用页面访问信息**
4. 限制事件属性来分析指定场景的页面访问数据
5. 选择分析维度、分析指标、分析时间等筛选条件

![img_1.png](img_1.png)


### 通用点击事件埋点

通过 head.js 注入 JTrack SDK，用于收集后端渲染Go项目、前后端分离Vue项目的点击事件信息，并调用荟聚上报函数。


#### 上报自定义字段明细

|      字段       |  描述   |                        规则                        |
|:-------------:|:-----:|:------------------------------------------------:|
|  c_platform   |  平台   |        PC、H5、APP、WeChatWeb、WeChatMP、Other        |
|   c_pageid    | 页面ID  | 映射表中定义的**页面ID** 或者  location.pathname |
|     c_url     | 页面URL |                       href                       |
|  c_pagename   | 页面名称  |        映射表中定义的**页面名称** 或者 document.title         |
| c_productname | 产品名称  |                 映射表中定义的**产品名称**                  |
|    c_desc     | 页面功能简述  |                映射表中定义的**页面功能简述**                 |
|    c_title    | 页面真实title(备用)  |                  document.title                  |
| c_breakername | 断点名称  | 点击元素或者父级元素的 innerText 或 name 或 title，最大字符长度为 15  |
|  c_breakerid  | 断点ID  |                    点击元素 xpath                    |


#### 荟聚平台分析使用示例
1. 访问登录荟聚分析平台
2. 选择进入 **分析 - 常用分析 - 行为分析**
3. 分析行为中，选择 **客户自定义事件 - 剑鱼通用点击事件（勿删）**
4. 限制事件属性来分析指定场景的点击数据
5. 选择分析维度、分析指标、分析时间等筛选条件

##### 👇下面示例分析 ** 再次购买 ** 按钮的点击情况
1. 限制事件属性中，设置条件为：**断点名称** 包含 **再次购买**，与上报信息中 c_breakername 一致
2. 分析维度中，选择根据 平台 / 页面url 分析，与上报信息中 c_platform、c_url 一致
   ![荟聚示例](/images/track-hj.png)


> 如需了解其他技术细节、加解密密钥请前往 [jy-track](http://192.168.3.207:8080/zhangyuhan/jy-track)

> 也可以使用埋点反查询工具，寻找查看对应关系

### 通用点击事件-埋点反查询工具
![埋点反查询工具](/images/track-tools.png)

::: warning
**2023/3/11**
* SDK 新增的通用页面访问统计暂不支持查询
* SDK 新增的自定义参数暂不支持查询
  :::

#### 下载安装
1. 访问企业微信 - 微盘 - 项目文件 - 埋点查询工具
2. 根据自己操作系统下载不同的平台(Windows/MAC)的安装包