@ked3/ktrace

v1.2.4

Published

9 months ago

跨平台埋点分析SDK

0High
0Medium
0Low

kibble5788

analytics tracking event 埋点统计

KTrace SDK

一个轻量级、跨平台的埋点分析SDK，支持多种前端框架和原生HTML项目。

特性

🚀 轻量级: 压缩后体积小，性能优异
🔧 易集成: 简单的API设计，快速集成到项目中
🌐 跨平台: 支持HTML、React、Vue等多种前端环境
📊 丰富事件: 支持页面访问、用户交互、错误监控等多种事件类型
🛡️ 类型安全: 完整的TypeScript类型定义
🔍 调试友好: 内置调试模式，便于开发调试
⚡ 自动追踪: 支持自动追踪页面访问、错误等常见事件

安装

NPM 安装

npm install @ked3/ktrace

CDN 引入

<script src="https://unpkg.com/@ked3/ktrace@latest/dist/ktrace.min.js"></script>

快速开始

HTML 原生项目

<!DOCTYPE html>
<html>
<head>
    <script src="./ktrace.min.js"></script>
</head>
<body>
    <script>
        // 初始化追踪器
        const tracker = new KTrace.HtmlAdapter({
            project_id: "your_project_id",
            enable_auto_track: true,
            debug: true
        });
        
        // 启动追踪
        tracker.init();
        
        // 手动追踪事件
        tracker.trackEvent(KTrace.EventKey.BUTTON_CLICK, {
            button_type: 'submit',
            page_section: 'header'
        });
    </script>
</body>
</html>

ES6 模块

import { HtmlAdapter, EventKey } from '@ked3/ktrace';

// 初始化追踪器
const tracker = new HtmlAdapter({
    project_id: "your_project_id",
    server_url: "https://your-analytics-server.com",
    enable_auto_track: true,
    debug: false
});

// 启动追踪
tracker.init();

// 追踪自定义事件
tracker.trackEvent(EventKey.USER_LOGIN, {
    user_id: '12345',
    login_method: 'email'
});

配置选项

interface TrackerConfig {
    /** 项目ID，必填项 */
    project_id: string;
    
    /** 数据上报的服务器地址（可选） */
    server_url?: string;
    
    /** 单条事件上报路径（可选） */
    event_path?: string;
    
    /** 批量事件上报路径（可选） */
    batch_event_path?: string;
    
    /** 是否启用自动埋点功能 */
    enable_auto_track?: boolean;
    
    /** 是否开启调试模式 */
    debug?: boolean;
}

支持的事件类型

页面相关事件

PAGE_VIEW - 页面访问
PAGE_LEAVE - 页面离开
PAGE_VISIBILITY_CHANGE - 页面可见性变化
ROUTE_CHANGE - 路由变化

用户交互事件

BUTTON_CLICK - 按钮点击
USER_INPUT - 用户输入
SCROLL - 滚动
HOVER - 鼠标悬停
DOUBLE_CLICK - 双击
RIGHT_CLICK - 右键点击
DRAG / DROP - 拖拽操作
FOCUS / BLUR - 焦点变化
CUSTOM_INTERACTION - 自定义交互
FEEDBACK_SUBMIT - 反馈提交

错误监控事件

JAVASCRIPT_ERROR - JavaScript错误
RESOURCE_ERROR - 资源加载错误
NETWORK_ERROR - 网络错误
COMPONENT_ERROR - 组件错误
CUSTOM_ERROR - 自定义错误

业务事件

USER_LOGIN - 用户登录
USER_LOGOUT - 用户登出
COMPONENT_LIFECYCLE - 组件生命周期

API 参考

HtmlAdapter

构造函数

const tracker = new HtmlAdapter(config);

方法

`init()`

初始化追踪器，设置自动追踪和错误监听。

tracker.init();

`trackEvent(eventKey, metadata?)`

追踪自定义事件。

tracker.trackEvent(EventKey.BUTTON_CLICK, {
    button_id: 'submit-btn',
    page_section: 'form'
});

`trackError(error, eventKey?, metadata?)`

追踪错误事件。

try {
    // 可能出错的代码
} catch (error) {
    tracker.trackError(error, EventKey.JAVASCRIPT_ERROR, {
        context: 'user_action'
    });
}

`trackPageView(path?)`

手动追踪页面访问。

tracker.trackPageView('/custom-page');

自动追踪功能

当 enable_auto_track 设置为 true 时，SDK会自动追踪以下事件：

页面加载完成时的页面访问事件
页面离开事件
JavaScript运行时错误
资源加载错误
Promise未捕获的错误

调试模式

开启调试模式后，SDK会在控制台输出详细的日志信息：

const tracker = new HtmlAdapter({
    project_id: "your_project_id",
    debug: true  // 开启调试模式
});

示例项目

查看 docs/examples/ 目录下的示例文件：

demo.html - 基础功能演示
demo2.html - 高级功能演示

开发

安装依赖

pnpm install

构建项目

pnpm run build

运行测试

pnpm run test

启动开发服务器

pnpm run dev

版本历史

v1.2.2

优化错误处理机制
增加更多事件类型支持
改进TypeScript类型定义

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。

支持

如果您在使用过程中遇到问题，请通过以下方式获取帮助：

查看示例代码
提交 GitHub Issue
查看项目文档