本文介绍将其他类别的小程序接入 ARMS 前端监控的基础使用方法、通用配置、API 方法和进阶场景。本文适用于除钉钉 E 应用、支付宝小程序和微信小程序之外的各类符合标准规范的小程序。

基础使用方法

基础方法包含引入 npm 包并初始化、上报,和设置安全域名这三个步骤。

  1. 引入 npm 包并初始化。

    1. 在小程序的项目中引入 alife-logger npm 包,以便使用该模块来上报日志。

      npm install alife-logger
      							
    2. 将以下内容添加至 /utils 目录下的 monitor.js 文件中以完成初始化。

      说明 您可以自定义 JS 文件的名称和存放位置。
      import MiniProgramLogger from 'alife-logger/miniprogram';
      const Monitor = MiniProgramLogger.init({
          pid: 'xxx',
          uid: 'userxxx', // 设置用户uid,用于统计UV信息。
          region: 'cn', // 指定应用部署的地域:中国设为cn,中国以外地域设为sg。默认值为cn。
          // 基础小程序监控需要手动传入RPC。请按照实际业务写实现方法,以下示例为钉钉E应用中的调用方式。
          sendRequest: (url, resData) => {
                // 此部分由业务方配置,支持Get/Post上报。
              // demo in dingding
              var method = 'GET';
              var data;
              if (resData) {
                  method = 'POST';
                  data = JSON.stringify(resData);
              }
              dd.httpRequest({
                  url: url,
                  method: method,
                  data: data,
                  fail: function (error) {
                      //...
                  }
              });
          },
           // 手动传入获取当前页面路径的方法。请按照实际业务写实现方法,以下示例为钉钉E应用中的调用方式。
           getCurrentPage: () => {
                // 此部分由业务方配置。
              if (typeof getCurrentPages !== 'undefined' && typeof getCurrentPages === 'function') {
                  var pages = (getCurrentPages() || []);
                  var pageLength = pages.length;
                  var currPage = pages[pageLength - 1];
                  return (currPage && currPage.route) || null;
              }
           }
      });
      
      export default Monitor;
      							
      说明 关于参数的详细配置,请参考通用配置
  2. 上报日志。

    1. 在 app.js 中,使用以下两种方法之一上报日志。

      • 使用 Monitor.hookApp(options) 方法静默捕获 Error 类日志。其中的 options 即为 App 层相应的 Object 配置。

        import Monitor from '/utils/monitor';
        
            App(Monitor.hookApp({
              onError(err) {
                console.log('进入onError:', err);
              },
              onLaunch() {
                console.log('进入onLaunch');
              }
        
              onShow(options) {
              },
              onHide() {
              }
            }));
        
        									
      • 使用 Monitor.error(err) 方法手动上报 Error 类日志。

        import Monitor from '/utils/monitor';
        
            App({
              onError(err) {
                  Monitor.error(err);
                console.log('进入onError:', err);
              },
              onLaunch() {
                console.log('进入onLaunch');
              }
        
              onShow(options) {
              },
              onHide() {
              }
            });
        									
    2. 在 page 的 JS 文件 中,使用以下两种方法之一上报日志。

      • 使用 Monitor.hookPage(options) 方法静默上报 PV、Health 数据。

        说明 此方法不支持静默上报 API 请求。
        import Monitor from '/utils/monitor';
        
            Page(Monitor.hookPage({
               data: {},
                onLoad(query) {
                },
                onReady() {
                    // 页面加载完成
                },
                onShow() {
        
                },
                onLoad(query) {
        
                },
                onHide() {
        
                },
                onUnload() {
        
                },
                onTitleClick() {
                    /**
                     * 统计打点数据,自定义打点。
                     * @desc
                     */
                    Monitor.sum('titleClick');
                }       
            }));
        									
      • 调用 API 方法主动打点。

        说明 关于 API 方法的详细信息,请参考 API 方法
        import Monitor from './util/monitor';
        
            Page({
               data: {},
                onShow() {
                    Monitor.pageShow();
                },
                onHide() {
                    Monitor.pageHide();
                },
                onUnload() {
                    Monitor.pageHide();
                },
                onTitleClick() {
                    /**
                     * 统计打点数据,自定义打点。
                     * @desc
                     */
                    Monitor.sum('titleClick');
                }       
            });
        									
  3. 设置安全域名。

    • 如果 region 设为 cn,则将 https://arms-retcode.aliyuncs.com 添加到合法域名。

    • 如果 region 设为 sg,则将 https://arms-retcode-sg.aliyuncs.com 添加到合法域名。

