ystv-wk-tracker

H5埋点基础框架 - 基于三段式字段结构设计

特性

• 支持多种事件类型：点击、曝光、上焦、搜索等
• 完善的数据结构设计，包含系统字段、场景上下文字段和扩展字段
• 易于集成和使用
• 支持批量上报和定时上报
• 提供调试模式，便于开发调试
• 支持焦点事件防抖，避免频繁上报

注意事项

• 目前tv-list等非原生HTML组件不支持v-track自定义指令，请引入 plugin 后通过 this.$trackClick、this.$trackFocus 手动触发上报
• 需要引入mixin支持自动曝光组件，需要在引入组件处通过v-if处理组件显示隐藏，组件name不能为空，组件data中需要预先定义trackElementId, trackElementType等字段
• 组件销毁时会自动清理相关资源，但建议在应用退出前调用Tracking.destroy()确保队列中的日志全部上报
• 如果需要修改默认配置（如上报地址、批量上报阈值等），请在应用初始化时调用Tracking.init()方法
• 为确保数据准确性，请确保必要字段（如elementId、elementType）不为空
• 在批量上报模式下，数据不会立即发送，而是在达到阈值或定时器触发时统一上报
• 使用页面曝光功能时，如果未设置trackPageId，将自动生成页面ID
• 焦点事件默认启用300ms防抖，可通过FOCUS_DEBOUNCE配置项调整，设置为0则禁用防抖

安装

npm install ystv-wk-tracker

使用示例

1. 初始化（推荐）

import Tracking from "ystv-wk-tracker";

// 传入 Vue 实例，自动注册插件方法到 Vue.prototype
Tracking.init({
    Vue,                            // Vue 实例（必需，用于注册插件方法）
    DEBUG: true,                    // 开启调试模式
    REPORT_URL: "xxx",              // 上报接口地址
    FOCUS_DEBOUNCE: 500,            // 焦点防抖时间(ms)，默认300
});

初始化后可在组件中使用：

// 便捷方法
this.$trackFocus({ elementId: "xxx", elementType: this.$ELEMENT_TYPE.PROGRAMSET });
this.$trackClick({ elementId: "xxx", elementType: this.$ELEMENT_TYPE.PROGRAMSET });
this.$trackExpose({ pageId: "xxx", elementId: "xxx", elementType: this.$ELEMENT_TYPE.PROGRAMSET });

// 或使用 $tracking 实例
this.$tracking.init({ DEBUG: true });
this.$tracking.destroy();

初始化时会自动挂载以下内容到 Vue.prototype：

| 方法 | 说明 | |------|------| | this.$tracking | Tracking 实例，包含所有埋点方法 | | this.$ELEMENT_TYPE | 元素类型枚举 | | this.$EVENT_TYPE | 事件类型枚举 | | this.$trackFocus(params) | 上报焦点事件 | | this.$trackClick(params) | 上报点击事件 | | this.$trackExpose(params) | 上报曝光事件 | | this.$trackCustom(contextFields, options) | 自定义事件上报 |

配置项说明

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | PAGE_ID_PREFIX | string | "" | 项目包名，用于生成页面ID | | DEVICE_ID | string | "unknown" | 设备ID | | REPORT_URL | string | "http://127.0.0.1:8087/logup/1/400/log" | 上报接口地址 | | DEBUG | boolean | false | 是否开启调试模式 | | ENABLE_REPORT | boolean | true | 是否启用上报 | | TIMEOUT | number | 10000 | 上报请求超时时间(ms) | | BATCH_SIZE | number | 10 | 批量上报阈值 | | BATCH_INTERVAL | number | 5000 | 批量上报间隔(ms) | | FOCUS_DEBOUNCE | number | 300 | 焦点埋点防抖时间(ms)，设置为0则禁用防抖 |

焦点防抖说明

焦点事件防抖用于避免同一元素短时间内频繁触发焦点导致的重复上报：

• 默认值: 300ms
• 行为: 每个元素独立防抖，只有最后一次焦点事件会在延迟后上报
• 禁用: 设置 FOCUS_DEBOUNCE: 0 可禁用防抖功能
• 不同元素互不影响: 元素A和元素B的防抖计时器独立运行

2. 页面曝光

