tangbuy-trace

tangbuy-trace 是一个用于跟踪用户行为事件的 JavaScript 库，支持 Web 和 H5 平台。该库旨在帮助开发者轻松记录用户在页面中的操作，并将这些操作日志发送到指定的服务器。

引入

你可以根据实际需要，按需引入库中的模块。以下是一个示例：

// 只引入需要的模块
import { initTrace } from 'tangbuy-trace/web';

实例化

在使用库之前，你需要先初始化 Trace 实例。可以在项目的入口文件中进行如下操作：

const trace = initTrace({
  mode: 'prod', // 'test' 或 'prod'
  watchPath: false, // 是否监听路径变化, 建议使用手动设置pageInfo
  version: '1.0.0', // 数据来源版本
});

参数说明：

• mode: 选择运行环境，可以是 'test' 或 'prod'。
• watchPath: 布尔值，决定是否自动监听 URL 变化。
• version: 日志数据的版本号。

实例方法

1. trace.logEvent

logEvent 是 Trace 实例的主要方法之一，用于记录用户操作事件。你可以直接使用这个方法来记录各种类型的事件。

使用示例

trace.logEvent({
  model: 'user_operation',    // 事件归类
  eventName: 'search',        // 事件名称
  eventArgs: { keyword: '商品名' }  // 事件参数
});

这个方法接受一个对象作为参数，其中包括 model（事件归类）、eventName（事件名称）和 eventArgs（事件参数）等信息。

包装方法：traceLogEvent

你也可以使用 traceLogEvent 这个包装方法来简化事件记录。这个方法内部调用了 trace.logEvent。

引入

import { traceLogEvent } from 'tangbuy-trace/web';

使用示例

traceLogEvent({
  model: 'user_operation',    // 事件归类
  eventName: 'search',        // 事件名称
  eventArgs: { keyword: '商品名' }  // 事件参数
});

2. trace.setUserId

setUserId 是一个用于设置用户 ID 的方法，通常在用户登录或身份确认后调用。

使用示例

trace.setUserId('12345');

通过调用这个方法，你可以确保在记录事件时，所有相关的事件都包含正确的用户 ID。

3. trace.setPageInfo

setPageInfo 方法用于手动设置当前页面和来源页面的信息。当 watchPath 选项未启用时，你可以通过此方法手动管理页面信息。

使用示例

trace.setPageInfo({
  requestPage: '/home',
  fromPage: '/login'
});

4. trace.installBeforeGetUserInfo

installBeforeGetUserInfo 方法允许你在获取用户信息之前设置一个回调函数。这个回调函数会在每次记录事件时被调用，以确保用户信息是最新的。

使用示例

trace.installBeforeGetUserInfo(() => ({
  userId: '12345',
  token: 'abcdef'
}));

在这个回调函数中，你可以定义如何获取用户信息，并确保在记录事件时，这些信息是最新的。

包装的 API

traceLogEvent 是对 trace.logEvent 的包装，提供了更简洁的使用方式。如果你的项目中只需要记录事件，可以选择按需引入这些包装方法，而无需每次手动初始化 Trace 实例。

watchPath 的实现原理

watchPath 参数启用后，库内部会自动监听浏览器的 URL 变化，并根据这些变化更新当前页面的 requestPage 和 fromPage 信息。

具体实现包括：

1. 历史记录变更监听：通过重写 history.pushState 和 history.replaceState 方法，捕捉 URL 变化并调用事件处理函数。

2. 浏览器事件监听：通过监听 popstate 和 hashchange 事件，捕捉浏览器导航和 URL 哈希变化。

3. 页面信息更新：在捕捉到 URL 变化后，库会自动更新 requestPage 和 fromPage 信息，并将这些信息附加到每次事件日志的通用参数中。

示例

// 自动监听页面路径变化
const trace = initTrace({ watchPath: true });

// 手动设置页面信息（当不启用 watchPath 时）
trace.setPageInfo({
  requestPage: '/home',
  fromPage: '/login',
});

贡献

欢迎大家提交问题与贡献代码！如有任何问题或建议，请通过 issue 与我们联系。

License

ISC