# web-log-tracker

> send user actions and app performance

Latest version **3.0.2** (published 2019-02-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install web-log-tracker
pnpm add web-log-tracker
yarn add web-log-tracker
bun add web-log-tracker
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.2 |
| Published | 2019-02-21 |
| First published | 2018-05-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 363 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | zhangc13 |
| Maintainers | mysoft |
| Keywords | fast-tracker, mingyuanyun |

## Links

- npm: https://www.npmjs.com/package/web-log-tracker
- Repository: git@gitlab.mypaas.com.cn:fast/fast-tracker
- npm.io page: https://npm.io/package/web-log-tracker

## Recent versions

- 3.0.2 (latest) — 2019-02-21
- 1.0.2 — 2018-05-09
- 1.0.1 — 2018-05-09
- 1.0.0 — 2018-05-09

## README

## 应用集成

### 探针集成

- 预先配置，通过 CDN 引入自动创建探针
- 通过 CDN 引入后手动创建探针


#### 预先配置 引入后自动创建探针

> 将以下代码复制到所有业务代码引入的script标签之前（如果是混合APP，还需要放在cordova.js引入之后）

````js
<script>!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={"app_code":"应用编码XXX","product_code":"产品编码XXX"};var n=b.createElement("script");var tag=b.getElementsByTagName("script")[0];n.async=1;n.src=d;tag.parentNode.insertBefore(n,tag);})(window,document,"https://mic-open.mypaas.com.cn/web-log-tracker/v2/myWebLogTracker.min.js","__myWebLogTracker__");</script>
````

以上代码进行了以下两项操作：

1. 创建了一个 script 元素，并从 https://mic-open.mypaas.com.cn/web-log-tracker/v2/myWebLogTracker.min.js 异步下载 myWebLogTracker JavaScript 库；

2. 根据配置初始化全局 `__myWebLogTracker__` 探针对象，后续可以通过该对象调用相应的 API;

> 该代码已经根据配置创建探针 `__myWebLogTracker__` 全局对象，不需要重复创建；除app_code和product_code之外，还可以继续添加更多配置参数（详见探针配置）


#### 手动引入/创建探针

- CDN 
应该在 `head` 标记顶部附近以及任何其他 JavaScript 或 css 标记之前添加代码;
````js
<script src='https://mic-open.mypaas.com.cn/web-log-tracker/v2/myWebLogTracker.min.js'></script>
````

该脚本会在全局导出一个 `myWebLogTracker` 函数，可以通过该函数创建探针对象；

> script 脚本不要异步加载，否则脚本还未加载完成就实例化探针会导致 myWebLogTracker 未定义错误


引入脚本后，可以手动创建探针，所有配置都可以根据环境或其他条件动态生成；

> 混合应用请确保创建探针代码添加在 `cordova` 脚本之后，探针需要根据 `cordova` 对象来确认是否为混合应用；

````
// 创建配置对象，详细配置参考『探针配置』
const options = {
  product_code: '产品编码XXX',
  app_code: '应用编码XXX',
  disabled: process.env.NODE_ENV === 'production' ? false : true,
};

// 创建探针
const tracker = myWebLogTracker(options)
````

探针创建完成后，相应的数据收集和日志上报会自动处理；


### 探针配置

探针的配置选项是在探针初始化时以参数的方式传递的，同时也提供相应的 API 动态的修改探针的配置。

#### 配置选项

| 属性 | 类型 | 描述 | 是否必填 | 默认值|
| --- | --- | --- | --- | --- |
| product_code | string | 产品编码，用于隔离不同产品上报的数据 只能由小写英文字符, 下划线和数字组成 | 是 |  |
| app_code | string | 产品应用编码，用于隔离不同应用上报的数据 只能由小写英文字符, 下划线和数字组成 | 是 |  |
| tenant_code | string | SaaS应用中的租户编码 | 否 |  |
| user_account | string | 真实用户标识 | 否 |  |
| is_spa | boolean | 是否为单页应用功能 | 否 | true |
| page_interval | int | 检测页面停留时间间隔(单位：ms)，配置>0，则视为开启 | 否 | 1800000 |
| disable_event_track | boolean | 禁用标准点击事件上报 | 否 | false |
| disable_api_hook | boolean | 禁用应用内API请求上报 | 否 | false |
| disable_error_track | boolean | 禁用全局JS错误拦截 | 否 | false |
| disable_report_position | boolean | 禁用位置上报(只针对于混合应用) | 否 | false |
| manual_report_page_load | boolean | 是否手动上报页面加载时间, 如果设置为 true, 则需要在页面加载完成后调用 reportLoaded API 上报 | 否 | false |
| api_ignore_urls | array | 需要忽略上报API请求的域名，API请求上报开启时有效，支持正则表达式 | 否 | |
| api_property_cb | function | 修正 API 事件上报中 api 属性(api 地址)，参数为 API 地址，返回值为字符串 | 否 | null |
| collect_tags | string/array | 定义需要手机事件的标签名称，如：['a','button']；默认为所有标签都收集 | 否 | 'all' |
| collect_filter | function | 自定义元素过滤。函数接收事件源参数，返回boolean | 否 |  |
| log_content_attribute | string | 申明式日志属性名称，如:```<a href="#" data-log="日志内容"></a>``` | 否 | data-log |
| log_event_attribute | string | 自定义日志类型收集属性，如:```<button data-event="提交报告"></button>```（如需要与log_content_attribute同时使用，则必须处于同一元素） | 否 | data-event |
| route_title_maps | object | 自定义页面 Title map，键为需要自定义页面 title 的路径(使用正则表达式匹配)，值为上报的 Title | 否 | null |
| debug | boolean | 是否开启调试模式；开启后则将日志输入到控制台 | 否 | false |
| disabled | boolean | 是否禁用全部上报 | 否 | false |


