Umami统计系统集成与问题排查实战#

1
<!-- 启用自动追踪 -->
2
<script
3
    data-auto-track="true"
4
    data-cache="true"
5
    data-domains="your-domain.com"
6
    data-host-url="https://your-umami-instance.com"
7
    src="https://umami.is/script.js"
8
></script>

1
// 等待Umami加载
2
function waitForUmami() {
3
    if (window.umami && typeof window.umami.track === 'function') {
4
        window.umamiReady = true;
5
        console.log('[Umami] Ready for tracking');
6
        return true;
7
    }
8

9
    setTimeout(waitForUmami, 500);
10
    return false;
11
}
12

13
// 手动追踪事件
14
function trackCustomEvent(eventName, eventData = {}) {
15
    if (window.umamiReady && window.umami) {
16
        window.umami.track(eventName, eventData);
17
        console.log(`[Umami] Event tracked: ${eventName}`, eventData);
18
    } else {
19
        console.warn('[Umami] Not ready, event not tracked:', eventName);
20
    }
21
}
22

23
// 使用示例
24
trackCustomEvent('button-click', { button: 'download' });
25
trackCustomEvent('form-submit', { form: 'contact' });

1
// 手动页面追踪（适用于SPA）
2
function trackPageView(url, title) {
3
    if (window.umami) {
4
        window.umami.track(props => ({
5
            ...props,
6
            url: url,
7
            title: title
8
        }));
9
    }
10
}
11

12
// 路由变化时调用
13
trackPageView('/new-page', 'New Page Title');

1
// 延迟加载统计脚本
2
function loadUmamiWhenIdle() {
3
    if ('requestIdleCallback' in window) {
4
        requestIdleCallback(loadUmami);
5
    } else {
6
        setTimeout(loadUmami, 100);
7
    }
8
}
9

10
function loadUmami() {
11
    const script = document.createElement('script');
12
    script.src = 'https://umami.is/script.js';
13
    script.setAttribute('data-website-id', 'your-website-id');
14
    script.async = true;
15
    script.defer = true;
16
    document.head.appendChild(script);
17
}
18

19
// 页面加载完成后延迟加载
20
window.addEventListener('load', loadUmamiWhenIdle);

1
// API响应缓存
2
const CACHE_DURATION = 5 * 60 * 1000; // 5分钟
3
const statsCache = new Map();
4

5
async function getCachedStats(url) {
6
    const cacheKey = url;
7
    const cached = statsCache.get(cacheKey);
8

9
    if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
10
        console.log('[Stats Cache] Hit:', cacheKey);
11
        return cached.data;
12
    }
13

14
    try {
15
        const data = await fetchStats(url);
16
        statsCache.set(cacheKey, {
17
            data,
18
            timestamp: Date.now()
19
        });
20

21
        console.log('[Stats Cache] Miss, cached:', cacheKey);
22
        return data;
23
    } catch (error) {
24
        // 返回缓存数据（如果有）
25
        if (cached) {
26
            console.log('[Stats Cache] Error, using stale cache:', cacheKey);
27
            return cached.data;
28
        }
29
        throw error;
30
    }
31
}

1
// 批量获取统计数据
2
class StatsManager {
3
    constructor() {
4
        this.queue = [];
5
        this.processing = false;
6
        this.batchSize = 5;
7
        this.batchDelay = 100;
8
    }
9

10
    async getStats(url, element) {
11
        return new Promise((resolve, reject) => {
12
            this.queue.push({ url, element, resolve, reject });
13
            this.processBatch();
14
        });
15
    }
16

17
    async processBatch() {
18
        if (this.processing || this.queue.length === 0) {
19
            return;
20
        }
21

22
        this.processing = true;
23

24
        while (this.queue.length > 0) {
25
            const batch = this.queue.splice(0, this.batchSize);
26

27
            try {
28
                await Promise.all(
29
                    batch.map(async ({ url, element, resolve, reject }) => {
30
                        try {
31
                            const data = await getCachedStats(url);
32
                            this.updateElement(element, data);
33
                            resolve(data);
34
                        } catch (error) {
35
                            reject(error);
36
                        }
37
                    })
38
                );
39
            } catch (error) {
40
                console.error('[Stats Batch] Error:', error);
41
            }
42

43
            // 批次间延迟
44
            if (this.queue.length > 0) {
45
                await new Promise(resolve => setTimeout(resolve, this.batchDelay));
46
            }
47
        }
48

49
        this.processing = false;
50
    }
51

52
    updateElement(element, data) {
53
        if (!element) return;
54

55
        const { pageviews, visitors } = data;
56
        const viewsEl = element.querySelector('[data-stats="views"]');
57
        const visitorsEl = element.querySelector('[data-stats="visitors"]');
58

59
        if (viewsEl) {
60
            viewsEl.textContent = pageviews > 0 ? `${pageviews} 次浏览` : '暂无数据';
61
        }
62

63
        if (visitorsEl) {
64
            visitorsEl.textContent = visitors > 0 ? `${visitors} 位访客` : '暂无数据';
65
        }
66
    }
67
}
68

69
// 使用示例
70
const statsManager = new StatsManager();
71

72
// 为多个文章卡片获取统计数据
73
document.querySelectorAll('[data-post-url]').forEach(element => {
74
    const url = element.getAttribute('data-post-url');
75
    statsManager.getStats(url, element);
76
});

1
// 统一配置管理
2
interface UmamiConfig {
3
    websiteId: string;
4
    apiUrl: string;
5
    apiToken: string;
6
    domains: string[];
7
    autoTrack: boolean;
8
    cache: boolean;
9
}
10

