PixelHandler

Publisher Platform Pixel Tracking & Conversion Microservice

Service Type: Kubernetes Microservice
Technology: Node.js (JavaScript)
Runtime: Node.js Container
Last Updated: 2025-07-01

📋 Overview

The PixelHandler microservice is the central pixel tracking and conversion processing engine for the Publisher platform. It handles multiple types of tracking pixels including conversion tracking, revenue pixels, and session tracking from various sources like Facebook, TikTok, and custom postback URLs. The service processes pixel events, validates them against cached configurations, and routes them to appropriate Event Hubs for downstream processing.

Key Features

Multi-Platform Pixel Support: Facebook, TikTok, and custom postback pixels
Conversion Tracking: Comprehensive conversion event processing
Revenue Tracking: Multiple revenue stream processing (publisher, exchange, unaccounted)
Session Management: Session-based ad pixel tracking with Redis caching
Document Cache Integration: Real-time configuration and validation
Event Hub Routing: Intelligent routing to multiple Event Hub destinations
Duplicate Prevention: Fired pixel tracking to prevent duplicate processing

🛠 Technology Stack

Component	Technology
Language	JavaScript (Node.js)
Runtime	Node.js Container
Framework	HTTP Server
Database	Azure Cosmos DB
Caching	Redis
Storage	Azure Blob Storage
Messaging	Azure Event Hub
Build Tool	Webpack
Container	Docker
Orchestration	Kubernetes

🏗 Architecture

Service Architecture

Deployment Pattern: Kubernetes Deployment with HTTP Service
Input: HTTP GET/POST requests with pixel data
Processing: Multi-stage validation and enrichment pipeline
Output: Routed events to multiple Event Hubs
Caching: Redis for session data and fired pixel tracking
Configuration: Real-time document cache for pixel configurations

System Flow

graph TD
    A[Pixel Request] --> B[PixelHandler Service]
    B --> C[Pixel Type Detection]
    C --> D[Document Cache Validation]
    D --> E[Session Cache Lookup]
    E --> F[Duplicate Check]
    F --> G{Valid Pixel?}
    G -->|No| H[Error Response]
    G -->|Yes| I[Event Enrichment]
    I --> J[Event Hub Routing]
    J --> K[Conversion Events]
    J --> L[Revenue Events]
    J --> M[Router Results]
    J --> N[Ad Requests]

🔄 Processing Pipeline

Pixel Processing Flow

graph LR
    A[HTTP Request] --> B[Pixel Type Detection]
    B --> C[Configuration Lookup]
    C --> D[Session Validation]
    D --> E[Duplicate Prevention]
    E --> F[Event Generation]
    F --> G[Event Hub Publishing]

Multi-Platform Integration

sequenceDiagram
    participant Client
    participant Handler as PixelHandler
    participant Cache as Document Cache
    participant Redis as Session Cache
    participant EventHub as Event Hubs

    Client->>Handler: Pixel Request
    Handler->>Handler: Detect Pixel Type
    Handler->>Cache: Get Configuration
    Cache-->>Handler: Pixel Config
    Handler->>Redis: Check Session/Duplicates
    Redis-->>Handler: Session Data
    Handler->>Handler: Process & Enrich
    Handler->>EventHub: Route to Appropriate Hub
    Handler-->>Client: Success Response

📡 API Specification

Supported Pixel Types

Conversion Pixels

PostbackGETConversion: GET-based conversion tracking
PostbackPOSTConversion: POST-based conversion tracking
FacebookConversion: Facebook conversion API integration
TikTokConversion: TikTok conversion tracking

Revenue Pixels

PostbackGETPayout/PostbackPOSTPayout: Standard revenue tracking
FacebookRevenue: Facebook revenue events
TikTokRevenue: TikTok revenue tracking
QwRevenueGET/QwRevenuePOST: QuoteWizard revenue events

Session Pixels

SessionAdPixel: Session-based ad tracking with cache integration
PostbackGETInitialize/PostbackPOSTInitialize: Session initialization

Request Examples

Conversion Pixel (GET)

GET /pixel?type=PostbackGETConversion&sessionId=abc123&conversionValue=100&campaignId=456

Revenue Pixel (POST)

POST /pixel
Content-Type: application/json

{
  "type": "FacebookRevenue",
  "sessionId": "abc123",
  "revenue": 25.50,
  "currency": "USD",
  "campaignId": "456"
}

