qx-behav-track

v2.0.10

Published

a year ago

Behav-Track 是一个专为 Vue 项目设计的行为跟踪工具，旨在帮助你高效地收集和分析用户在应用中的行为数据。本手册将详细指导你如何在 Vue 项目中安装、配置、使用 Behav-Track，并介绍数据埋点和相关注意事项。

0High
0Medium
0Low

zkfy

Behav-Track 使用手册

一、安装

使用 npm 安装

npm install qx-behav-track

环境参数配置

环境参数非必需，未配置时可通过初始化函数的 options 传入。配置环境参数需要在本地的.env文件中添加内容。

Vite 环境参数

VITE_VERSION=2.0.0
VITE_DEV_SERVER_URL=https://buriedpoint.100bm.cn/track
VITE_PROD_SERVER_URL=https://buriedpoint.qianxingniwo.com/track
VITE_STORAGE_TYPE=localStorage

Webpack 环境参数

VERSION=2.0.0
DEV_SERVER_URL=https://buriedpoint.100bm.cn/track
PROD_SERVER_URL=https://buriedpoint.qianxingniwo.com/track
STORAGE_TYPE=localStorage

二、初始化

初始化代码需要放到main.ts文件中。Behav-Track 提供两种方式初始化：

方式1：通过 `app.use` + `options`

import { createApp } from 'vue';
import App from './App.vue';
import behaveTrack from "behav-track";

const app = createApp(App);
app.use(behaveTrack, {
    platform: 'wxwv', // 平台类型：微信嵌入h5
    projectId: 'mall', // 商城项目
    systemId: 'zsy', // 中石油商城
    forceLogin: true, // 登录成功后开始上报
    localTracking: true // 启动本地调试模式上报
    // 其它参数参见：options
});

方式2：通过 `behaveTrack.$gdp`

import { createApp } from 'vue';
import App from './App.vue';
import behaveTrack from "behav-Track";

const app = createApp(App);
app.use(behaveTrack);

// wechatH5: 微信嵌入h5, mall: 商城项目, zsy: 中石油商城, appid: 空，options: 覆盖默认参数, true: 登录成功后开始上报
behaveTrack.$gdp.wechatH5("mall", "zsy", "", { localTracking: true }, true);

初始化成功后可通过 Vue 全局对象或 window.$gdp 调用挂载函数：

this.$gdp.track({event:"user.login.sms",id: "u983782923",title:"短信登录" }); // Vue Composition API 中

// 或

window.$gdp.track({event:"user.login.sms",id: "u983782923",title:"短信登录" }); // Vue Composition API 或 JS 模块中

options 参数说明

| 参数名 | 描述 | 类型 | 默认值 | | ---------------- | -------------------------------------------------------------------------------------------------------------------- | ------ | -------------------- | | projectId | 项目编号，见基础数据表 | 字符串 | 无 | | systemId | 系统编号，见基础数据表 | 字符串 | 无 | | platform | 平台类型: web PC/H5 站点, Android 安卓内嵌页, wxwv 微信公众号内嵌页, iOS iOS 内嵌页, Minp 微信小程序内嵌页 | 字符串 | 无 | | forceLogin | 是否强制登录（需要登录后才能使用的系统请设为 true） | 布尔值 | false | | version | 版本号 | 字符串 | behav-track 的版本号 | | debug | 调试模式（开启后在控制台打印上报日志） | 布尔值 | false | | localTracking | 本地上报开关（true 时开启本地上报） | 布尔值 | false | | serverUrl | 上报服务器地址（根据 debug 或 localTracking 自动选择） | 字符串 | 自动选择 | | storageType | 埋点数据存储类型 ("localStorage", "cookie") | 字符串 | "localStorage" | | sessionExpires | session 过期时间 | 数字 | 1 年 |

三、用户信息

1. 设置 Identify

forceLogin 设置为 true 时：必须在登录成功后调用 identify 函数设置唯一标识，否则数据不会上报。

this.$gdp.identify("87698372112");// Vue Composition API 中

// 或

window.$gdp.identify("87698372112"); // Vue Composition API 或 JS 模块中

2. 设置 User ID

用户登录成功后立即设置：

this.$gdp.setUserId("u908777"); // Vue Composition API 中

// 或

window.$gdp.setUserId("u908777"); // Vue Composition API 或 JS 模块中

3. setUserAttributes

用于设置用户信息，可传递任意数据，输入为对象。

this.$gdp.setUserAttributes({ uid: "u908777", age: 28 }); // Vue Composition API 中

// 或

window.$gdp.setUserAttributes({ uid: "u908777", sex: 1 }); // Vue Composition API 或 JS 模块中

4. setUser

用户登录成功后立即设置：

this.$gdp.setUser("u908777", "张三"); // Vue Composition API 中

// 或

window.$gdp.setUser("u908777", "张三"); // Vue Composition API 或 JS 模块中

setUser 是 identify、setUserId、setUserAttributes 的组合。实现代码如下：

export function setUser(userId: string | number, userName?: string): void {
    setUserId(userId);
    identify(userId);
    setUserAttributes({
        userName: userName
    });
}

四、数据埋点

1. `event` 介绍

event 是用于标识某一功能具体行为的唯一名称，是进行大数据分析计算时的关键。所有 event 必须预先定义好，并统一配置到数据中。前端在初始化时会自动拉取这些配置并缓存。埋点时，必须使用已定义的 event，否则会报错。这样做确保了数据的一致性和准确性。

