当前位置：首页 > 行业动态 > 正文

hm.js使用说明

hm.js是轻量级工具库，提供DOM操作、事件处理等常用方法，支持ES6/CommonJS导入，如 import { $ } from 'hm.js'，可快速选取元素并绑定事件，如 $('#btn').on('click', () => {})

hm.js使用说明

工具简介

hm.js是一款轻量级前端埋点库，主要用于网页或移动应用的性能监控、用户行为分析及错误追踪，其核心功能包括：

hm.js使用说明 第1张

  • 自动化数据采集：支持页面加载、点击、错误等基础事件的自动捕获。
  • 自定义事件上报：允许开发者手动标记关键业务节点（如按钮点击、表单提交）。
  • 实时数据传输：通过异步接口将数据发送至后端服务器，减少对主线程阻塞。
  • 跨平台兼容：支持PC、H5、小程序等多种环境，适配主流浏览器。

安装与引入

安装方式

环境 安装命令或步骤
浏览器 直接引入脚本：<script src="path/to/hm.js"></script>
Node.js 通过包管理器安装：npm install hm.js
CDN 使用公共链接：<script src="https://cdn.example.com/hm.js"></script>

依赖说明

  • 浏览器环境需支持ES5+语法。
  • Node.js环境需配合模块化工具（如Webpack）使用。

基础配置

初始化配置

// 基础初始化（必填参数为appid和url）
hm.init({
  appid: 'your-app-id',          // 应用唯一标识，用于区分数据来源
  url: 'https://api.example.com/collect', // 数据接收接口地址
  debounce: 500,                // 事件合并上报的时间间隔（毫秒）
  timeout: 3000,                // 单次上报超时时间（毫秒）
  heartbeat: 10000              // 心跳间隔（毫秒，用于保持连接）
});

核心参数说明

参数 类型 默认值 作用描述
appid String 无 应用唯一标识，必填项
url String 无 数据上报接口地址，必填项
debounce Number 500 事件合并上报的时间阈值，单位毫秒
timeout Number 3000 单次上报请求超时时间，单位毫秒
heartbeat Number 10000 心跳检测间隔，用于维持长连接（部分场景支持）

事件上报与监听

自动采集事件

hm.js默认会自动捕获以下事件，无需手动调用：

  • 页面性能：pageLoad（页面加载完成）、domReady（DOM渲染完成）。
  • 用户交互：click（点击事件）、scroll（滚动深度）。
  • 资源错误：error（JavaScript错误）、resourceError（资源加载失败）。

自定义事件上报

// 手动触发事件（推荐用于关键业务节点）
hm.event('customEvent', {
  params: {
    key1: 'value1',         // 自定义参数
    key2: 123               // 数值型参数
  }
});

事件监听与回调

// 监听事件触发结果
hm.onEvent((data) => {
  console.log('事件已上报:', data);
});
// 监听错误信息
hm.onError((err) => {
  console.error('上报失败:', err);
});

高级功能配置

数据过滤与采样

// 过滤指定事件（如忽略所有点击事件）
hm.ignoreEvents(['click']);
// 设置采样率（仅上报10%的事件）
hm.setSampleRate(0.1);

隐私保护设置

// 禁用自动收集敏感信息（如User-Agent、IP地址）
hm.disableTracking({
  userAgent: true,    // 是否禁用用户代理信息
  ip: true            // 是否禁用IP地址收集
});

使用场景示例

网页性能监控

// 初始化配置
hm.init({
  appid: 'web-performance-123',
  url: 'https://monitor.example.com/api/collect'
});
// 自动捕获页面加载事件
hm.on('pageLoad', () => {
  console.log('页面加载完成，性能数据已上报');
});

用户行为分析

// 记录按钮点击事件
document.querySelector('.submit-btn').addEventListener('click', () => {
  hm.event('buttonClick', {
    buttonId: 'submitBtn',
    timestamp: Date.now()
  });
});

错误追踪

// 全局捕获JS错误
window.onerror = (msg, url, line, col) => {
  hm.event('error', {
    message: msg,
    file: url,
    line: line,
    column: col
  });
};

常见问题与解决方案

数据未上报或延迟问题

问题现象 可能原因 解决方案
事件未触发上报 appid或url配置错误
网络中断		 检查配置参数
确认网络连通性
数据延迟到达后端 debounce时间过长
服务器压力大		 调低debounce值
优化后端接口

浏览器兼容性问题

  • 表现：低版本浏览器（如IE11）报错。
  • 解决：启用兼容性模式,或通过Polyfill补充缺失API。

FAQs（常见问题解答）

Q1：如何排查事件未成功上报的问题？

A1：

  1. 检查控制台是否有报错信息（如Network Error或403状态码）。
  2. 确认appid和url是否正确配置，且后端接口允许跨域请求。
  3. 通过hm.onError监听错误回调,定位具体失败原因。

Q2：能否限制某些事件仅在特定条件下上报？

A2：
可以通过条件判断结合hm.event实现。 

if (userIsVIP) {
  hm.event('vipClick', { / 参数 / });
}
hm.js单页路由配置
0

相关文章