Header Bidding

WATERFALL (old way):
  "I have one ticket to sell. I'll ask my friend first.
   He offers $5. Sold. My other friend would have paid $20 — too bad."

HEADER BIDDING (new way):
  "I have one ticket to sell. I'll text all 10 friends at once
   and give them 90 seconds to reply with their best offer.
   The highest reply wins. I get $20 instead of $5."

var adUnits = [
  {
    code: 'div-gpt-ad-leaderboard',       // must match GPT slot div ID exactly
    mediaTypes: {
      banner: { sizes: [[728,90], [970,90], [970,250]] }
    },
    bids: [
      { bidder: 'appnexus', params: { placementId: 12345678 } },
      { bidder: 'rubicon',  params: { accountId: 9001, siteId: 283, zoneId: 1234 } },
      { bidder: 'ix',       params: { siteId: '47777', size: [728,90] } },
      { bidder: 'pubmatic', params: { publisherId: '158355', adSlot: 'hb-leaderboard@728x90' } },
      { bidder: 'openx',   params: { unit: '540191387', delDomain: 'pub.openx.net' } }
    ]
  },
  {
    code: 'div-gpt-ad-mrec',
    mediaTypes: {
      banner: { sizes: [[300,250], [300,600]] }
    },
    bids: [
      { bidder: 'appnexus', params: { placementId: 87654321 } },
      { bidder: 'rubicon',  params: { accountId: 9001, siteId: 283, zoneId: 5678 } }
    ]
  },
  {
    code: 'div-gpt-ad-video',
    mediaTypes: {
      video: {
        context: 'instream',
        playerSize: [[640, 480]],
        mimes: ['video/mp4'],
        protocols: [2, 3, 5, 6, 7, 8],
        playbackmethod: [2],
        skip: 1,
        skipafter: 5
      }
    },
    bids: [
      { bidder: 'appnexus', params: { placementId: 11223344, video: { skippable: true } } }
    ]
  }
];

pbjs.setConfig({
  bidderTimeout: 1500,
  enableSendAllBids: false,                    // one winner per slot — cleaner GAM targeting

  priceGranularity: {
    buckets: [
      { max: 3,   increment: 0.05 },    // fine buckets where most bids land
      { max: 8,   increment: 0.10 },
      { max: 20,  increment: 0.25 },
      { max: 100, increment: 1.00 }
    ]
  },

  userSync: {
    syncEnabled: true,
    filterSettings: {
      iframe: { bidders: ['appnexus', 'rubicon'], filter: 'include' },
      image:  { bidders: '*',                             filter: 'include' }
    },
    syncsPerBidder: 5,
    syncDelay: 3000
  },

  currency: { adServerCurrency: 'USD' },

  schain: {
    validation: 'strict',
    config: {
      ver: '1.0', complete: 1,
      nodes: [{ asi: 'your-exchange.com', sid: 'pub-001', hp: 1 }]
    }
  },

  consentManagement: {                               // GDPR / TCF integration
    gdpr: {
      cmpApi: 'iab',                              // reads from window.__tcfapi
      timeout: 10000,                            // ms to wait for CMP before continuing
      allowAuctionWithoutConsent: false          // do NOT run auction if no consent signal
    },
    usp: { cmpApi: 'iab', timeout: 1000 }   // CCPA
  }
});

var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];
var pbjs = pbjs || {};
pbjs.que = pbjs.que || [];

// Define GPT slots — these are the ad unit paths in your GAM network
googletag.cmd.push(function() {
  googletag.defineSlot('/12345/homepage-leaderboard', [[728,90],[970,90]], 'div-gpt-ad-leaderboard')
    .addService(googletag.pubads());
  googletag.defineSlot('/12345/homepage-mrec', [[300,250],[300,600]], 'div-gpt-ad-mrec')
    .addService(googletag.pubads());

  googletag.pubads().disableInitialLoad();   // prevent GPT from loading ads before Prebid runs
  googletag.pubads().enableSingleRequest();
  googletag.enableServices();
});

