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)

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

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:

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

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

How SSPs/DSPs Use It

// 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
}

Privacy Safe

• 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

Site-Level Data (ortb2.site.content)

{
  "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
          }
        }
      }
    }
  }
}

Impression-Level Keys (ortb2Imp.ext.data)

| 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

Page Context (Default)

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

Video Context

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

Auto-Detection

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

Event Callbacks

// 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

# 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: [email protected]

License

Apache 2.0 - see LICENSE

Built by Mixpeek | Integrates with Prebid.js