11
const umamiConfig: UmamiConfig = {
12
    websiteId: process.env.UMAMI_WEBSITE_ID!,
13
    apiUrl: process.env.UMAMI_API_URL!,
14
    apiToken: process.env.UMAMI_API_TOKEN!,
15
    domains: ['localhost', 'your-domain.com'],
16
    autoTrack: true,
17
    cache: true
18
};

1
// Umami错误监控
2
class UmamiMonitor {
3
    constructor() {
4
        this.errors = [];
5
        this.setupErrorHandling();
6
    }
7

8
    setupErrorHandling() {
9
        // 监听脚本加载错误
10
        document.addEventListener('error', (event) => {
11
            if (event.target.src && event.target.src.includes('umami')) {
12
                this.logError('Script Load Error', {
13
                    src: event.target.src,
14
                    message: 'Failed to load Umami script'
15
                });
16
            }
17
        }, true);
18

19
        // 监听API错误
20
        const originalFetch = window.fetch;
21
        window.fetch = async (...args) => {
22
            try {
23
                const response = await originalFetch(...args);
24

25
                if (args[0].includes('/api/stats') && !response.ok) {
26
                    this.logError('API Error', {
27
                        url: args[0],
28
                        status: response.status,
29
                        statusText: response.statusText
30
                    });
31
                }
32

33
                return response;
34
            } catch (error) {
35
                if (args[0].includes('/api/stats')) {
36
                    this.logError('Network Error', {
37
                        url: args[0],
38
                        error: error.message
39
                    });
40
                }
41
                throw error;
42
            }
43
        };
44
    }
45

46
    logError(type, details) {
47
        const error = {
48
            type,
49
            details,
50
            timestamp: new Date().toISOString(),
51
            userAgent: navigator.userAgent,
52
            url: window.location.href
53
        };
54

55
        this.errors.push(error);
56
        console.error('[Umami Monitor]', error);
57

58
        // 可选：发送错误报告
59
        this.reportError(error);
60
    }
61

62
    async reportError(error) {
63
        try {
64
            await fetch('/api/error-report', {
65
                method: 'POST',
66
                headers: { 'Content-Type': 'application/json' },
67
                body: JSON.stringify(error)
68
            });
69
        } catch (e) {
70
            console.warn('[Umami Monitor] Failed to report error:', e);
71
        }
72
    }
73

74
    getErrorSummary() {
75
        return {
76
            totalErrors: this.errors.length,
77
            errorTypes: [...new Set(this.errors.map(e => e.type))],
78
            recentErrors: this.errors.slice(-5)
79
        };
80
    }
81
}
82

83
// 启用监控
84
const monitor = new UmamiMonitor();

1
// Umami功能测试
2
class UmamiTester {
3
    async runTests() {
4
        const results = [];
5

6
        // 测试脚本加载
7
        results.push(await this.testScriptLoading());
8

9
        // 测试API连接
10
        results.push(await this.testAPIConnection());
11

12
        // 测试事件追踪
13
        results.push(await this.testEventTracking());
14

15
        // 测试URL处理
16
        results.push(await this.testUrlHandling());
17

18
        return results;
19
    }
20

21
    async testScriptLoading() {
22
        return {
23
            name: 'Script Loading',
24
            passed: !!(window.umami && typeof window.umami.track === 'function'),
25
            details: {
26
                umamiExists: !!window.umami,
27
                trackFunction: typeof window.umami?.track,
28
                scriptElement: !!document.querySelector('[data-website-id]')
29
            }
30
        };
31
    }
32

33
    async testAPIConnection() {
34
        try {
35
            const response = await fetch('/api/stats?url=%2F');
36
            const data = await response.json();
37

38
            return {
39
                name: 'API Connection',
40
                passed: response.ok && typeof data.pageviews === 'number',
41
                details: {
42
                    status: response.status,
43
                    hasPageviews: typeof data.pageviews === 'number',
44
                    hasVisitors: typeof data.visitors === 'number'
45
                }
46
            };
47
        } catch (error) {
48
            return {
49
                name: 'API Connection',
50
                passed: false,
51
                details: { error: error.message }
52
            };
53
        }
54
    }
55

56
    async testEventTracking() {
57
        if (!window.umami) {
58
            return {
59
                name: 'Event Tracking',
60
                passed: false,
61
                details: { error: 'Umami not loaded' }
62
            };
63
        }
64

65
        try {
66
            // 发送测试事件
67
            window.umami.track('test-event', { test: true });
68

69
            return {
70
                name: 'Event Tracking',
71
                passed: true,
72
                details: { eventSent: true }
73
            };
74
        } catch (error) {
75
            return {
76
                name: 'Event Tracking',
77
                passed: false,
78
                details: { error: error.message }
79
            };
80
        }
81
    }
82

83
    async testUrlHandling() {
84
        const testUrls = [
85
            '/posts/测试文章/',
86
            '/posts/%E6%B5%8B%E8%AF%95%E6%96%87%E7%AB%A0/',
87
            '/posts/test-article/'
88
        ];
89

90
        const results = {};
91

92
        for (const url of testUrls) {
93
            const normalized = decodeURIComponent(url);
94
            const encoded = encodeURIComponent(normalized);
95

96
            results[url] = {
97
                original: url,
98
                normalized: normalized,
99
                encoded: encoded
100
            };
101
        }
102

103
        return {
104
            name: 'URL Handling',
105
            passed: true,
106
            details: results
107
        };
108
    }
109
}
110

111
// 运行测试
112
const tester = new UmamiTester();
113
tester.runTests().then(results => {
114
    console.log('[Umami Tests]', results);
115
});