// Prebid configuration and auction
pbjs.que.push(function() {
  pbjs.setConfig({ /* ...setConfig as above... */ });
  pbjs.addAdUnits(adUnits);

  pbjs.requestBids({
    timeout: 1500,
    bidsBackHandler: function() {
      pbjs.setTargetingForGPTAsync();        // write hb_pb, hb_bidder, hb_adid to GPT slots
      googletag.cmd.push(function() {
        googletag.pubads().refresh();        // fire GAM ad request with key-values attached
      });
    }
  });
});

// === Useful console commands for QA ===
// pbjs.getBidResponses()          — all bids per ad unit (bid, no-bid, timeout)
// pbjs.getHighestCpmBids()        — winning bid per ad unit
// pbjs.getAdserverTargeting()     — key-values written to each GPT slot
// pbjs.getAllWinningBids()        — bids that won AND rendered

POST https://prebid-server.example.com/openrtb2/auction
Content-Type: application/json

{
  "id": "auction-ctv-001",
  "tmax": 1000,
  "imp": [
    {
      "id": "1",
      "video": {
        "mimes": ["video/mp4"],
        "protocols": [2, 3, 5, 6],
        "w": 1920, "h": 1080,
        "startdelay": 0,                       // 0 = pre-roll
        "playbackmethod": [2],
        "skip": 1, "skipafter": 5
      },
      "bidfloor": 5.00,
      "bidfloorcur": "USD",
      "ext": {
        "prebid": {
          "bidder": {                               // per-bidder params — replaces Prebid.js adapter config
            "appnexus": { "placementId": 11223344 },
            "rubicon":   { "accountId": 9001, "siteId": 283, "zoneId": 9999 },
            "ix":        { "siteId": "47777" }
          },
          "storedAuctionResponse": "stored-resp-001"   // optional: use cached test response for dev
        }
      }
    }
  ],
  "app": {
    "bundle": "com.example.ctvapp",
    "name": "Example CTV",
    "storeurl": "https://channelstore.roku.com/details/123",
    "publisher": { "id": "pub-456" }
  },
  "device": {
    "ua": "Roku/DVP-9.10 (519.10E04142A)",
    "devicetype": 3,                             // 3 = Connected TV / SmartTV
    "ifa": "aebe0a86-1f3a-4c65-b2bc-4f7b9c4e9d01",  // device advertising ID (RIDA on Roku)
    "lmt": 0,                                    // Limit Ad Tracking: 0 = not limited
    "geo": { "country": "USA", "region": "CA" }
  },
  "user": {
    "ext": {
      "eids": [
        {
          "source": "liveramp.com",
          "uids": [{ "id": "RampID-abc123", "atype": 3 }]
        }
      ]
    }
  },
  "regs": { "coppa": 0, "ext": { "gdpr": 0, "us_privacy": "1YNN" } }
}

{
  "id": "auction-ctv-002",
  "imp": [
    {
      "id": "1",
      "ext": {
        "prebid": {
          "storedrequest": { "id": "ctv-preroll-720" }
          // PBS looks up "ctv-preroll-720" from its database and merges
          // the stored bidder config, floor, and media type definition
        }
      }
    }
  ],
  "app": { "bundle": "com.example.ctvapp" },
  "device": { "devicetype": 3, "ifa": "aebe0a86-..." }
  // Bidder params, video sizes, floors etc. come from the stored request template
}

import { registerBidder } from '../src/adapters/bidderFactory.js';
import { BANNER, VIDEO } from '../src/mediaTypes.js';
import { deepAccess, logWarn } from '../src/utils.js';

const BIDDER_CODE    = 'mybidder';
const ENDPOINT_URL   = 'https://bid.mybidder.example.com/openrtb2/auction';
const SYNC_URL       = 'https://sync.mybidder.example.com/usersync';
const SUPPORTED_MEDIA = [BANNER, VIDEO];

