Tracking & Voluum Analytics
Relevant source files
The following files were used as context for generating this wiki page:
The Tracking & Voluum Analytics system in FusionOps is a multi-layered infrastructure designed to capture user engagement, monitor campaign performance, and synchronize data with external tracking platforms like Voluum. It employs a first-party tracking pixel for direct event logging and leverages the Voluum API for automated campaign management and click-id synchronization.
This system ensures that every user interaction—from initial page views (pv) to form submissions and conversions—is recorded with high fidelity while maintaining security through anti-fingerprinting techniques and domain-specific variations.
Sources: CLAUDE.md, PRODUCTION_READY.md
System Architecture
The tracking architecture consists of three primary layers: the client-side event emitters, the Cloudflare Pixel Worker for event ingestion, and the API Worker for external platform integration.
Core Components
| Component | Function | Technology |
|---|---|---|
| Pixel Worker | Ingests events via beacon/GIF requests and stores them in D1. | Cloudflare Worker + D1 |
| Voluum API Handler | Manages campaign creation, lander updates, and data fetching. | Node.js / API Worker |
| Tracking Dashboard | Visualizes real-time and historical event data for operators. | React + Recharts |
| First-Party Pixel | Client-side script for extracting Click IDs and firing events. | Vanilla JS (Inline) |
Sources: CLAUDE.md:46-52, apps/pixel-worker/src/index.ts
Event Data Flow
User events flow from the landing page to the Pixel Worker, which validates the payload and logs it to a dedicated D1 database instance.
The diagram shows the progression from user interaction to database storage and visualization.
Sources: apps/pixel-worker/src/index.ts, src/components/TrackingDashboard.jsx
Pixel Worker Implementation
The Pixel Worker is the primary ingestion point for all tracking data. It handles GET requests for a 1x1 transparent GIF and POST requests containing event payloads.
Event Processing Logic
The worker extracts campaign IDs, event types, and user UUIDs from incoming requests. It implements security measures like domain-specific headers and timing randomization to prevent fingerprinting.
Sources: apps/pixel-worker/src/index.ts:1-25, PRODUCTION_READY.md:79-92
Tracking Endpoints
- GET
/e: Returns a transparent 1x1 GIF and logs the event (often used for page views). - POST
/e: Accepts a JSON payload for more complex events likeform_startorconversion.
Click ID Handling
The system extracts Click IDs from various URL parameters to maintain continuity across traffic sources.
| Parameter Name | Purpose |
|---|---|
vlcid | Voluum Click ID |
clickid | Standard Click ID |
cid | Short Campaign ID |
cpid | Campaign Personal ID |
Sources: files/tracking-validation-prompt.md:23-28
Voluum Integration
FusionOps integrates deeply with the Voluum platform to automate the creation and management of marketing campaigns.
API Capabilities
The voluum-api.js handler manages authentication and resource management via the Voluum REST API. It handles:
- Campaign CRUD: Programmatic creation of tracking campaigns.
- Lander Management: Syncing landing page URLs and scripts.
- Postback Forwarding: Sending conversion data from the Callback Worker to Voluum.
Sources: apps/api-worker/src/handlers/voluum-api.js
Sequence: Campaign Creation
This sequence illustrates the automated handshake between FusionOps and Voluum during site deployment.
Sources: apps/api-worker/src/handlers/voluum-api.js
Data Visualization & Monitoring
The Tracking Dashboard provides a real-time view of campaign performance, aggregating data from the Pixel D1 database.
Key Metrics Tracked
- Page Views (PV): Total initial loads of the landing page.
- Form Starts: When a user first interacts with an input field.
- Form Submits: Successful lead generation events.
- Conversion Rate: Ratio of submits to page views.
Sources: src/components/TrackingDashboard.jsx:85-110
Security & Anti-Fingerprinting
To avoid detection by ad platforms, the workers implement randomized fingerprints:
- Server Headers: Randomly varies between
nginx,LiteSpeed, andApache. - Timing Randomization: Artificial delays of 0-8ms are added to responses.
- Error Variances: Domain-specific error message formats.
Sources: PRODUCTION_READY.md:85-102
Summary
The Tracking & Voluum Analytics system ensures robust data collection through a first-party Cloudflare Worker infrastructure. By combining direct D1 event logging with deep Voluum API integration, the project provides operators with a comprehensive view of campaign performance while protecting infrastructure from automated detection through advanced anti-fingerprinting techniques.
Sources: PRODUCTION_READY.md:120-135, CLAUDE.md:46-52