longan-sdk v0.2.36

v0.36

1.添加isSfApp配置，试用于丰声微应用

v0.32~v0.35

1.修复在部分网络和浏览器版本下，refeerer信息上报不完整的bug; 2.优化北斗报警信息，增强报警信息完整性。在上报报警信息时，添加alarm_msg。

v0.31

增加全局点击事件自动监听，可通过增加配置项 use_global_auto_listen: true 开启，默认不开启。

v0.29 ~ v0.30

主动dispatch错误也会对filter_error_msg的字段进行过滤。 性能上报window.unload改为window.onunload

v0.28 ~ v0.29

优化clientSize数据收集方式，

v0.26 ~ v0.27

修复hash路由的bug

v0.25

触发报警的WARNING_TAG将projectName和errorTag中短横线改为下划线形式。兼容北斗报警格式。

v0.24

优化longanTJS.js脚本。

V0.20.22~23

longanTJS 方法支持 -c/--config 参数传入 默认是 ‘tsconfig.json’ longanAddSchema 参数优化schemaNameSpace可不传 默认区json的$id

  interface IAddSchema {
    schemaNameSpace?: string;
    schemaJson: any;
  }

  interface ILonganValidate {
    validate: (params: IValidate) => any
  };

  /**
   * @description 加载jsonschema 并返回校验函数
   * @param schemaNameSpace 生成jsonschema.json 的id
   * @param schemaJson 生成的jsonschema
  */

  export function longanAddSchema(params: IAddSchema): ILonganValidate['validate'];

V0.20.21-beta 增加url参数

 longanValidate({
    instance: action.payload.data,
    targetSchema: 'IParams',
    url,
  });

V0.2.20 TS运行时校验更新brocken

• 提供方法 longanAddSchema
• 使用示例

  interface IAddSchema {
    schemaNameSpace: string;
    schemaJson: any;
  }

  interface ILonganValidate {
    validate: (params: IValidate) => any
  };

  /**
   * @description 加载jsonschema 并返回校验函数
   * @param schemaNameSpace 生成jsonschema.json 的id
   * @param schemaJson 生成的jsonschema
  */

  export function longanAddSchema(params: IAddSchema): ILonganValidate['validate'];

  const longanValidate = longanAddSchema({
    schemaNameSpace: 'OrderManage',
    schemaJson,
  });

 longanValidate({
    instance: action.payload.data,
    targetSchema: 'IParams',
  });

V0.2.17~19 升级内容

• 添加错误类型TSRunError
• TSRunError上报的错误信息 longan展示平台同步添加

V0.2.16 升级内容

• 添加方法 longanValidate 提供TS运行时的类型校验、有错我并主动上报

interface IValidate {
  schemaNameSpace: string;
  schemaJson: {};
  instance: any;
  targetSchema: string;
}
/**
 * 
 * @param {*} schemaNameSpace 生成的schemaJson 中的 $id 值
 * @param {*} schemaJson  生成的schemaJson
 * @param {*} instance 要校验的数据
 * @param {*} targetSchema 目标TSJSON
 */
function longanValidate(params: IValidate): any;

• 提供命令行命令 longanTJS 生成TS定义对应的json文件

  FILE_PATH: pattern 需要遍历生成json的ts文件路径 参数参考 glob 第一个参数
  DEFAULT_INCLUDE_FILES:  string 默认包含的一些全局TS定义的路劲 
  longanTJS FILE_PATH? DEFAULT_INCLUDE_FILES?

v0.2.15 升级内容

• 添加方法：dispatchWithoutRegister 直接上报埋点或报错

interface IParmWRegister {
  type: 'error' | 'event',
  data: Partial<ILonganConfig> & IDispatchParams & IDispatchError & {
    env?: ILonganConfig['env']
  }
}

/**
 * @description 直接上报埋点或报错
 * @param {IParmWRegister} params
 * @example 
 * dispatchWithoutRegister({
      type:'error',
      data: {
      project_name:'xxx',
      error_message:'xxx', 
      error_content:'xxx', 
     }
  })
 */
function dispatchWithoutRegister(params: IParmWRegister): void;

v0.2.14 升级内容

• 调整上报信息参数位置

v0.2.13 升级内容

• 上报添加error_tag字段

v0.2.12 升级内容

• 上报添加error_level字段
• 接入北斗报警

v0.2.11 升级内容

• 修复：errorType在一些情况下为undefind的问题
• 暴露4个方法：
• longanStart 对应longan.start
• longanDispatch 对应longan.dispatch
• longanDispatchError 对应longan.dispatchError
• longanUpdateConfig 对应longan.updateConfig

