Back to Bidders

PubMatic

Features

Bidder Code pubmatic Prebid.org Member yes
Prebid.js Adapter yes Prebid Server Adapter yes
Media Types display, video, native Multi Format Support true
TCF-EU Support yes IAB GVL ID 76
GPP Support some (check with bidder) DSA Support check with bidder
USP/CCPA Support yes COPPA Support yes
Supply Chain Support yes Demand Chain Support yes
Safeframes OK yes Supports Deals yes
Floors Module Support yes First Party Data Support yes
Endpoint Compression yes ORTB Blocking Support yes
User IDs all Privacy Sandbox check with bidder
Prebid Server App Support yes

Table of contents

Introduction

Publishers can use Prebid.js to call PubMatic in any of the following ways:

  • Call through our client-side adapter: Prebid.js calls PubMatic directly from the browser using our client-side adapter.
  • Call through our server-side adapter: Prebid.js makes a call to Prebid Server and then Prebid Server uses our server-side adapter to call PubMatic.

We highly recommend adding the gptPreAuction module to populate GPID (Global Placement ID) values. See the gptPreAuction module documentation for implementation details.

Bid Params

Name Scope Description Example Type
publisherId required PubMatic-specific identifier associated with your account '32572' string
adSlot optional PubMatic-specific identifier associated with this ad unit. Refers to Ad Tags within PubMatic UI. We accept Ad Tag Name or Ad Tag ID, refer to example. '38519891' or 'homepage_banner' string
dctr optional Deal Custom Targeting
(Value configured in each adunit will be passed inside adunit configs i.e., imp.ext)		 'key1:abc\|key2:123' string
deals optional PMP deals
(Passed per slot. Each deal-id should be a string with more than 3 characters.)		 ['deal-id-5', 'deal-id-6', 'deal-id-7'] array of strings
outstreamAU optional Renderer ID provided by your account representative. Required for outstream video bids unless the ad unit has a supplied renderer. 'renderer_test_pubmatic' string

First Party Data

Publishers should use the ortb2 method of setting First Party Data. The following fields are supported:

  • ortb2.site.*
  • ortb2.user.*

AdUnit-specific data is supported using AdUnit.ortb2Imp.ext.*

UserSync

PubMatic recommends the UserSync configuration below. Without it, the PubMatic adapter will not be able to perform user syncs, which lowers match rate and reduces monetization.

pbjs.setConfig({
  userSync: {
    filterSettings: {
      iframe: {
        bidders: '*', // '*' represents all bidders
        filter: 'include'
      }
    }
  }
});

Note: Combine the above configuration with any other UserSync configuration. Multiple setConfig() calls overwrite each other and only the last call for a given attribute will take effect.

adSlot

The adSlot parameter is optional. If you choose to omit it, your PubMatic account must have default site and tag settings enabled. Contact your PubMatic Account Manager to learn more.

The adSlot parameter accepts either an Ad Tag Name or Ad Tag ID from PubMatic UI. We recommend using only one adSlot value per ad unit. See the Banner section for an example.

Format Example
Ad Tag ID '38519891'
Ad Tag Name 'unique-name-here' 
var adUnits = [{
    code: 'test-div',
    mediaTypes: {
        banner: {
            sizes: [
                [300, 250],
                [300, 600]
            ]
        }
    },
    bids: [{
        bidder: 'pubmatic',
        params: {
            publisherId: '32572', // required
            adSlot: '38519891' // optional - can be ID or name like 'homepage_banner'
        }
    }]
}];

Video

The following parameters are available for mediaTypes.video configuration:

Name Scope Description Example
mimes required List of content MIME types supported by the player. See OpenRTB 2.5 for options ['video/mp4']
minduration recommended Minimum video ad duration in seconds 5
maxduration recommended Maximum video ad duration in seconds 30
startdelay recommended Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements
>0: Mid-Roll (value indicates start delay in seconds)
0: Pre-Roll
-1: Generic Mid-Roll
-2: Generic Post-Roll		 0
playbackmethod recommended Playback methods that may be in use. Only one method is typically used in practice. See OpenRTB 2.5 section 5.10 for options
1: Auto-play, sound on
2: Auto-play, sound off
3: Click-to-play
4: Mouse-over		 [2]
protocols recommended Supported video bid response protocol values
1: VAST 1.0
2: VAST 2.0
3: VAST 3.0
4: VAST 1.0 Wrapper
5: VAST 2.0 Wrapper
6: VAST 3.0 Wrapper
7: VAST 4.0
8: VAST 4.0 Wrapper		 [2, 3, 5, 6]
linearity recommended OpenRTB2 linearity
1: Linear/In-Stream
2: Non-Linear/Overlay		 1
placement recommended Placement type for the impression. See OpenRTB 2.5 section 5.9 for options 1
plcmt recommended Video placement type. See OpenRTB 2.6 Plcmt Subtypes - Video 1
skippable optional Indicates if the player will allow the video to be skipped, where true = skippable true
api optional Supported API framework values
1: VPAID 1.0
2: VPAID 2.0
3: MRAID-1
4: ORMMA
5: MRAID-2		 [1, 2]
battr optional Blocked creative attributes. See OpenRTB 2.5 specification, List 5.3 for values [3, 9]
minbitrate optional Minimum bit rate in Kbps 300
maxbitrate optional Maximum bit rate in Kbps 1500

