Mixpeek RTD (Real-Time Data) Adapter for Prebid.js

This is a Real-Time Data (RTD) module for Prebid.js that replaces cookie-based targeting with sub-100ms contextual signals.


---

What This Is

| Type | Status |
|------|--------|
| RTD Module (bid enrichment) | Supported |
| Bidder Adapter | Not a bidder |
| Analytics Adapter | Not analytics |
| Identity Module | Not identity |

SSPs and DSPs can immediately consume these signals via ortb2.site.content and ortb2Imp.ext.data without custom integration.

---

Who This Is For

- Publishers migrating off cookie-based targeting
- SSPs looking for contextual + adjacency signals
- DSPs pricing inventory using OpenRTB 2.6 context

Used in Mixpeek production demos and SSP pilots.

---

Why Use This

1. Ad Adjacency Awareness - Competitive separation, no repeat creatives
2. Privacy-First Contextual Targeting - No cookies, no user tracking
3. IAB Taxonomy Classification - Content categorization (v3.0)
4. Brand Safety Scoring - Real-time sentiment analysis
5. Multimodal Analysis - Text, image, video content understanding
6. Sub-100ms RTD Performance - Optimized for header bidding latency

Graceful Failure: If Mixpeek is unavailable or times out, auctions proceed normally. The module never blocks bid requests.

---

Minimal Setup (Copy-Paste Ready)

``javascript
import '@mixpeek/prebid'

pbjs.setConfig({
realTimeData: {
dataProviders: [{
name: 'mixpeek',
params: {
apiKey: 'YOUR_API_KEY',
collectionId: 'YOUR_COLLECTION_ID',
namespace: 'YOUR_NAMESPACE'
}
}]
}
})
`

That's it. The RTD module automatically enriches all bid requests.

---

Installation

`bash
npm install @mixpeek/prebid
`

Prerequisites

1. Mixpeek Account - Sign up at mixpeek.com
2. API Key - Generate in your Mixpeek dashboard
3. Collection - Create a collection with feature extractors
4. Namespace - Your namespace ID (format: ns_xxxxx)
5. Prebid.js - Version 6.0.0 or higher

---

Shadow Mode (Risk-Free Testing)

Deploy in observation mode first — zero auction impact:

`javascript
pbjs.setConfig({
realTimeData: {
auctionDelay: 0, // Don't delay auctions
dataProviders: [{
name: 'mixpeek',
waitForIt: false, // Don't wait for Mixpeek
params: {
apiKey: 'YOUR_API_KEY',
collectionId: 'YOUR_COLLECTION_ID',
namespace: 'YOUR_NAMESPACE',
debug: true // See what signals would be added
}
}]
}
})
`

Shadow mode lets you:
- Verify signals are being generated correctly
- Monitor latency in your environment
- Confirm no auction disruption
- Review ortb2 output before enabling

When ready, switch to production mode by setting waitForIt: true and auctionDelay: 250.

---

Full Configuration

`javascript
import '@mixpeek/prebid'

pbjs.setConfig({
realTimeData: {
auctionDelay: 250, // Max wait for contextual data (ms)
dataProviders: [{
name: 'mixpeek',
waitForIt: true, // Wait for Mixpeek before auction
params: {
// Required
apiKey: 'YOUR_API_KEY',
collectionId: 'YOUR_COLLECTION_ID',
namespace: 'YOUR_NAMESPACE', // e.g., 'ns_abc123'

// Optional
endpoint: 'https://api.mixpeek.com', // Default
mode: 'auto', // 'page', 'video', 'image', or 'auto'
timeout: 250, // API timeout in ms
cacheTTL: 300, // Cache TTL in seconds
enableCache: true, // Enable local caching
debug: false // Enable debug logging
}
}]
}
})