export const spec = {
  code: BIDDER_CODE,
  supportedMediaTypes: SUPPORTED_MEDIA,

  // ── 1. Validate params before the auction ──────────────────────────────
  isBidRequestValid: function(bid) {
    if (!bid.params || !bid.params.placementId) {
      logWarn(`[mybidder] missing required param: placementId on bid `, bid);
      return false;
    }
    return true;
  },

  // ── 2. Build the HTTP request to send to your SSP ─────────────────────
  buildRequests: function(validBidRequests, bidderRequest) {
    const gdpr    = bidderRequest.gdprConsent;
    const usp     = bidderRequest.uspConsent;
    const referer = deepAccess(bidderRequest, 'refererInfo.page') || '';

    const openRtbRequest = {
      id: bidderRequest.auctionId,
      tmax: bidderRequest.timeout,
      imp: validBidRequests.map(bid => {
        const imp = {
          id: bid.bidId,                            // Prebid-generated bid ID — must echo back in response
          bidfloor: bid.params.floor || 0,
          bidfloorcur: 'USD',
          ext: { placementId: bid.params.placementId }
        };

        const bannerSizes = deepAccess(bid, 'mediaTypes.banner.sizes');
        if (bannerSizes) {
          imp.banner = { format: bannerSizes.map(s => ({ w: s[0], h: s[1] })) };
        }

        const videoParams = deepAccess(bid, 'mediaTypes.video');
        if (videoParams) {
          imp.video = {
            mimes:          videoParams.mimes    || ['video/mp4'],
            protocols:      videoParams.protocols || [2, 3, 5, 6],
            w:              videoParams.playerSize?.[0]?.[0],
            h:              videoParams.playerSize?.[0]?.[1],
            playbackmethod: videoParams.playbackmethod,
            skip:           videoParams.skip       || 0,
            skipafter:      videoParams.skipafter   || 5
          };
        }

        return imp;
      }),

      site: {
        page: referer,
        domain: new URL(referer || 'https://unknown.com').hostname,
        publisher: { id: validBidRequests[0]?.params?.publisherId || '' }
      },

      // Privacy signals — always include these
      regs: {
        coppa: 0,
        ext: {
          gdpr: gdpr?.gdprApplies ? 1 : 0,
          us_privacy: usp || ''
        }
      },
      user: {
        ext: {
          consent: gdpr?.consentString || '',
          eids: validBidRequests[0]?.userIdAsEids || []   // Unified IDs from Prebid ID modules
        }
      }
    };

    return {
      method: 'POST',
      url: ENDPOINT_URL,
      data: JSON.stringify(openRtbRequest),
      options: { contentType: 'application/json' }
    };
  },

  // ── 3. Parse the SSP response into Prebid bid objects ─────────────────
  interpretResponse: function(serverResponse, request) {
    const body = serverResponse?.body;
    if (!body?.seatbid?.length) return [];

    const bids = [];
    body.seatbid.forEach(seatbid => {
      (seatbid.bid || []).forEach(bid => {
        const pbBid = {
          requestId:  bid.impid,            // must match imp[].id from buildRequests
          cpm:        bid.price,
          currency:   body.cur || 'USD',
          width:      bid.w,
          height:     bid.h,
          creativeId: bid.crid || bid.id,
          ttl:        300,                 // seconds this bid is valid — player must render within TTL
          netRevenue: true,               // true = price is net of SSP fee
          meta: {
            advertiserDomains: bid.adomain || [],
            mediaType: bid.ext?.prebid?.type || BANNER
          }
        };

        // Banner creative
        if (bid.adm && !bid.ext?.prebid?.type?.includes('video')) {
          pbBid.ad = bid.adm;
        }

        // Video creative (VAST XML or URL)
        if (bid.ext?.prebid?.type === 'video') {
          pbBid.vastXml = bid.adm;
          pbBid.vastUrl = bid.ext?.prebid?.targeting?.hb_uuid
            ? `https://prebid-cache.example.com/cache?uuid=` + bid.ext.prebid.targeting.hb_uuid
            : undefined;
          pbBid.mediaType = VIDEO;
        }

        bids.push(pbBid);
      });
    });
    return bids;
  },

  // ── 4. User sync — after auction, fire sync pixels ────────────────────
  getUserSyncs: function(syncOptions, serverResponses, gdprConsent, uspConsent) {
    if (!serverResponses?.length) return [];

    const gdprParam    = gdprConsent?.gdprApplies ? 1 : 0;
    const consentParam = encodeURIComponent(gdprConsent?.consentString || '');
    const uspParam     = encodeURIComponent(uspConsent || '');

    if (syncOptions.iframeEnabled) {
      return [{
        type: 'iframe',
        url:  `${SYNC_URL}?gdpr=${gdprParam}&consent=${consentParam}&us_privacy=${uspParam}&type=iframe`
      }];
    }

    if (syncOptions.pixelEnabled) {
      return [{
        type: 'image',
        url:  `${SYNC_URL}?gdpr=${gdprParam}&consent=${consentParam}&type=pixel`
      }];
    }

    return [];
  },

  // ── 5. Win notification — fires when this adapter's bid renders ────────
  onBidWon: function(bid) {
    if (bid.nurl) {
      // Replace auction price macro with clearing price
      const url = bid.nurl.replace('${AUCTION_PRICE}', bid.cpm);
      navigator.sendBeacon(url);
    }
  }
};