Tracking.pageExpose({
    pageId: "player",
    elementId: "channel_001",
    elementType: Tracking.ELEMENT_TYPE.PROGRAMSET,
});

// 或在组件中
this.$trackExpose({
    pageId: "player",
    elementId: "channel_001",
    elementType: this.$ELEMENT_TYPE.PROGRAMSET,
});

3. 点击事件

Tracking.click({
    elementId: "channel_001",
    elementType: Tracking.ELEMENT_TYPE.PROGRAMSET,
});

// 或在组件中
this.$trackClick({
    elementId: "channel_001",
    elementType: this.$ELEMENT_TYPE.PROGRAMSET,
});

4. 焦点事件

Tracking.focus({
    elementId: "channel_001",
    elementType: Tracking.ELEMENT_TYPE.PROGRAMSET,
});

// 或在组件中
this.$trackFocus({
    elementId: "channel_001",
    elementType: this.$ELEMENT_TYPE.PROGRAMSET,
});

5. 全局引入自定义指令(悟空小程序请在main-native.js中引入)

import { trackDirective } from "ystv-wk-tracker";

Vue.directive("track", trackDirective);

自定义指令触发点击和焦点事件

<!-- 使用自定义指令处理点击和焦点事件 -->
<div
    v-track="{
        elementId: 'channel_001',
        elementType: ELEMENT_TYPE.PROGRAMSET,
        buttonName: 'xx按钮',
        extend: { customField: 'value' },
    }"
>
    频道内容
</div>

<!-- 仅处理点击事件 -->
<div
    v-track:click="{
        elementId: 'btn_submit',
        elementType: ELEMENT_TYPE.PROGRAMSET,
        buttonName: '提交按钮',
    }"
>
    提交
</div>

<!-- 仅处理焦点事件 -->
<div
    v-track:focus="{
        elementId: 'need_to_focus',
        elementType: ELEMENT_TYPE.PROGRAMSET,
    }"
>
    上焦元素
</div>

Mixin 使用示例（自动曝光）

Mixin 仅用于自动曝光功能，手动上报请使用 plugin 提供的方法。

import { trackMixin } from "ystv-wk-tracker";

export default {
    mixins: [trackMixin],
    name: "pageNameXXX",
    data() {
        return {
            // 设置页面曝光参数
            trackPageId: "player_page", // 页面ID
            trackElementId: "channel_001", // 曝光元素ID
            trackElementType: this.ELEMENT_TYPE.PROGRAMSET, // 曝光元素类型
            trackFromPageId: "home_page", // 来源页面ID
            trackExtend: {
                // 扩展字段
                customField: "value",
            },
        };
    },
    methods: {
        handleClick() {
            // 使用 plugin 提供的方法上报点击事件
            this.$trackClick({
                elementId: "btn_click",
                elementType: this.$ELEMENT_TYPE.PROGRAMSET,
                extend: { action: "click_action" },
            });
        },

        handleFocus() {
            // 使用 plugin 提供的方法上报焦点事件
            this.$trackFocus({
                elementId: "input_focus",
                elementType: this.$ELEMENT_TYPE.PROGRAMSET,
                extend: { action: "focus_action" },
            });
        },

        reExpose() {
            // 重新触发曝光上报（mixin 提供）
            this.reTrackExposure();
        },
    },
};

主要功能

• 系统字段集: 包含用户、设备、平台、版本、网络、时间等维度的基础字段
• 场景上下文字段集: 根据不同业务场景变化的字段，反映场景、位置、内容的运营效果
• 扩展字段集: 业务团队可以自助添加新字段以快速迭代业务功能

事件类型

• 点击事件 (click)
• 上焦事件 (focusctrl)
• 页面曝光事件 (expose)

元素类型

• 节目集 (programset)
• 产品包 (product)
• 活动 (activity)
• 商家 (shop)
• 优惠券 (coupon)
• 套餐 (combo)
• 短视频 (shortvideo)

文件说明

• index.js: 主入口文件
• core.js: 核心上报模块，处理日志的组装、队列管理、上报逻辑
• context.js: 场景上下文构建模块
• constants.js: 常量定义
• trace.js: 用户路径追踪模块
• request.js: 请求处理模块
• util.js: 工具函数集合