// Bids are automatically enriched with contextual data
pbjs.requestBids({
adUnits: [...],
bidsBackHandler: function(bids) {
// Bids now include Mixpeek contextual data in ortb2
}
})
`

---

Ad Adjacency Awareness (Key Feature)

The adapter automatically tracks previously served ads to enable:

- Competitive Separation - Avoid showing competing brands consecutively
- Creative Frequency - Prevent the same ad from showing repeatedly
- Category Diversity - Improve ad variety for better user experience

$3

`javascript
// Data automatically injected into ortb2Imp.ext.data:
{
"hb_mixpeek_prev_creative": "12345", // Last creative ID
"hb_mixpeek_prev_bidder": "appnexus", // Last winning bidder
"hb_mixpeek_prev_adunit": "sidebar-1", // Last ad unit
"hb_mixpeek_prev_cat": "IAB18-1,IAB12-3" // Last ad categories
}

// DSP can use for competitive separation:
if (prevCategories.includes('IAB18-1') && currentAd.category === 'IAB18-1') {
// Don't show competing fashion ads back-to-back
}
`

$3

- No user tracking or identifiers
- Only ad metadata stored (< 200 bytes)
- Session-scoped, localStorage with memory fallback
- GDPR/CCPA compliant (contextual, not behavioral)

---

OpenRTB 2.6 Output

$3

`javascript
{
"site": {
"content": {
"cat": ["IAB19-11"], // IAB Content Categories
"cattax": 6, // IAB Taxonomy v3.0
"genre": "Technology", // Human-readable category
"keywords": "ai,technology,ml", // Extracted keywords
"language": "en", // Content language
"ext": {
"data": {
"mixpeek": {
"score": 0.94, // Classification confidence
"brandSafety": 0.98, // Brand safety score
"sentiment": "positive" // Content sentiment
}
}
}
}
}
}
`

$3

| Key | Description | Example |
|-----|-------------|---------|
| hb_mixpeek_category | Content category | "Technology" |
| hb_mixpeek_score | Classification confidence | "0.94" |
| hb_mixpeek_safety | Brand safety score | "0.98" |
| hb_mixpeek_keywords | Extracted keywords | "AI,ML,tech" |
| hb_mixpeek_sentiment | Content sentiment | "positive" |
| hb_mixpeek_prev_creative | Last creative ID | "12345" |
| hb_mixpeek_prev_bidder | Last winning bidder | "appnexus" |
| hb_mixpeek_prev_cat | Last ad categories | "IAB18-1" |

---

How It Works

`
USER → WEBSITE → PREBID.JS
│
├──→ MIXPEEK RTD Module
│ (Extract page content)
│ (Get previous ad info)
│ ↓
│ Returns: categories, keywords, sentiment
│ ↓
(enrich bid request with ortb2)
│
├──→ SSP 1 ──→ DSPs (use contextual signals)
├──→ SSP 2 ──→ DSPs (use adjacency data)
└──→ SSP N

(collect bids)
│
▼
AD SERVER
│
▼
RELEVANT AD
`

---

Content Modes

$3

`javascript
params: {
mode: 'page', // Analyze article/page content
// ...
}
`

$3

`javascript
params: {
mode: 'video',
videoSelector: '#main-video', // CSS selector
// ...
}
`

$3

`javascript
params: {
mode: 'auto', // Automatically detect content type
// ...
}
`

---

Event Callbacks

`javascript
// Context ready
pbjs.onEvent('mixpeekContextReady', function(context) {
console.log('Category:', context.taxonomy?.label)
console.log('Keywords:', context.keywords)
})

// Error handling
pbjs.onEvent('mixpeekContextError', function(error) {
// Errors don't block auction (graceful degradation)
console.error('Mixpeek error:', error)
})

// Cache hit
pbjs.onEvent('mixpeekContextCached', function(data) {
console.log('Using cached context')
})
`

---

Testing

`bash


Run all tests

npm test

Run with live API (requires credentials)

MIXPEEK_API_KEY=your_key \
MIXPEEK_NAMESPACE=ns_xxxxx \
MIXPEEK_COLLECTION_ID=col_xxxxx \
npm run test:live

Coverage report

npm run test:coverage
``

---

Documentation

- Quick Start - Get running in 5 minutes
- Integration Guide - Step-by-step setup
- API Reference - Complete API docs
- Testing Guide - How to test the adapter

---

Support

- Documentation: docs.mixpeek.com
- GitHub Issues: Create an issue
- Email: support@mixpeek.com

---

License

Apache 2.0 - see LICENSE

Built by Mixpeek | Integrates with Prebid.js