SDK API

API 使用文档

简介

当您的项目按照正确的方式接入 FrontJS 之后，您可以使用 FrontJS API 动态调整 FrontJS 监控脚本的行为。 FrontJS Javascript 监控脚本（包含 Web 端 和 微信小程序 端版本）提供了通用的 API 调用方法，当使用我们提供的代码接入项目后可以使用以下方式调用 FrontJS API：

web 端

window.FrontJS.*

微信小程序

getApp().FrontJS.*

API 和功能概览

  • addUserData 添加用户自定义数据。
  • removeUserData 移除用户数据。
  • try 尝试执行某个方法 错误将会被捕获上报到 FrontJS；如果没有遇到错误则会返回被执行方法的返回值。
  • catch 上报一个错误到 FrontJS。
  • composedTry 返回一个基于 try API 的 复合函数
  • addEventListener 添加一个事件侦听器 (Web 端有效)
  • removeEventListener 移除一个事件侦听器 (Web 端有效)

addUserData

说明

动态的添加一条自定义数据，添加后用户数据会附在每一条上报到 FrontJS 的消息上，在查看错误信息流页面最底端的定义数据选项卡中可以看到。

参数与返回值

bool addUserData(string key, string value)

key 为自定义数据名字， value 为自定义数据的值，添加成功后会返回 true。

示例

web 端

// 同时上报 Session Storage 存储的用户观看视频的次数
window.FrontJS.addUserData('viewTimes', window.sessionStorage && window.sessionStorage.getItem('viewTimes'))

微信小程序

// 同时上报用户手机品牌
getApp().FrontJS.addUserData('cellphoneBrand', wx.getSystemInfoSync().brand)

removeUserData

说明

动态的删除一条自定义数据，删掉后数据将不再上报 FrontJS。

参数与返回值

bool removeUserData(string key)

key 为自定义数据名字且当 key 不存在时不会报错，删除成功后会返回 true。

示例

web 端

// 如果用户拒绝隐私条款 放弃收集敏感数据
if (rejected) {window.FrontJS.removeUserData('viewTimes')}

微信小程序

// 如果用户拒绝隐私条款 放弃收集敏感数据
if (rejected) {getApp().FrontJS.removeUserData('cellphoneBrand')}

try

说明

尝试执行一个方法，如果出现错误将错误上报 FrontJS ，如果没有错误返回被执行方法的返回值

参数与返回值

mixed try(function fn, object context[, mixed arg0[, mixed arg1 [..., argn]]])

fn 为尝试要执行的方法， context 为尝试执行次方法的上下文环境，arg1, arg2, ... , argn 为 fn 传入的参数，如果出现错误将错误上报 FrontJS 并返回 null；如果没有错误返回被执行方法的返回值

示例

web 端

// 在 localStorage 存储数据
function setUserValue (key, value) {
  return window.localStorage.setItem(key, values)
}

// 尝试在 localStorage 存储数据
window.FrontJS.try(setUserValue, this, ‘FrontJS’, ‘nice’)

微信小程序

// 除法运算
function division (operant0, operant1) {
  return operant0 / operant1
}

// 尝试进行除 0 运算
getApp().FrontJS.try(division, this, 1, 0)

catch

说明

将错误上报给 FrontJS，返回 null。

参数与返回值

void catch(mixed e)

e 可以是 字符串 数字 或者是 Javascript 捕获的错误对象；当 e 是错误对象时 FrontJS 会使用错误对象内的 stack trace 信息；若 e 是其它类型 FrontJS 将尝试自己产生 stack trace 信息，该方法返回值为 null。

示例

web 端

// 上报一条错误
window.FrontJS.catch('error found')

// 使用 Javascript 捕获的错误对象
try {
  window.undefinedFn()
} catch (e) {
  window.FrontJS.catch(e)
}

微信小程序

// 上报一条错误
getApp().FrontJS.catch('error found')

// 使用 Javascript 捕获的错误对象
try {
  wx.undefinedFn({})
} catch (e) {
  getApp().FrontJS.catch(e)
}

composedTry

说明

返回一个基于 try API 的复合函数

参数与返回值

function composedTry(function fn, object context)

fn 为尝试要执行的方法， context 为尝试执行次方法的上下文环境，返回一个基于 try API 的 复合函数。 例如

// 使用 try API
try(fn, context, arg0_0, arg0_1)
try(fn, context, arg1_0, arg1_1)
try(fn, context, arg2_0, arg2_1)
try(fn, context, arg3_0, arg3_1)

// 使用 composedTry API (等效代码)
let composed = composedTry(fn, context)
composed(arg0_0, arg0_1)
composed(arg1_0, arg1_1)
composed(arg2_0, arg2_1)
composed(arg3_0, arg3_1)

示例

web 端

// 除法运算
function division (operant0, operant1) {
  return operant0 / operant1
}

// 构造尝试方法
var composed = window.FrontJS.composedTry(division, this)

// 尝试进行除法运算
composed(4, 2)  // 返回 2
composed(2, 1)  // 返回 1
composed(1, 0)  // 返回 null 并上报一条错误给 FrontJS

微信小程序

// 除法运算
function division (operant0, operant1) {
  return operant0 / operant1
}

// 构造尝试方法
let composed = getApp().FrontJS.composedTry(division, this)

// 尝试进行除法运算
composed(4, 2)  // 返回 2
composed(2, 1)  // 返回 1
composed(1, 0)  // 返回 null 并上报一条错误给 FrontJS

addEventListener 添加一个事件侦听器 (Web 端有效)

说明

添加一个事件侦听器 (Web 端有效)

参数与返回值

function addEventListener(string eventType, function handler)

当产生与 eventType 相应的事件时执行 handler 方法, 返回 handler 的引用。

事件列表

事件名 说明 传入参数描述
enterpage 当页面 load 完成时触发; 如果配置中 optimisedForSPA 设置为 true 则触发单页面应用优化行为，此时路由跳转后或进入页面时触发此事件 传入一个对象。包含以下属性 type: 当前事件名, url: 当前页面 URL, referer: 当前页面的来源页, route: 当前页面路由 (设置 routeMapping 后生效), refererRoute: 当前页面的来源页路由 (设置 routeMapping 后生效)

示例

web 端

// 单页面应用内路由跳转时也能被 Google Analytics 记录
window.FrontJS.addEventListener('enterpage', function (e) {
  // use ga
  ga('set', 'page', e.url.split(window.location.host)[1]);
  ga('send', 'pageview');
  // use gtag
  gtag('config', 'TRACK_ID', { 'page_path': e.url.split(window.location.host)[1] });
})

removeEventListener 移除一个事件侦听器 (Web 端有效)

说明

移除一个事件侦听器 (Web 端有效)

参数与返回值

function removeEventListener(string eventType, function handler)

移除为 eventType 事件添加 handler 方法, 返回 handler 的引用。

示例

web 端

// 单页面应用内路由跳转时也能被 Google Analytics 记录 保留 handler 以方便后期移除
var handler = window.FrontJS.addEventListener('enterpage', function (e) {
  // use ga
  ga('set', 'page', e.url.split(window.location.host)[1]);
  ga('send', 'pageview');
  // use gtag
  gtag('config', 'TRACK_ID', { 'page_path': e.url.split(window.location.host)[1] });
})

// 撤销翻页面应用路由跳转 Google Analytics 记录
window.FrontJS.removeEventListener('enterpage', handler)