2. 指令埋点

适用场景：指令埋点适用于需要在模板中直接绑定埋点数据的场景，特别是当埋点数据与模板中的某个元素或属性紧密相关时。它简化了埋点的过程，使得在模板中就能完成埋点的配置。

<script setup lang="ts">
import { ref } from 'vue';
let data = ref<{ event: string; id: string; title: string }>({});
data.value = {
  event: 'home.topbar.banner.click', // 事件名称，必须使用预定义的名称
  id: '16892', // 对象的数据编号，必须
  title: '元旦福利', // 对象的标题说明，必须
};
</script>

<template>
  <!-- 使用 v-x-track 指令将埋点数据绑定到 a 元素上 -->
  <a v-x-track="data">点击这里查看元旦福利</a>
</template>

以上埋点在 click 事件触发后上报埋点数据。

v-x-track 等同于 v-x-track:click，还支持 v-x-track:change，在元素的 change 事件触发后上报埋点数据。

3. 函数埋点

适用场景：函数埋点适用于需要在组件的某个方法或生命周期钩子中进行埋点的场景。它提供了更大的灵活性，允许开发者在代码逻辑中动态地决定何时进行埋点。

<script setup lang="ts">
const login = () => {
    // 用户登录成功后处理以下逻辑----------------------
    window.$gdp.identify("16892"); // 设置用户登录唯一标识
    window.$gdp.setUserId("16892"); // 设置用户编号
    // 上报登录事件
    window.$gdp.track({
        event: 'user.login.sms',
        id: '16892', // 用户编号，日志编号皆可
        title: '登录成功', // 说明字段
    });
}
</script>

在上面的例子中，login 方法处理用户登录成功后设置用户信息，并添加埋点数据。

另外，同时调用 identify 和 setUserId 函数比较繁琐，也可以调用它们的合并函数 setUser：

<script setup lang="ts">
const login = () => {
    // 用户登录成功后处理以下逻辑----------------------
    window.$gdp.setUser("16892", "张三"); // 设置用户 identify, user id, name
    // 上报登录事件
    window.$gdp.track({
        event: 'user.login.sms',
        id: '16892', // 用户编号，日志编号皆可
        title: '登录成功', // 说明字段
    });
}
</script>

4. 数据类型

只有符合IEventData数据结构的数据才能会上报

// 定义产品项接口，包含事件名称、SKU ID和SPU ID
export interface IProductItem {
    event: string; // 事件名称
    name: string; // 产品名称
    skuId: string | number; // SKU ID，可以是字符串或数字
    spuId: string | number; // SPU ID，可以是字符串或数字
}

// 定义搜索接口，包含事件名称和关键词
export interface ISearch {
    event: string; // 事件名称
    keywords: string; // 搜索关键词
    resultCount?: number; // 结果数量
}

// 定义用户接口，包含事件名称、用户ID和用户名
export interface IUser {
    event: string; // 事件名称
    id: string | number; // 用户ID，可以是字符串或数字
    name: string; // 用户名
}

// 定义项目接口，包含事件名称、项目ID和项目标题
export interface IItem {
    event: string; // 事件名称
    id: string | number; // 项目ID，可以是字符串或数字
    title: string; // 项目标题
}

// 定义结果接口，包含事件名称、输入数据和结果数量
export interface IQuery {
    event: string; // 事件名称
    input: any; // 输入数据，可以是任何类型
    resultCount: number; // 结果数量
}

// 定义事件数据类型，可以是IProductItem、ISearch、IItem、IUser或IQuery中的任何一个
export type IEventData = IProductItem | ISearch | IItem | IUser | IQuery;

// 类型保护函数，用于判断给定事件是否为IProductItem类型
export function IsProductItem(event: any): event is IProductItem {
    // 检查event是否为非空对象，并且包含event、skuId和spuId属性
    return typeof event === 'object' && event !== null && 'event' in event && 'name' in event && 'skuId' in event && 'spuId' in event;
}

// 类型保护函数，用于判断给定事件是否为ISearch类型
export function IsSearch(event: any): event is ISearch {
    // 检查event是否为非空对象，并且包含event和keywords属性
    return typeof event === 'object' && event !== null && 'event' in event && 'keywords' in event;
}

// 类型保护函数，用于判断给定事件是否为IUser类型
export function IsUser(event: any): event is IUser {
    // 检查event是否为非空对象，并且包含event、id和name属性
    return typeof event === 'object' && event !== null && 'event' in event && 'id' in event && 'name' in event;
}

// 类型保护函数，用于判断给定事件是否为IItem类型
export function IsItem(event: any): event is IItem {
    // 检查event是否为非空对象，并且包含event、id和title属性
    return typeof event === 'object' && event !== null && 'event' in event && 'id' in event && 'title' in event;
}

// 类型保护函数，用于判断给定事件是否为IQuery类型
export function IsQuery(event: any): event is IQuery {
    // 检查event是否为非空对象，并且包含event、input和resultCount属性
    return typeof event === 'object' && event !== null && 'event' in event && 'input' in event && 'resultCount' in event;
}

// 综合判断函数，用于判断给定事件是否为IEventData类型中的任何一种
export function IsIEventData(event: any): event is IEventData {
    // 依次调用各个类型保护函数，如果任何一个返回true，则event是IEventData类型
    return IsProductItem(event) || IsSearch(event) || IsItem(event) || IsUser(event) || IsQuery(event);
}

非IEventData类型报错：

event未定义时报错: