Status: ✅ Complete
Date: January 29, 2025
Phase: Phase 2 - Real Data Integration
This guide explains how the PrivacyMetrics dashboard now connects to real event data collected by the Lightweight Tracking Script. Instead of displaying mock/hardcoded data, the dashboard now calculates and displays actual analytics metrics from your websites.
Website with Tracking Script
↓
Events sent to /api/v1/events
↓
Events stored in database
↓
Dashboard queries aggregation service
↓
Metrics calculated from raw events
↓
Dashboard displays real analytics
server/services/aggregation.ts)
server/routes/dashboard.ts)
client/hooks/useDashboardData.ts)
client/pages/Dashboard.tsx)
Website visitors trigger events:
// Automatic pageviews
// Tracked on page load and SPA navigation
// Custom events (if configured)
PivotMetrics.track('custom', {
action: 'signup',
plan: 'premium'
});
Events are sent to the collection API:
POST /api/v1/events
{
trackingCode: "pm-xxx",
eventType: "pageview",
url: "https://website.com/page",
sessionId: "sess-123",
visitorId: "vis-123",
timestamp: "2025-01-29T10:00:00Z"
}
Events are stored in the database.
Dashboard queries aggregation service:
GET /api/v1/dashboard/metrics?websiteId=web-123&days=7
The aggregation service:
Components render the real data:
Page Views: 1,234 (+12%)
Unique Visitors: 456 (+8%)
Sessions: 567 (-3%)
Bounce Rate: 42% (+2%)
Avg Session Duration: 3m 45s (+15%)
Get overall dashboard metrics.
Query Parameters:
websiteId (required): Website IDdays (optional): Number of days to analyze (default: 7)Response:
{
"success": true,
"data": {
"pageViews": 1234,
"pageViewsChange": 12,
"uniqueVisitors": 456,
"uniqueVisitorsChange": 8,
"sessions": 567,
"sessionsChange": -3,
"avgSessionDuration": 225,
"avgSessionDurationChange": 15,
"bounceRate": 42,
"bounceRateChange": 2
}
}
Example:
curl -X GET "http://localhost:3000/api/v1/dashboard/metrics?websiteId=web-123&days=7" \
-H "Authorization: Bearer YOUR_TOKEN"
Get pageview data over time (for charting).
Query Parameters:
websiteId (required)days (optional): Default 7Response:
{
"success": true,
"data": [
{
"date": "2025-01-29",
"pageviews": 156
},
{
"date": "2025-01-28",
"pageviews": 142
}
],
"total": 1234
}
Get top pages by pageview count.
Query Parameters:
websiteId (required)days (optional): Default 7limit (optional): Default 10Response:
{
"success": true,
"data": [
{
"url": "https://example.com/",
"views": 450,
"uniqueVisitors": 320,
"bounceRate": 35,
"avgSessionDuration": 240
},
{
"url": "https://example.com/about",
"views": 320,
"uniqueVisitors": 280,
"bounceRate": 42,
"avgSessionDuration": 180
}
],
"total": 2
}
Get traffic sources (referrers).
Query Parameters:
websiteId (required)days (optional)limit (optional): Default 10Response:
{
"success": true,
"data": [
{
"referrer": "google.com",
"visitors": 150,
"sessions": 160,
"pageViews": 450
},
{
"referrer": "Direct",
"visitors": 120,
"sessions": 130,
"pageViews": 300
}
],
"total": 2
}
Get device breakdown statistics.
Query Parameters:
websiteId (required)days (optional)Response:
{
"success": true,
"data": {
"mobile": 400,
"desktop": 600,
"tablet": 100,
"other": 20
}
}
Add the Lightweight Tracking Script to your website:
<script>
window.TRACKER_CODE = 'your-tracking-code-from-dashboard';
</script>
<script src="https://your-analytics-domain.com/tracker.js" async></script>
Events are automatically tracked. To send custom events:
// In your application code
PivotMetrics.track('custom', {
event_name: 'signup',
plan: 'premium',
user_id: 'user-123'
});
To verify the setup is working:
window.PivotMetrics (should exist)/api/v1/eventsDefinition: Total number of page load events
Calculation: Count all events with eventType = "pageview"
Example:
Definition: Number of distinct visitors in period
Calculation: Count distinct visitorId values
Example:
Definition: Number of distinct user sessions
Calculation: Count distinct sessionId values where eventType = "pageview"
Example:
Definition: Percentage of sessions that have only 1 page view
Calculation: (Single-page sessions / Total sessions) × 100
Example:
Interpretation:
Definition: Average time spent per session
Calculation: Sum of all session durations / Number of sessions
Session duration: Time between first and last event in session
Example:
Definition: Percentage change comparing current period to previous period
Calculation: ((Current - Previous) / Previous) × 100
Example:
Dashboard supports multiple time periods:
| Range | Period | Comparison |
|---|---|---|
| 24h | Last 24 hours | vs previous 24h |
| 7d | Last 7 days | vs previous 7 days |
| 30d | Last 30 days | vs previous 30 days |
| 90d | Last 90 days | vs previous 90 days |
How to use:
// In browser console on your website
for (let i = 0; i < 5; i++) {
PivotMetrics.track('custom', {
test: true,
iteration: i
});
}
PivotMetrics.flush();
/api/v1/eventsRun the test suite:
npm test -- server/__tests__/aggregation.test.ts
Tests verify:
Possible causes:
Solutions:
Ctrl+U → search “TRACKER_CODE”Possible causes:
Solutions:
Note: Bounce rate requires session grouping logic. In early versions, may not be perfectly accurate. Please report if calculations seem off.
If dashboard is slow:
| Metric | Query Time |
|---|---|
| 1,000 events | <100ms |
| 10,000 events | 100-500ms |
| 100,000 events | 500ms-2s |
| 1M+ events | Consider pre-aggregation |
A: Events are batched for performance (default 5-10 seconds). This reduces API calls and improves efficiency. You can manually flush with PivotMetrics.flush().
A: Currently, the dashboard shows aggregated metrics for privacy. Individual visitor tracking is intentionally not exposed to protect user privacy.
A: Metrics are calculated from actual event data, so they’re as accurate as the tracking. Edge cases (timezone transitions, clock skew) may cause minor variations.
A: Data export is a future feature. For now, you can use the API endpoints to programmatically retrieve metrics.
A: Currently, all events are retained indefinitely. We recommend periodic archival for very large datasets.
For questions or issues:
npm testImplementation Status: ✅ Complete
Last Updated: January 29, 2025