@mixpeek/prebid 1.0.0

package/docs/MIGRATION_V2.md

@@ -0,0 +1,519 @@
+# Migration Guide: v1 → v2 (RTD Module)
+
+> 🔄 **Breaking Changes:** Version 2.0 introduces a proper Prebid RTD submodule structure  
+> 📅 **Release Date:** TBD  
+> ⏱️ **Migration Time:** ~15-30 minutes
+
+---
+
+## What's Changing?
+
+Version 2.0 restructures the Mixpeek adapter to follow Prebid's official Real-Time Data (RTD) module pattern, matching how modules like **Qortex** and **Rayn** work.
+
+### Key Changes
+
+1. **Configuration Structure** - New `realTimeData.dataProviders[]` pattern
+2. **Module Registration** - Now a proper RTD submodule
+3. **Data Format** - Enhanced `ortb2.site.content` injection
+4. **IAB Mapping** - Built-in IAB Content Taxonomy v3.0 support
+
+---
+
+## Quick Migration Checklist
+
+- [ ] Update configuration from `mixpeek: {}` to `realTimeData.dataProviders[]`
+- [ ] Add `auctionDelay` parameter
+- [ ] Add `waitForIt` flag
+- [ ] Move all params inside `params:` object
+- [ ] Test with debug mode enabled
+- [ ] Verify `ortb2.site.content` is populated
+- [ ] Update IAB mapping with your taxonomy's node_ids (optional)
+- [ ] Update tests if using the adapter
+
+---
+
+## Configuration Migration
+
+### v1 (Old) ❌
+```javascript
+pbjs.setConfig({
+  mixpeek: {
+    apiKey: 'sk_your_api_key',
+    collectionId: 'col_your_collection',
+    endpoint: 'https://server-xb24.onrender.com',
+    namespace: 'production',
+    featureExtractors: ['taxonomy', 'brand-safety'],
+    mode: 'auto',
+    timeout: 250,
+    cacheTTL: 300,
+    enableCache: true,
+    debug: false
+  }
+})
+```
+
+### v2 (New) ✅
+```javascript
+pbjs.setConfig({
+  realTimeData: {
+    auctionDelay: 250,  // NEW: Max time to wait for RTD providers
+    dataProviders: [{   // NEW: Array of RTD providers
+      name: 'mixpeek',  // NEW: Provider name
+      waitForIt: true,  // NEW: Wait for this provider
+      params: {         // NEW: Wrap all config in params
+        apiKey: 'sk_your_api_key',
+        collectionId: 'col_your_collection',
+        endpoint: 'https://server-xb24.onrender.com',
+        namespace: 'production',
+        featureExtractors: ['taxonomy', 'brand-safety'],
+        mode: 'auto',
+        timeout: 250,
+        cacheTTL: 300,
+        enableCache: true,
+        debug: false
+      }
+    }]
+  }
+})
+```
+
+---
+
+## Detailed Migration Steps
+
+### Step 1: Update Configuration Structure
+
+**Before (v1):**
+```javascript
+pbjs.setConfig({
+  mixpeek: { /* config */ }
+})
+```
+
+**After (v2):**
+```javascript
+pbjs.setConfig({
+  realTimeData: {
+    auctionDelay: 250,
+    dataProviders: [{
+      name: 'mixpeek',
+      waitForIt: true,
+      params: { /* config */ }
+    }]
+  }
+})
+```
+
+**Changes:**
+1. Replace `mixpeek: {}` with `realTimeData: {}`
+2. Add `auctionDelay` at top level
+3. Add `dataProviders` array
+4. Wrap config in `params: {}`
+
+### Step 2: Add New RTD Parameters
+
+Add these new parameters to control RTD behavior:
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `auctionDelay` | number | ❌ | 250 | Max time (ms) to wait for all RTD providers |
+| `name` | string | ✅ | - | Must be `'mixpeek'` |
+| `waitForIt` | boolean | ❌ | false | Whether to wait for this provider |
+
+**Example:**
+```javascript
+realTimeData: {
+  auctionDelay: 300,  // Wait up to 300ms for RTD data
+  dataProviders: [{
+    name: 'mixpeek',     // Required
+    waitForIt: true,     // Wait for Mixpeek
+    params: { /* ... */ }
+  }]
+}
+```
+
+### Step 3: Move All Config to `params`
+
+All your existing Mixpeek configuration goes inside the `params` object:
+
+```javascript
+params: {
+  // All your existing config
+  apiKey: 'sk_...',
+  collectionId: 'col_...',
+  endpoint: '...',
+  // etc.
+}
+```
+
+### Step 4: Update Multiple RTD Providers (if applicable)
+
+If you're using multiple RTD providers (e.g., with ID5 or RampID):
+
+**Before (v1):**
+```javascript
+pbjs.setConfig({
+  mixpeek: { /* ... */ }
+})
+
+// Separate config for ID5
+pbjs.setConfig({
+  userId: {
+    auctionDelay: 50,
+    userIds: [{
+      name: 'id5Id',
+      params: { /* ... */ }
+    }]
+  }
+})
+```
+
+**After (v2):**
+```javascript
+pbjs.setConfig({
+  realTimeData: {
+    auctionDelay: 300,  // Combined delay for all RTD providers
+    dataProviders: [
+      {
+        name: 'mixpeek',
+        waitForIt: true,
+        params: { /* Mixpeek config */ }
+      },
+      {
+        name: 'id5',
+        waitForIt: true,
+        params: { /* ID5 config */ }
+      }
+    ]
+  }
+})
+```
+
+---
+
+## What's New in v2
+
+### 1. Enhanced ortb2 Data Structure ✨
+
+v2 now injects data into **both** site-level and impression-level locations:
+
+**Site-Level (`ortb2.site.content`):**
+```javascript
+{
+  "ortb2": {
+    "site": {
+      "content": {
+        "cat": ["IAB19-11"],        // NEW: IAB categories
+        "cattax": 6,                 // NEW: Taxonomy version
+        "genre": "Technology - AI",  // NEW: Genre
+        "keywords": "ai,tech",       // NEW: Keywords
+        "language": "en",            // NEW: Language
+        "title": "Page Title",       // NEW: Title
+        "url": "https://...",        // NEW: URL
+        "ext": {                     // NEW: Extension data
+          "data": {
+            "mixpeek": {
+              "score": 0.94,
+              "brandSafety": 0.98,
+              "sentiment": "positive"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Impression-Level (`ortb2Imp.ext.data`):**
+```javascript
+{
+  "hb_mixpeek_taxonomy": "IAB19-11",
+  "hb_mixpeek_category": "Technology > AI",
+  // ... same as v1
+}
+```
+
+### 2. Built-in IAB Mapping 🗺️
+
+v2 includes IAB Content Taxonomy v3.0 mapping:
+
+- Maps Mixpeek's `node_id` to IAB codes
+- Multiple fallback strategies
+- Configurable mappings
+
+See `src/utils/iabMapping.js` for details.
+
+### 3. Consent Management Integration 🔒
+
+v2 properly integrates with Prebid's consent framework:
+
+```javascript
+// Automatically receives and logs consent
+init: function(config, userConsent) {
+  // userConsent includes GDPR and USP data
+}
+```
+
+### 4. Standard RTD Interface 🔌
+
+v2 implements Prebid's official RTD submodule interface:
+
+- `init()` - Initialize with consent
+- `getBidRequestData()` - Enrich bid requests
+- `getTargetingData()` - Provide targeting keys
+
+---
+
+## Testing Your Migration
+
+### 1. Enable Debug Mode
+
+```javascript
+realTimeData: {
+  auctionDelay: 250,
+  dataProviders: [{
+    name: 'mixpeek',
+    waitForIt: true,
+    params: {
+      apiKey: 'sk_...',
+      collectionId: 'col_...',
+      debug: true  // Enable debug logging
+    }
+  }]
+}
+```
+
+### 2. Check Console Logs
+
+Look for these messages:
+
+```
+[mixpeek] Initializing Mixpeek RTD module
+[mixpeek] getBidRequestData called
+[mixpeek] Context retrieved successfully
+[mixpeek] Injected site.content data
+[mixpeek] Enriched 3 ad units
+```
+
+### 3. Verify ortb2 Data
+
+Inspect the bid request:
+
+```javascript
+pbjs.onEvent('beforeRequestBids', function(bidRequest) {
+  console.log('ortb2 site.content:', 
+    bidRequest.ortb2Fragments?.global?.site?.content)
+  
+  console.log('Ad unit enrichment:', 
+    bidRequest.adUnits[0]?.ortb2Imp?.ext?.data)
+})
+```
+
+### 4. Verify Auction Not Blocked
+
+Check that auctions aren't delayed unnecessarily:
+
+```javascript
+const startTime = Date.now()
+
+pbjs.requestBids({
+  bidsBackHandler: function() {
+    const duration = Date.now() - startTime
+    console.log(`Auction completed in ${duration}ms`)
+    // Should be ~250-500ms depending on API latency
+  }
+})
+```
+
+---
+
+## Common Migration Issues
+
+### Issue 1: "Module not found" or Silent Failure
+
+**Symptoms:**
+- No logs in console
+- No context enrichment
+- No errors
+
+**Cause:** Configuration not properly structured
+
+**Solution:**
+```javascript
+// Make sure you have this exact structure
+pbjs.setConfig({
+  realTimeData: {            // Must be "realTimeData"
+    dataProviders: [{         // Must be array
+      name: 'mixpeek',        // Must be exactly 'mixpeek'
+      params: { /* ... */ }   // Must have params object
+    }]
+  }
+})
+```
+
+### Issue 2: Auction Blocked Too Long
+
+**Symptoms:**
+- Auctions taking > 500ms
+- Timeout errors
+
+**Cause:** `auctionDelay` too high or API too slow
+
+**Solution:**
+```javascript
+realTimeData: {
+  auctionDelay: 200,  // Reduce delay
+  dataProviders: [{
+    name: 'mixpeek',
+    waitForIt: false,  // Don't wait if API is slow
+    params: {
+      timeout: 150     // Reduce API timeout
+    }
+  }]
+}
+```
+
+### Issue 3: No ortb2.site.content Data
+
+**Symptoms:**
+- `ortb2Imp.ext.data` populated
+- `ortb2.site.content` missing
+
+**Cause:** Using v1 module
+
+**Solution:** Ensure you're loading the v2 RTD provider module, not the v1 adapter.
+
+### Issue 4: IAB Codes Not Showing
+
+**Symptoms:**
+- Context data present
+- No IAB codes in `ortb2.site.content.cat`
+
+**Cause:** Mixpeek taxonomy not mapped
+
+**Solution:**
+1. Run E2E tests to discover your node_ids:
+   ```bash
+   npm run test:e2e
+   ```
+2. Update `src/utils/iabMapping.js` with your mappings:
+   ```javascript
+   export const MIXPEEK_NODE_TO_IAB = {
+     'your_node_id': 'IAB19-11',
+     // ... add your mappings
+   }
+   ```
+
+---
+
+## Rollback Plan
+
+If you need to rollback to v1:
+
+### 1. Revert Configuration
+
+```javascript
+// Back to v1 format
+pbjs.setConfig({
+  mixpeek: {
+    apiKey: 'sk_...',
+    collectionId: 'col_...',
+    // ... v1 config
+  }
+})
+```
+
+### 2. Revert Package
+
+```bash
+npm install @mixpeek/prebid-contextual-adapter@1.x
+```
+
+### 3. Clear Cache
+
+```bash
+# Clear browser cache
+# Or programmatically:
+window.MixpeekContextAdapter.clearCache()
+```
+
+---
+
+## Breaking Changes Summary
+
+| Change | v1 | v2 | Required Action |
+|--------|----|----|----------------|
+| **Config structure** | `mixpeek: {}` | `realTimeData.dataProviders[]` | Update config |
+| **Module type** | Custom hooks | RTD submodule | No code change |
+| **ortb2 location** | Imp-level only | Site + Imp level | Verify bidders receive data |
+| **Consent** | Not handled | Integrated | Test with GDPR/USP |
+| **IAB mapping** | Manual | Built-in | Optional: configure mappings |
+
+---
+
+## Benefits of Migrating
+
+✅ **Standard Pattern** - Follows official Prebid RTD structure  
+✅ **Better Integration** - Works with other RTD modules  
+✅ **Enhanced Data** - ortb2.site.content for DSPs  
+✅ **IAB Compliant** - Built-in taxonomy mapping  
+✅ **Consent Aware** - Respects GDPR/USP  
+✅ **Future Proof** - Ready for Prebid repository submission  
+
+---
+
+## Timeline
+
+### Deprecation Schedule
+
+- **v2.0 Release:** TBD
+- **v1 Support:** 6 months after v2 release
+- **v1 End of Life:** 12 months after v2 release
+
+### Recommended Migration Timeline
+
+- **Weeks 1-2:** Test v2 in staging environment
+- **Week 3:** Gradual rollout to 10% of traffic
+- **Week 4:** Rollout to 50% of traffic
+- **Week 5:** Full production rollout
+- **Week 6+:** Monitor and optimize
+
+---
+
+## Support
+
+Need help with migration?
+
+- **Documentation:** [Full Integration Guide](integration-guide.md)
+- **Examples:** See `examples/` directory
+- **Issues:** [GitHub Issues](https://github.com/mixpeek/prebid-contextual-adapter/issues)
+- **Email:** support@mixpeek.com
+- **Slack:** [Join our Slack](https://mixpeek.com/slack)
+
+---
+
+## FAQ
+
+### Do I need to update my API key?
+No, existing API keys work with v2.
+
+### Will my existing collection work?
+Yes, collections are fully compatible.
+
+### Do I need to change my ad units?
+No, ad unit configuration remains the same.
+
+### What about caching?
+Caching works the same way in v2.
+
+### Can I run v1 and v2 simultaneously?
+No, only one version should be active at a time.
+
+### Do I need to update my tests?
+Yes, if your tests reference the old configuration format.
+
+---
+
+**Ready to migrate?** Follow the steps above and you'll be running v2 in no time! 🚀
+