Features Overview

Feature documentation for OpenAdServe. Covers analytics, CTR optimization, inventory forecasting, programmatic demand, and more.

Core Features

📊 Real-Time Analytics

ClickHouse-powered event tracking with sub-second latency. Track impressions, clicks, custom events, and ad requests with registered dimension indexing.

View documentation →

Status: ✅ Stable, Production Ready

🎯 CTR Optimization

Machine learning-based click-through rate prediction for CPC campaigns. Bayesian estimation with historical learning and eCPM boosting.

View documentation →

Status: ✅ Stable, Production Ready

🔗 Custom Events

Flexible server-to-server event tracking beyond impressions and clicks. Track video views, engagement metrics, and custom interactions.

View documentation →

Status: ✅ Stable, Production Ready

🖱️ Click URL Macros

Customizable click-through URLs with macro substitution for dynamic values. Integrate with advertiser tracking systems seamlessly.

View documentation →

Status: ✅ Stable, Production Ready

Advanced Features

📈 Inventory Forecasting

Predict available impressions for potential line items with bid-aware conflict detection and priority-based preemption modeling.

View documentation →

Status: ⚠️ Beta - Use as rough estimates

💱 Programmatic Demand

Header bidding and RTB integration with OpenRTB-compatible bid requests. Unified auction with eCPM normalization.

View documentation →

Status: ⚠️ Beta - Limited DSP testing

🧪 Synthetic Data

Generate realistic test data for development. Create demo campaigns, line items, and simulated traffic for load testing.

View documentation →

Status: 🔧 Dev Tool Only

Feature Highlights

Analytics & Reporting

Real-time campaign performance tracking with powerful querying.

Event Tracking
Registered Dimensions
Campaign Reports

Track everything:

✅ Impressions with full request context
✅ Clicks with referrer and timestamp
✅ Custom events (video views, engagement, conversions)
✅ Ad requests for fill rate analysis

Storage: ClickHouse with automatic partitioning and retention

Learn more →

Optimize analytics with indexed columns:

✅ Type validation (enum, number, string)
✅ Fast aggregation queries (10x+ speedup)
✅ Automatic report generation
✅ Custom dimension registration

Example: content_category, user_segment, device_tier

Learn more →

CTR Optimization

Maximize revenue from CPC campaigns with machine learning.

How It Works

1. Historical Learning: Query past performance from ClickHouse to calculate actual CTR per line item.

2. Bayesian Estimation: Blend historical CTR with baseline CTR using configurable smoothing weights.

3. eCPM Boosting: Convert CPC bids to eCPM using predicted CTR: eCPM = CPC × CTR × 1,000

4. Competitive Ranking: CPC campaigns compete fairly with CPM campaigns in unified auction.

Configuration:

BASELINE_CTR=0.01          # 1% fallback CTR
CTR_SMOOTHING_WEIGHT=10    # Weight for Bayesian smoothing

Read full documentation →

Inventory Forecasting

Predict available impressions for potential line items.

Beta Feature

The forecasting algorithm needs revision and should be used for rough planning estimates only. See known limitations.

What it does:

✅ Analyzes 30 days of historical traffic patterns
✅ Detects conflicts with existing campaigns
✅ Filters same-priority conflicts by eCPM threshold (10%)
✅ Estimates inventory reduction from higher-priority competition
✅ Supports CPM and CPC campaigns with eCPM normalization

What it doesn't do:

❌ Simulate rate limiting or frequency caps
❌ Predict when budget-exhausted campaigns stop competing
❌ Use actual CTR prediction for CPC eCPM (uses static 1%)
❌ Calculate precise targeting overlap percentages

Use case: Planning campaign capacity and identifying potential delivery issues before launch.

Read full documentation →

Programmatic Integration

Connect to header bidding and RTB demand sources.

OpenRTB Compatible

Send OpenRTB-formatted bid requests to programmatic demand sources with automatic request/response parsing.

Unified Auction

Programmatic bids compete with direct campaigns using eCPM normalization. Priority-based ranking ensures guaranteed delivery.

Timeout Handling

Configurable bid request timeouts with automatic fallback to direct campaigns when programmatic doesn't respond.

Line item configuration:

{
  "line_item_type": "programmatic",
  "programmatic_config": {
    "bidder_endpoint": "https://bidder.example.com/bid",
    "timeout_ms": 100
  }
}

Read full documentation →

Feature Maturity Matrix

Feature	Status	Production Ready	Notes
Analytics	✅ Stable	Yes	ClickHouse integration tested at scale
CTR Optimization	✅ Stable	Yes	Bayesian estimation with proven accuracy
Custom Events	✅ Stable	Yes	Flexible tracking for any event type
Click URL Macros	✅ Stable	Yes	Macro substitution and validation
Forecasting	⚠️ Beta	No	Algorithm needs revision - rough estimates only
Programmatic	⚠️ Beta	Yes	OpenRTB compatible, limited DSP testing
Synthetic Data	🔧 Dev Tool	No	Internal testing and demo purposes only

Quick Setup Workflows

Set Up Real-Time Analytics

Step-by-step guide