v0.2.10 升级内容

• 上报错误信息添加，error_level字段。用户可以自定义error_level错误等级。

• 修复：error接口上传字段为空时，统一传-1;

v0.2.8 & v2.0.9 升级内容

• 初始话配置优化,env配置项支持输入数组，用于处理单项目多域名的场景

    longan.start({
    project_name: 'bms', // 项目名称
    env: {
        uat: ['www.uat.com','xxxx','xxx3'], 
        online: ['www.uat.com','xxxx','xxx3'],
        develop: window.location.host
    },
    })

• 上报信息添加唯一值

v0.2.7 升级内容

• 修复错误类型上报不准确的问题

• 相同错误上报间隔改为10min

v0.2.3 & v0.2.5升级内容

• 完善typescript注释

v0.2.2升级内容

• 自动上报基础字段：client_size：宽*高

v0.1.9 v0.2.0升级内容

• 新增可选配置字段hashRoute，用于解决hash路由的流量统计问题，大数据平台同步中；
• 解决日志匹配问题；

v0.1.8升级内容

• 修复filter_fileds字段问题

使用方法

本教程通过最快捷的例子到完整的配置，来演示说明longan的基础配置和使用

1. 快速开始

下面是最简单的基础配置。引入longan-sdk后，执行longan.start方法就可以实现了上报基础信息，性能信息，错误上报的功能！

import longan from 'longan-sdk';	
longan.start({
    project_name: 'Cosmos', // 项目名称
    env: {
        uat: 'www.uat-Cosmos.com',
        online: 'www.online-Cosmos.com',
        develop: window.location.host
    },
})

需要注意的是，project_name和env字段是必填项。

project_name：

project_name将是你在longan数据展示平台查看自己项目的名称。你所有的信息收集将落到你配置的project_name名下。所以定好project_name后就不要再做更改！

env:

env是一个对象,其中uat,online,develop三个属性的值对应着项目运行时的location.host。

如果你online的实际host是www.online.com，却配置成www.online_2.com。那当项目发布上线后，longan判断实际location.host和配置的不同，将不会执行上报。

develop属性请配置开发时的location.host。longan会做出上报的动作，但上报信息不会真正的被收集。

2.基础功能

2.1基础配置

下面是一个完整的longan基础配置信息

longan.start或longanStart方法接受一个对象，用户注册基础信息。执行方法后longan就已经开启了上报功能

import longan from 'longan';
// 或者 import { longanStart } from 'longan-sdk';


longan.start({
  project_name: 'otms', // 项目名称
  env: {  
    uat: 'www.uat.com',
    online: 'www.online.com',
    develop: 'window.location.host'
  },
  loginUser: '01389450',
  filter_fields: ['position_name'], // 过滤掉不想上传的字段
  filter_confitions:['error'], // 过滤掉不想上传的功能
  additional_info: {name:'zcy',}, // 自定义信息
  hash_route: false, // 开启代表有hash路由流量统计
  filter_error_msg: [], // 过滤不想上报的错误。使用indexOf做匹配，请传errorMessage的关键字
 })

2.2 埋点

埋点可通过元素埋点和自定义埋点两个方法实现埋点信息上报

2.2.1 元素埋点

方法1：在目标元素上设置属性为longan前缀的id，实现事件埋点上传。

<Button id="longan-test-event">测试事件埋点</Button>

// 上报信息说明
埋点名称：'longan-test-event'
埋点描述：'测试事件埋点'
埋点类型：'点击'

方法2：给目标元素添加 data-longan 属性，可自定义上传文案。

<Button id="longan-test-event" data-longan="点击订单详情-确认">测试事件埋点</Button>

// 上报信息说明
埋点名称：'longan-test-event'
埋点描述：'点击订单详情-确认'
埋点类型：'点击'

2.2.2 自定义埋点。

longan.dispatch或longanDispatch方法接受一个对象参数。可以自定义上报埋点信息。

import longan from 'longan-sdk';
// 或者 import { longanDispatch } from 'longan-sdk';

longan.dispatch({
    event_name: 'new-work-order',
    event_desc: '新建工单',
    event_type: 'selfDefine',
});

// 上报信息说明
埋点名称：'new-work-order'
埋点描述：'新建工单'
埋点类型：'自定义'

2.3 更新配置

有些配置信息是异步获取的，例如用户登陆的信息。

longan.updateConfig或longanUpdateConfig接收一个对象参数，执行后，后续上报的基础信息将被修改。方法执行后会修改配置信息，覆盖基础配置的信息。