通用配置

通用的初始化参数如下表所示。

参数 类型 描述 是否必需 默认值
pid String 站点 ID。 null
uid String 用户 ID,用于统计 UV。 Storage 设置
tag String 传入的标记。每条日志都会携带该标记。
disabled Boolean 是否禁用日志上报功能。 false
sample Integer 日志采样率,值为 1、10 或 100。性能和成功 API 日志按照 1/sample 的比例上报。 1
disableHook Boolean 是否禁用 my.httpRequest 请求监听。默认会监听并用于上报 API 调用成功率。 false
sendRequest Function 发送日志的方法。如果不配置,则无法发送日志。
getCurrentPage Function 获取当前页面的方法。

sendRequest 参数说明

此参数用于发送日志,需要支持 Get/Post 方法。上报 Error 类的日志时会采用 Post 上报方式。方法的参数说明如下:

参数 类型 描述
url String 日志上报的地址。
resData Object 需要 Post 上报的内容。如果该参数有值则需要用 Post 方法上报,否则用 Get 方法上报。

sendRequest 配置示例

sendRequest: (url, resData) => {
          // 此部分由业务方配置,支持Get/Post上报。
        // demo in dingding
        var method = 'GET';
        var data;
        if (resData) {
            method = 'POST';
            data = JSON.stringify(resData);
        }
        dd.httpRequest({
            url: url,
            method: method,
            data: data,
            fail: function (error) {
                //...
            }
        });
    }
			

API 方法

方法 参数 备注
hookApp {} 请传入原有的 App 参数。可用于在 App 的生命周期中自动打点。
hookPage {} 请传入原有的 Page 参数。可用于在 Page 的生命周期中自动打点。
setCommonInfo {[key: string]: string;} 设置日志基础字段,可用于灰度发布等场景。
setConfig {[key: string]: string;} 设置 config 字段。
pageShow {} Page Show 打点,发送 PV 数据。
pageHide {} Page Hide 打点,发送 Health 数据。
error String/Object 错误日志打点。
api String API 类日志上报。
sum/avg String 自定义求和、求均值日志上报。
说明 小程序监控项目如需使用 hookApp、hookPage 嵌入生命周期打点,必须符合标准小程序关于 App 和 Page 的规范,即 App 层有 onError,Page 层有 onShowonHideonUnload。使用方法示例请参考基础使用方法

大部分日志上报 API 与 Web 端监控 SDK 一致,其他 API 的使用方法如下:

  • 如需发送当前页面的 PV 数据,则在 Page 的 onShow 方法下调用 pageShow() 方法。

    说明 请勿与 hookPage() 方法同时使用此方法,否则会造成 PV 类日志重复上报。
    import Monitor from '/util/monitor';
    Page({
        onShow: function() {
            Monitor.pageShow();
        }
    })
    					
  • 如需发送当前页面的 Health 类数据,统计当前页面的健康度和页面停留时间,则在 Page 的 onHideonUnload 方法下调用 pageHide() 方法。

    说明 请勿与 hookPage() 方法同时使用此方法,否则会造成日志重复上报。
    import Monitor from '/util/monitor';
      Page({
    
          onHide: function() {
              Monitor.pageHide();
          },
          onUnload: function() {
              Monitor.pageHide();
          }
          ... 
      })
    					

进阶场景

当基础使用方法无法满足需求时,请参考以下进阶场景。

  • 设置 uid(主要用于统计 UV 信息)

    • 如果在监控 SDK 初始化之前,能够获得与用户有关的信息,则可以直接设置 uid

    • 如果在监控 SDK 初始化之前,无法获得与用户有关的信息,则可以在应用 onShow 前获取用户信息,然后通过 setCommonInfo({uid: 'xxx'}); 设置 uid

  • 设置小程序相关的公共信息

    请使用 setCommonInfo 方法设置小程序相关的公共信息。ARMS 前端监控会对以下字段进行统计分析:

    • sr:屏幕尺寸
    • vp:浏览器窗口可见区域
    • dpr:屏幕像素比
    • ul:文档语言
    • dr:文档 Refer
    • ct:网络连接类型(例如 WiFi 或 3G)
      警告 切勿使用 setCommonInfo 方法设置过多字段,否则可能超出请求的限制长度,从而导致请求失败。

参考