registerBidder(spec);

import { spec } from 'modules/mybidderBidAdapter.js';
import { newBidder } from 'src/adapters/bidderFactory.js';

const ENDPOINT = 'https://bid.mybidder.example.com/openrtb2/auction';

describe('mybidderBidAdapter', function() {
  const adapter = newBidder(spec);

  describe('isBidRequestValid', function() {
    it('returns true for a bid with placementId', function() {
      const bid = { params: { placementId: 12345 } };
      expect(spec.isBidRequestValid(bid)).to.equal(true);
    });
    it('returns false when placementId is missing', function() {
      const bid = { params: {} };
      expect(spec.isBidRequestValid(bid)).to.equal(false);
    });
  });

  describe('buildRequests', function() {
    const validBidRequests = [{
      bidId: 'bid-abc-001',
      params: { placementId: 12345 },
      mediaTypes: { banner: { sizes: [[300,250]] } },
      userIdAsEids: []
    }];
    const bidderRequest = {
      auctionId: 'auct-001',
      timeout: 1500,
      refererInfo: { page: 'https://example.com/' },
      gdprConsent: { gdprApplies: true, consentString: 'CPXx...' }
    };

    it('sends POST to the correct endpoint', function() {
      const request = spec.buildRequests(validBidRequests, bidderRequest);
      expect(request.method).to.equal('POST');
      expect(request.url).to.equal(ENDPOINT);
    });

    it('includes GDPR consent in the request body', function() {
      const request = spec.buildRequests(validBidRequests, bidderRequest);
      const body = JSON.parse(request.data);
      expect(body.regs.ext.gdpr).to.equal(1);
      expect(body.user.ext.consent).to.equal('CPXx...');
    });
  });

  describe('interpretResponse', function() {
    it('returns an empty array for empty seatbid', function() {
      expect(spec.interpretResponse({ body: { seatbid: [] } }, {})).to.deep.equal([]);
    });

    it('correctly maps a banner bid response', function() {
      const resp = {
        body: {
          cur: 'USD',
          seatbid: [{ bid: [{ impid: 'bid-abc-001', price: 2.5, w: 300, h: 250, adm: '<div>ad</div>', crid: 'cr-1' }] }]
        }
      };
      const bids = spec.interpretResponse(resp, {});
      expect(bids[0].requestId).to.equal('bid-abc-001');
      expect(bids[0].cpm).to.equal(2.5);
    });
  });
});

# Format: SSP domain, publisher account ID, relationship type, TAG-ID
appnexus.com, 9001, DIRECT, f08c47fec0942fa0     # DIRECT = you have a direct deal with this SSP
rubiconproject.com, 158355, DIRECT, 0bfd66d529a55807
openx.com, 540191387, DIRECT, 6a698e965929d969
indexexchange.com, 185001, DIRECT
pubmatic.com, 158355, DIRECT, 5d62403b186f2ace
triplelift.com, 1001, RESELLER, 6c33edb13117fd86 # RESELLER = SSP sells your inventory on behalf of another
# Rule: every SSP in your Prebid adapter config must appear here
# Missing entries = DSPs with brand safety filters will not buy your inventory