> log_event_attribute (自定义日志事件类型名称属性) 必须和期望得到的 log_content_attribute (自定义日志内容) 处于同一元素；
> 比如：

````js
  options = {
     log_event_attribute: 'data-custom-event',
     log_content_attribute: 'data-custom-log',
  };
  
  // html 中
  <a data-custom-event='添加到购物车' data-custome-log='橘子' href='#'>橘子</a>
````


#### 注册SaaS租户编码与真实用户标识

SaaS 的租户编码和真实用户标识一般需要用户登录后动态配置，探针对象提供了 `registUser` API 注册租户编码和真实用户标识。

- WebLogTracker.registUser({ [key: 'tenant_code' | 'user_account']: string })

registUser 接收一个配置对象，代表需要注册的租户编码和真实用户标识；

````
// 可以在登录后注册

login().then(() => {
  // 使用天眼平台创建的探针对象为 __myWebLogTracker__，手动创建的探针对象调用相应的对象即可
  window.__myWebLogTracker__.registUser({
    tenant_code: 'SaaS应用租户编码',
    user_account: '真实用户标识'
  });
});
````




#### 动态修改探针配置

探针创建完成后，有时需要动态修改探针的配置，可以使用探针对象的 `modifyConfig` API 动态修改探针的配置。

- WebLogTracker.modifyConfig({ [key: string]: string | boolean | int | array })

modifyConfig 接收一个配置对象，代表需要修改的探针配置。

````
// 使用天眼平台创建的探针对象为 __myWebLogTracker__，手动创建的探针对象调用相应的对象即可

window.__myWebLogTracker__.modifyConfig({
  disabled: true,
});
````

可以动态修改的配置明细如下（具体含义参考上方的配置选项）：

- page_interval,
- disable_event_track,
- disable_api_hook,
- disable_error_track,
- collect_tags,
- collect_filter,
- log_content_attribute,
- log_event_attribute,
- api_ignore_urls,
- disabled

### 主动上报日志和错误

探针在实例化后，会自动上报一些事件用来收集相应的数据，你也可以在需要的时候手动上报日志和错误事件，探针提供两个接口用于手动上报：`report` 以及 `reportError`。

- WebLogTracker.report(eventName, content)

report 接收两个参数：

eventName: 自定义事件名称，

content: 自定义事件内容对象，由于探针会自动获取对应的基本信息(page 信息, vendor 信息 etc.），只需要把对应的事件内容提供到 `log` 键即可

````
// 用户下单后发送下单事件

// 使用天眼平台创建的探针对象为 __myWebLogTracker__，手动创建的探针对象调用相应的对象即可
window.__myWebLogTracker__.report('用户下单', {
  log: 'PO123456789', // 自定义内容
});
````

- WebLogTracker.reportError(content)

reportError 实际上是 report('error', content) 的简便写法，直接上报对应的错误消息到 `error` 事件；

````
// 使用天眼平台创建的探针对象为 __myWebLogTracker__，手动创建的探针对象调用相应的对象即可
window.__myWebLogTracker__.reportError('用户下单', {
  log: `Error Message: ${message}, file: ${filename}, line: ${lineNumber}` // 自定义错误消息内容
});
````

### 手动上报页面加载时间

探针自动收集的页面加载时间来源于 `performance` 对象，对于混合 APP 或一些复杂的异步加载页面来说，通过 `performance` 获取的页面加载时间不太准确，因此提供一个手动上报页面加载时间的 API.

- WebLogTracker.reportLoaded()

当调用 `reportLoaded` 时，会以当前的时间戳来作为页面加载完成的时间。

````js
// 手动上报的时间

document.addEventListener('deviceready', () => {
  // some code...

  window.__myWebLogTracker__.reportLoaded();
});

````

### 配置自定义页面 Title

如果需要自定义上报数据的 title 属性，需要在探针实例化提供 `route_title_maps` 配置。 `route_title_maps` 接收一个简单的 Javascript 对象，键名为页面的路径(不包含 host)，键值为对应的 title。比如:

````
{
  '/login': '登录',
  '/products': '产品',
};
````

路径的匹配使用的是正则表达式测试，如果当前页面路径与某个配置的路径匹配成功，则会所用对应的 title 作为上报数据的 title 属性，如果没有匹配项，默认使用 `document.title` 属性；

---
_Source: https://npm.io/package/web-log-tracker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._