应用集成

探针集成

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

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

将以下代码复制到所有业务代码引入的script标签之前（如果是混合APP，还需要放在cordova.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 标记之前添加代码;

<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 (自定义日志内容) 处于同一元素； 比如：

  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 时，会以当前的时间戳来作为页面加载完成的时间。

// 手动上报的时间

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 属性；