Instream Video

var videoAdUnits = [{
    code: 'test-div-video',
    mediaTypes: {
        video: {
            playerSize: [640, 480], // required
            context: 'instream', // required
            mimes: ['video/mp4'], // required
            minduration: 5,
            maxduration: 30,
            startdelay: 0,
            playbackmethod: [2],
            protocols: [2, 3, 5, 6],
            linearity: 1,
            placement: 1,
            plcmt: 1
        }
    },
    bids: [{
        bidder: 'pubmatic',
        params: {
            publisherId: '32572', // required
            adSlot: '38519891' // optional - can be ID or name like 'video_preroll'
        }
    }]
}];

Outstream Video

var videoAdUnits = [{
    code: 'test-div-video-outstream',
    mediaTypes: {
        video: {
            playerSize: [300, 250], // required
            context: 'outstream', // required
            mimes: ['video/mp4'], // required
            minduration: 5,
            maxduration: 30,
            startdelay: 0,
            playbackmethod: [2],
            protocols: [2, 3, 5, 6],
            linearity: 1,
            placement: 3,
            plcmt: 4
        }
    },
    bids: [{
        bidder: 'pubmatic',
        params: {
            publisherId: '32572', // required
            adSlot: '38519891', // optional - can be ID or name like 'outstream_article'
            outstreamAU: 'renderer_test_pubmatic' // required for outstream video
        }
    }]
}];

Note: As an alternative to using the outstreamAU parameter, you can supply your own renderer at the ad unit level. This gives you more control over the rendering process. For more information on configuring custom renderers, see the Prebid.js Outstream Video documentation.

Configuration for Video

For video ads, Prebid cache needs to be enabled for the PubMatic adapter.

pbjs.setConfig({
    cache: {
        url: 'https://my-pbs.example.com/cache'
    }
});

Native

We recommend using the ORTB Native spec 1.2.

var adUnits = [{
    code: 'test-div-native',    
    mediaTypes: {
        native: {
            ortb: {
                assets: [{
                    id: 1,
                    required: 1,
                    img: {
                        type: 3,
                        w: 150,
                        h: 50
                    }
                },
                {
                    id: 2,
                    required: 1,
                    title: {
                        len: 80
                    }
                },
                {
                    id: 3,
                    required: 1,
                    data: {
                        type: 1
                    }
                },
                {
                    id: 4,
                    required: 1,
                    data: {
                        type: 2
                    }
                }]
            }
        }
    },
    bids: [{
        bidder: 'pubmatic',
        params: {
            publisherId: '32572', // required
            adSlot: '38519891' // optional - can be ID or name like 'native_sidebar'
        }
    }]
}];

Multi-format

PubMatic supports multi-format ad units, allowing a single ad unit to accept multiple media types (banner, video, and native). The adapter will prioritize formats based on the order they are defined in the mediaTypes object.

var adUnits = [{
    code: 'test-div-multi',
    mediaTypes: {
        banner: {
            sizes: [
                [300, 250],
                [300, 600]
            ]
        },
        video: {
            context: 'outstream',
            playerSize: [300, 250],
            mimes: ['video/mp4'],
            protocols: [2, 3, 5, 6],
            minduration: 5,
            maxduration: 30
        },
        native: {
            ortb: {
                assets: [{
                    id: 1,
                    required: 1,
                    img: {
                        type: 3,
                        w: 150,
                        h: 50
                    }
                },
                {
                    id: 2,
                    required: 1,
                    title: {
                        len: 80
                    }
                }]
            }
        }
    },
    bids: [{
        bidder: 'pubmatic',
        params: {
            publisherId: '32572', // required
            adSlot: '38519891' // optional - can be ID or name like 'multi_format_ad'
        }
    }]
}];

Prebid Server

The following test parameters can be used to verify that Prebid Server is working properly with the PubMatic adapter. This example includes an imp object with a PubMatic test publisher ID, ad slot, and sizes that would match with the test creative.

{
"imp":[
      {
         "id":"some-impression-id",
         "banner":{
            "format":[
               {
                  "w":300,
                  "h":250
               },
               {
                  "w":300,
                  "h":600
               }
            ]
         },
         "ext":{
            "pubmatic":{
               "publisherId": "156276",
               "adSlot":"pubmatic_test"
            }
         }
      }
   ]
}

Endpoint Compression

This adapter utilizes gzip compression support built into Prebid.js core. For more information, see Compression Support for Outgoing Requests

Disabling Compression

You can disable gzip compression at the bidder level using pbjs.setBidderConfig. Set the gzipEnabled value to false:

pbjs.que.push(function () {
  pbjs.setBidderConfig({
    bidders: ['pubmatic'],
    config: {
      gzipEnabled: false
    }
  });
});

"Send All Bids" Ad Server Keys

These are the bidder-specific keys that would be targeted within GAM in a Send-All-Bids scenario. GAM truncates keys to 20 characters.
hb_pb_pubmatic hb_bidder_pubmatic hb_adid_pubmatic
hb_size_pubmatic hb_source_pubmatic hb_format_pubmatic
hb_cache_host_pubmat hb_cache_id_pubmatic hb_uuid_pubmatic
hb_cache_path_pubmat hb_deal_pubmatic

Back to Bidders