import longan from 'longan-sdk';
// 或者 import { longanUpdateConfig } from 'longan-sdk';

longan.updateConfig({
  loginUser: '01389450',
  project_name: 'otms', // 项目名称
  lid: 'logId',
  cookie: 'cookie',
});

2.4 错误上报

longan通过window.onerror全局监听错误，并且实时上报。

有些场景，无法通过onerror事件捕获，需要用户手动上报：例如errorBoundry捕获的错误等，异步请求状态码异常等。

longan.dispatchError或longanDispatchError接受一个对象参数，可以自定义上报错误信息。

import longan from 'longan-sdk';
import { longanDispatchError } from 'longan-sdk';

class ErrorBoundary extends React.Component<IProps, IState> {
  public static getDerivedStateFromError() {
    return { hasError: true };
  }

  constructor(props: IProps) {
    super(props);
    this.state = {
      hasError: false,
      // errorMessage: '',
      // errorInfo: '',
    };
    this.handleClick = this.handleClick.bind(this);
  }

  public componentDidCatch(error: any, info: any) {
    // 错误上报
    try {
      longanDispatchError({
        error_message: error.toString(),
        error_content: error.stack,
        error_level: '0',
        error_tag: 'error_boundary'
      });
    } catch (error) {
      console.log(error);
    }
  }

  // eslint-disable-next-line class-methods-use-this
  public handleClick() {
    window.location.reload();
  }

  public render() {
    if (this.state.hasError) {
      return (
        <ErrorBox>
          <Icon className='error_icon' type='exclamation-circle' theme='filled' />
          <h1>抱歉，系统暂时异常，请稍后再试</h1>
          <h1>
            您可以尝试
            <Button className='refresh_btn' type='primary' size='small' onClick={this.handleClick}>刷新</Button>
          </h1>
          <h1>若始终无法正常访问，请联系项目支持人员，感谢配合~</h1>
        </ErrorBox>
      );
    }

    return this.props.children;
  }
}

3. 扩展功能

3.1 运行时数据校验报警

typescript只能在开发环境对前端静态的数据类型做出校验。

一旦前端项目部署到生产环境，动态的数据没有办法去监控和校验类型是否异常。

longan提供了在运行时监控数据类型的功能，对错误的数据类型进行上报。

运行时数据校验需要两个步骤：

• 监控项目中的type.ts变化，自动生成jsonSchema文件
• 对比校验的对象和jsonSchema，异常数据上报

3.1.1 自动生成jsonSchema

提供命令行命令 longanTJS FILE_PATH DEFAULT_INCLUDE_FILES -c TSCONFIG

在package.json中添加如下命令：

// package.json
  "scripts": {
    "tjs": "longanTJS './src/pages/SettleOrder/types.ts' './base.d.ts'"
  },

执行npm run tjs，即在FILE_PATH平级的目录下生成一个jsonSchema.json的文件。

3.1.2 jsonSchema校验函数

提供工厂函数longanAddSchema或者longan.addSchma，执行后生成校验函数

执行返回的校验函数即可实现运行时校验报警。

校验函数需要三个参数

import schemaJson from './schemaJson.json'
import { longanAddSchema } from 'longan-sdk'
const validateFn = longanAddSchema({ schemaJson });

validateFn({
  'instance': fetchRes,
  "targetSchema": 'fetchResType',
  'url': '/get/list'
})

3.1.2 最佳实现方案

将生产jsonSchema文件的步骤接入ci/cd流程中，系统自动监控系统所有types.ts的变化，当type.ts文件有变化时，自动生成jsonSchema文件。

利用husky提供的git hooks。在pre-commit时，扫描暂存区是否有types.ts文件，如果有的话，利用lint-staged执行脚本自动生成jsonSchema文件。

// .lintstagedrc.js
module.exports = {
  "src/**/*.ts": (filenames) => {
    var regStr = /type.ts|types.ts/i;
    let res =  filenames.filter(item => regStr.test(item)).map((filename) => {
      let str = "longanTJS"+` "${filename}"`+ ' "./base.d.ts"';
      console.log("执行命令===>", str);
      return str;
    });
    console.log("生成json文件中。");
    return res;
  },
  // "*.{js,jsx,ts,tsx}": [
  //   "eslint --config .eslintrc.js"
  // ],
}

// package.json
{
    "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
}

3.2 直接上报埋点或报错

有些场景，比如工具或者sdk想接入longan，监控sdk本身的使用情况，或者埋点。

提供了一个方法fnDispatchWithoutRegister或者longan.dispatchWithoutRegister，可以直接上报埋点或报错，