Tracker.js 外部网站集成示例

💡 概述

Tracker.js 是一个轻量级的前端跟踪库，类似于 Google Analytics 4。它可以在任何网站中加载，用于跟踪用户行为并将数据发送到 KaloCash 服务器。

🚀 快速开始

1 引入 Tracker.js 脚本

在您的 HTML 页面中，添加以下代码（推荐放在 <head> 标签中）：

<!-- 方式1: 从 KaloCash 服务器加载（推荐） -->
<script src="https://your-kalocash-domain.com/static/web/js/tracker.js"></script>

<!-- 方式2: 下载到本地服务器后加载 -->
<script src="/path/to/tracker.js"></script>
                

2 初始化 Tracker

在引入脚本后，添加初始化代码：

<script>
    // 等待页面加载完成后初始化
    document.addEventListener('DOMContentLoaded', function() {
        if (typeof GA4Tracker !== 'undefined') {
            GA4Tracker.init({
                // ⚠️ 重要：配置 API 服务器地址（必须）
                apiBaseUrl: 'https://your-kalocash-domain.com',
                
                // 可选配置
                debug: true,  // 开启调试模式（生产环境建议设为 false）
                autoPageView: true,  // 自动跟踪页面浏览
                autoTrackOutboundLinks: true,  // 自动跟踪外部链接
                autoTrackForms: true,  // 自动跟踪表单提交
                autoTrackScroll: true,  // 自动跟踪页面滚动
                autoTrackDownloads: true,  // 自动跟踪文件下载
                autoTrackVideos: true,  // 自动跟踪视频播放
                
                batchSize: 10,  // 批量发送大小
                batchInterval: 5000  // 批量发送间隔（毫秒）
            });
            
            console.log('✅ Tracker 初始化成功');
        } else {
            console.error('❌ Tracker 未加载，请检查脚本路径');
        }
    });
</script>
                

📝 完整集成示例

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>我的网站</title>
    
    <!-- 引入 Tracker.js -->
    <script src="https://your-kalocash-domain.com/static/web/js/tracker.js"></script>
    
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            if (typeof GA4Tracker !== 'undefined') {
                GA4Tracker.init({
                    apiBaseUrl: 'https://your-kalocash-domain.com',
                    autoPageView: true,
                    autoTrackOutboundLinks: true,
                    debug: false  // 生产环境关闭调试
                });
            }
        });
    </script>
</head>
<body>
    <h1>欢迎访问我的网站</h1>
    <p>页面浏览会自动跟踪</p>
    
    <button onclick="trackButtonClick()">点击我</button>
    
    <script>
        // 自定义事件跟踪
        function trackButtonClick() {
            GA4Tracker.trackEvent('button_click', {
                button_name: '欢迎按钮',
                button_location: '首页'
            });
            alert('点击已记录！');
        }
    </script>
</body>
</html>
            

⚠️ 重要配置说明

必须配置 apiBaseUrl

当在其他网站中使用 Tracker.js 时，必须配置 apiBaseUrl 参数，指定 KaloCash 服务器的完整地址（包含协议和域名）。

示例：

apiBaseUrl: 'https://www.kalocash.com'
apiBaseUrl: 'https://analytics.example.com'
apiBaseUrl: 'http://localhost:8080' （仅用于开发测试）

CORS 跨域支持

如果您的网站和 KaloCash 服务器不在同一个域名下，需要确保 KaloCash 服务器已配置 CORS 支持。请联系服务器管理员确认 CORS 配置。

🔧 API 使用说明

跟踪页面浏览

// 自动跟踪（如果 autoPageView: true）
// 或手动跟踪
GA4Tracker.trackPageView('/custom-path', '自定义页面标题');
                

跟踪自定义事件

GA4Tracker.trackEvent('event_name', {
    param1: 'value1',
    param2: 'value2'
});
                

设置用户 ID

GA4Tracker.setUserId('user_12345');

设置用户属性

GA4Tracker.setUserProperties({
    user_type: 'premium',
    membership_level: 'gold'
});
                

跟踪异常

GA4Tracker.trackException('错误描述', false, {
    error_type: 'javascript_error'
});
                

🧪 测试示例

实时测试（需要先加载 tracker.js）

如果您已经加载了 tracker.js，可以点击下面的按钮进行测试：

❓ 常见问题

Q: 为什么跟踪数据没有发送到服务器？

A: 请检查以下几点：

是否配置了正确的 apiBaseUrl？
服务器是否支持 CORS 跨域请求？
打开浏览器开发者工具，查看控制台是否有错误信息
开启 debug: true 查看详细日志

Q: 如何验证跟踪是否正常工作？

A: 可以：

开启 debug: true，在浏览器控制台查看日志
打开浏览器开发者工具的 Network 标签，查看是否有发送到 /api/analytics/track 的请求
登录 KaloCash 后台管理系统，查看分析数据

Q: 数据是实时发送的吗？

A: 不是。Tracker.js 使用批量发送机制：

默认每 5 秒批量发送一次（可通过 batchInterval 配置）
当事件队列达到 10 个时立即发送（可通过 batchSize 配置）
页面关闭时会自动发送所有待发送的事件

📞 需要帮助？

如果您在集成过程中遇到问题，请：

查看浏览器控制台的错误信息
确认服务器 CORS 配置正确
联系 KaloCash 技术支持团队

📊 Tracker.js 外部网站集成指南