Configure ClickHouse connection
```
CLICKHOUSE_URL=http://clickhouse:8123
```

Enable dimension registration (optional)

# config/dimensions.yaml
dimensions:
  - name: content_category
    type: enum
    values: [sports, news, tech]
    indexed: true

Generate demo data for testing

docker compose exec openadserve go run ./tools/fake_data

Run campaign reports

go run ./tools/campaign_report -campaign-id=1 -days=7

Set up Grafana dashboards Import pre-built dashboards from config/grafana/

Full analytics guide →

Enable CTR Optimization for CPC

Step-by-step guide

Configure baseline CTR

BASELINE_CTR=0.01
CTR_SMOOTHING_WEIGHT=10

Create CPC line items Set budget_type: "CPC" and provide cpc_bid
Generate traffic
```
go run ./tools/traffic_simulator
```
Monitor eCPM calculations Check logs for CTR predictions and eCPM boosting

Full CTR optimization guide →

Forecast Inventory Availability

Step-by-step guide

Configure line item targeting Define targeting criteria for forecast request

Send forecast request

POST /forecast
{
  "publisher_id": 1,
  "placement_id": 1,
  "targeting": {...},
  "flight_dates": {...}
}

Analyze conflict detection Review detected competing line items
Review availability estimates Use forecasted impression counts for planning

Full forecasting guide →

Integrate Programmatic Demand

Step-by-step guide

Configure programmatic line items

{
  "line_item_type": "programmatic",
  "programmatic_config": {
    "bidder_endpoint": "https://bidder.com/bid"
  }
}

Set bidder endpoint URLs Configure DSP/SSP endpoints
Test bid responses Send test requests and validate parsing
Monitor bid performance Track win rates and eCPM in analytics

Full programmatic guide →

Track Custom Engagement Events

Step-by-step guide

Generate event tokens Include event_url in ad response for custom tracking

Send S2S event requests

GET /event?token={signed_token}&type={event_type}

Query events in ClickHouse

SELECT * FROM events WHERE event_type = 'video_complete'

Build custom reports Aggregate events by line item, campaign, or custom dimensions

Full custom events guide →

Feature Dependencies

Understanding how features interact with core systems:

Analytics

Required: ClickHouse for event storage
Optional: Redis for real-time counters (graceful degradation)
Optional: Dimension registration for indexed columns

CTR Optimization

Required: Analytics with historical click/impression data
Required: ClickHouse for CTR calculations
Applies to: CPC line items only

Forecasting

Required: Analytics with 30-day historical data
Required: ClickHouse for traffic pattern queries
Required: PostgreSQL for active line item config

Programmatic

Required: External bidder endpoints
Required: Network access for HTTP requests
Optional: Timeout configuration tuning

Publisher-First Design Philosophy

These features reflect OpenAdServe's core principles:

Quality Over Quantity:

Ad reporting for user-facing quality control
Rate limiting to protect from budget exhaustion
Pacing for even delivery and budget preservation

Transparency and Control:

Forecasting with bid-aware conflict visibility
Real-time analytics for performance insights
Custom events for tracking what matters to you

Performance and Reliability:

CTR optimization maximizes CPC revenue
Single-pass filtering for 3x faster decisioning
Graceful degradation keeps serving ads

🏗️ Architecture

Learn how features integrate with the core ad decisioning engine and data stores.

View architecture →

🔌 API Reference

HTTP endpoints, request/response formats, and integration patterns for all features.

View API docs →

⚙️ Configuration

Environment variables, tuning parameters, and deployment settings for feature optimization.

View configuration →

📋 Trafficking

Campaign management, line item creation, and creative setup workflows.

View trafficking guide →

Core Features​

📊 Real-Time Analytics

🎯 CTR Optimization

🔗 Custom Events

🖱️ Click URL Macros

Advanced Features​

📈 Inventory Forecasting

💱 Programmatic Demand

🧪 Synthetic Data

Feature Highlights​

Analytics & Reporting​

CTR Optimization​

How It Works

Inventory Forecasting​

Programmatic Integration​

OpenRTB Compatible

Unified Auction

Timeout Handling

Feature Maturity Matrix​

Quick Setup Workflows​

Set Up Real-Time Analytics​

Enable CTR Optimization for CPC​

Forecast Inventory Availability​

Integrate Programmatic Demand​

Track Custom Engagement Events​

Feature Dependencies​

Analytics​

CTR Optimization​

Forecasting​

Programmatic​

Publisher-First Design Philosophy​

Related Documentation​

🏗️ Architecture

🔌 API Reference

⚙️ Configuration

📋 Trafficking

Core Features

Advanced Features

Feature Highlights

Analytics & Reporting

CTR Optimization

Inventory Forecasting

Programmatic Integration

Feature Maturity Matrix

Quick Setup Workflows

Set Up Real-Time Analytics

Enable CTR Optimization for CPC

Forecast Inventory Availability

Integrate Programmatic Demand

Track Custom Engagement Events

Feature Dependencies

Analytics

CTR Optimization

Forecasting

Programmatic

Publisher-First Design Philosophy

Related Documentation