Session Ad Pixel

POST /pixel
Content-Type: application/json

{
  "type": "SessionAdPixel",
  "sessionId": "abc123",
  "adData": {
    "placement": "header",
    "creative": "banner-001"
  }
}

Response Format

Success Response:

{
  "status": "success",
  "processed": true,
  "eventId": "event-123",
  "routedTo": "conversions"
}

Error Response:

{
  "status": "error",
  "message": "Invalid pixel configuration",
  "code": "INVALID_CONFIG"
}

🔧 Business Logic

Event Hub Routing Strategy

Events are routed to different Event Hubs based on pixel type:

conversions: Conversion tracking events
publisherrevenue: Publisher revenue events
unaccountedrevenue: Unaccounted revenue tracking
exchangerevenue: Exchange revenue events
routerresult: Router and session results
unauditedrevenue: Unaudited revenue events
revenueevents: General revenue events

Session Management

Session Cache: Redis-based session data storage
Session Validation: Ensures valid session context for ad pixels
Session Enrichment: Adds session-specific data to events

Duplicate Prevention

Fired Pixel Tracking: Prevents duplicate pixel processing
Unique Event IDs: Generates unique identifiers for each event
Cache-Based Deduplication: Uses Redis for duplicate detection

Configuration Management

Document Cache: Real-time pixel configuration retrieval
Dynamic Validation: Configuration-based pixel validation
Campaign Context: Campaign-specific pixel processing rules

⚙️ Configuration

Environment Variables

Redis Configuration: Connection strings and cache settings
Azure Cosmos DB: Database connection and container settings
Event Hub Settings: Multiple Event Hub connection strings
Blob Storage: Configuration and cache storage settings

Key Configuration Files

config/config.js: Main configuration
config/config.int.js: Integration environment
config/config.prod.js: Production environment

Pixel Type Configuration

Each pixel type defines:

{
  "type": "FacebookConversion",
  "action": "POST",
  "eventhub": "conversions",
  "needSessionCache": false,
  "postToAdRequest": false
}

🚀 Deployment

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Check deployment status
kubectl get pods -l app=pixelhandler

# View logs
kubectl logs -l app=pixelhandler -f

Local Development

# Install dependencies
npm install

# Run tests
npm test

# Start service
npm start

📊 Monitoring & Health Checks

Health Endpoints

Liveness: /live - Basic health check
Readiness: /ready - Service readiness check

Key Metrics to Monitor

Pixel processing rate by type
Event Hub publishing success rates
Redis cache hit/miss ratios
Document cache lookup performance
Duplicate pixel detection rate
Session validation success rate

Business Metrics

Conversion rates by platform
Revenue tracking accuracy
Session completion rates
Campaign performance metrics
Platform-specific pixel performance

🔧 Troubleshooting

Common Issues

Pixel Not Processing

Check pixel type configuration in document cache
Verify Event Hub connectivity for target hub
Validate session data in Redis cache
Check for duplicate pixel prevention

Session Cache Issues

# Check Redis connectivity
# Verify session data structure
# Monitor cache expiration settings

Event Hub Routing Failures

Verify Event Hub connection strings
Check Event Hub permissions and access
Monitor Event Hub capacity and throttling
Validate event payload structure

Configuration Problems

Missing Pixel Config: Check document cache for pixel type
Invalid Campaign: Verify campaign exists in cache
Session Validation: Ensure session data is properly cached

🧪 Testing

Unit Tests

npm test

Manual Testing

# Test conversion pixel
curl "http://localhost:8080/pixel?type=PostbackGETConversion&sessionId=test123"

# Test revenue pixel
curl -X POST -H "Content-Type: application/json" \
  -d '{"type":"FacebookRevenue","sessionId":"test123","revenue":25.50}' \
  "http://localhost:8080/pixel"

🤝 Dependencies

External Dependencies

Facebook Conversion API: Facebook pixel integration
TikTok Events API: TikTok pixel tracking
Redis: Session and duplicate tracking cache

Internal Dependencies

Document Cache Service: Pixel configuration management
Session Cache Service: Session data management
Router Result Service: Router integration
Ad Request Service: Ad request processing

NPM Dependencies

@redis/client: Redis integration
axios: HTTP client for external APIs
lodash: Utility functions
moment: Date/time handling
uuid: Unique identifier generation

This documentation was created through manual code analysis of the PixelHandler microservice codebase.