diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index c3e11a92a2..086b04156b 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -14,2813 +14,18 @@ sidebarType: 1 This page has documentation for the public API methods of Prebid.js. - - -## pbjs - -* [pbjs](#module_pbjs) - - * [.getAdserverTargeting()](#module_pbjs.getAdserverTargeting) - * [.getAdserverTargetingForAdUnitCode([adUnitCode])](#module_pbjs.getAdserverTargetingForAdUnitCode) - * [.getBidResponses()](#module_pbjs.getBidResponses) - * [.getBidResponsesForAdUnitCode(adUnitCode)](#module_pbjs.getBidResponsesForAdUnitCode) - * [.getEvents()](#module_pbjs.onEvent) - * [.getHighestCpmBids([adUnitCode])](#module_pbjs.getHighestCpmBids) - * [.getAllWinningBids()](#module_pbjs.getAllWinningBids) - * [.getAllPrebidWinningBids()](#module_pbjs.getAllPrebidWinningBids) - * [.getNoBids()](#module_pbjs.getNoBids) - * [.getNoBidsForAdUnitCode(adUnitCode)](#module_pbjs.getNoBidsForAdUnitCode) - * [.setTargetingForGPTAsync([codeArr], customSlotMatching)](#module_pbjs.setTargetingForGPTAsync) - * [.setTargetingForAst()](#module_pbjs.setTargetingForAst) - * [.renderAd(doc, id)](#module_pbjs.renderAd) - * [.removeAdUnit(adUnitCode)](#module_pbjs.removeAdUnit) - * [.requestBids(requestObj)](#module_pbjs.requestBids) - * [.addAdUnits(Array\|Object)](#module_pbjs.addAdUnits) - * [.bidderSettings](#module_pbjs.bidderSettings) - * [.onEvent(event, handler, id)](#module_pbjs.onEvent) - * [.offEvent(event, handler, id)](#module_pbjs.onEvent) - * [.enableAnalytics(config)](#module_pbjs.enableAnalytics) - * [.aliasBidder(adapterName, aliasedName)](#module_pbjs.aliasBidder) - * [.markWinningBidAsUsed(markBidRequest)](#module_pbjs.markWinningBidAsUsed) - * [.setConfig(options)](#module_pbjs.setConfig) - * [debugging](#setConfig-Debugging) - * [deviceAccess](#setConfig-deviceAcess) - * [bidderTimeout](#setConfig-Bidder-Timeouts) - * [maxRequestsPerOrigin](#setConfig-Max-Requests-Per-Origin) - * [disableAjaxTimeout](#setConfig-Disable-Ajax-Timeout) - * [timeoutBuffer](#setConfig-timeoutBuffer) - * [bidderOrder](#setConfig-Bidder-Order) - * [enableSendAllBids](#setConfig-Send-All-Bids) - * [sendBidsControl](#setConfig-Send-Bids-Control) - * [useBidCache](#setConfig-Use-Bid-Cache) - * [pageUrl](#setConfig-Page-URL) - * [publisherDomain](#setConfig-Publisher-Domain) - * [priceGranularity](#setConfig-Price-Granularity) - * [mediaTypePriceGranularity](#setConfig-MediaType-Price-Granularity) - * [s2sConfig](#setConfig-Server-to-Server) (server-to-server config) - * [app](#setConfig-app) (mobile app post-bid) - * [userSync](#setConfig-Configure-User-Syncing) - * [targetingControls](#setConfig-targetingControls) - * [sizeConfig and labels](#setConfig-Configure-Responsive-Ads) (responsive ads) - * [COPPA](#setConfig-coppa) - * [first party data](#setConfig-fpd) - * [cache](#setConfig-vast-cache) - * [instreamTracking](#setConfig-instream-tracking) - requires [Instream Tracking Module](/dev-docs/modules/instreamTracking.html) - * [site](#setConfig-site) - * [auctionOptions](#setConfig-auctionOptions) - * [Generic Configuration](#setConfig-Generic-Configuration) - * [Troubleshooting your config](#setConfig-Troubleshooting-your-configuration) - * [.setBidderConfig(options)](#module_pbjs.setBidderConfig) - * [.getConfig([string])](#module_pbjs.getConfig) - -Functions added by optional modules - - * [.adServers.dfp.buildVideoUrl(options)](#module_pbjs.adServers.dfp.buildVideoUrl) - requires [GAM Video Module](/dev-docs/modules/dfp_video.html) - * [.adServers.dfp.buildAdpodVideoUrl(options)](#module_pbjs.adServers.dfp.buildAdpodVideoUrl) - requires [GAM Video Module](/dev-docs/modules/dfp_video.html) [Alpha] - * [.adServers.freewheel.getTargeting(options)](#module_pbjs.getTargeting) - requires [Freewheel Module](/dev-docs/modules/freewheel.html) - * [.getUserIds()](#userId.getUserIds) - requires [User Id Module](/dev-docs/modules/userId.html) - * [.getUserIdsAsEids()](#userId.getUserIdsAsEids) - requires [User Id Module](/dev-docs/modules/userId.html) - * [.refreshUserIds(options, callback)](#userId.refreshUserIds) - requires [User Id Module](/dev-docs/modules/userId.html) - - - -### pbjs.getAdserverTargeting() ⇒ `object` - -Returns all ad server targeting for all ad units. Note that some bidder's response may not have been received if you call this function too quickly after the requests are sent. - -The targeting keys can be configured in [ad server targeting](#module_pbjs.bidderSettings). - -When [deals are enabled]({{site.baseurl}}/adops/deals.html), the object returned by this method may include a field `hb_deal_BIDDERCODE`, where `BIDDERCODE` is replaced by the name of the bidder, e.g., AppNexus, Rubicon, etc. - -**Kind**: static method of [pbjs](#module_pbjs) - -**Returns**: `object` - Map of adUnitCodes and targeting values [] - -**Returned Object Example:** - -{% highlight js %} -{ - "/9968336/header-bid-tag-0": { - "hb_bidder": "rubicon", - "hb_adid": "13f44b0d3c", - "hb_pb": "1.50" - }, - "/9968336/header-bid-tag-1": { - "hb_bidder": "openx", - "hb_adid": "147ac541a", - "hb_pb": "1.00" - }, - "/9968336/header-bid-tag-2": { - "hb_bidder": "appnexus", - "hb_adid": "147ac541a", - "hb_pb": "2.50", - "hb_deal_appnexus": "ABC_123" - } -} -{% endhighlight %} - -
- - - -### pbjs.getAdserverTargetingForAdUnitCode([adunitCode]) ⇒ `object` - -This function returns the query string targeting parameters available at this moment for a given ad unit. For full documentation see function [pbjs.getAdserverTargeting()](#module_pbjs.getAdserverTargeting). - -**Kind**: static method of [pbjs](#module_pbjs) - -**Returns**: `object` - returnObj return bids - -**Request Params:** - -{: .table .table-bordered .table-striped } -| Param | Type | Description | -| --- | --- | --- | -| [adunitCode] | `string` | adUnitCode to get the bid responses for | - -**Returned Object Example:** - -{% highlight js %} -{ - "hb_bidder": "rubicon", - "hb_adid": "13f44b0d3c", - "hb_pb": "0.50" -} -{% endhighlight %} - -
- - - -### pbjs.getBidResponses() ⇒ `object` - -This function returns the bid responses at the given moment. - -**Kind**: static method of [pbjs](#module_pbjs). - -**Returns**: `object` - map | object that contains the bidResponses. - -**Returned Object Params**: - -{: .table .table-bordered .table-striped } -| Param | Type | Description | | -|---------------------+---------+---------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------| -| `bidder` | String | The bidder code. Used by ad server's line items to identify bidders | `rubicon` | -| `adId` | String | The unique identifier of a bid creative. It's used by the line item's creative as in [this example]({{site.github.url}}/adops/send-all-bids-adops.html#step-3-add-a-creative). | `123` | -| `width` | Integer | The width of the returned creative size. | 300 | -| `height` | Integer | The height of the returned creative size. | 250 | -| `size` | String | The width x height of the returned creative size. | "300x250" | -| `cpm` | Float | The exact bid price from the bidder | 1.59 | -| `pbLg`,`pbMg`,`pbHg`,`pbAg`,`pbDg`,`pbCg` | String | CPM quantized to a granularity: Low (pbLg), Medium (pbMg), High (pbHg), Auto (pbAg), Dense (pbDg), and Custom (pbCg). | "5.00" | -| `currency` | String | Currency of the bid CPM | `"USD"` | -| `netRevenue` | Boolean | True if bid is Net, False if Gross | `true` | -| `requestTimestamp` | Integer | The time stamp when the bid request is sent out in milliseconds | 1444844944106 | -| `responseTimestamp` | Integer | The time stamp when the bid response is received in milliseconds | 1444844944185 | -| `timeToRespond` | Integer | The amount of time for the bidder to respond with the bid | 79 | -| `adUnitCode` | String | adUnitCode to get the bid responses for | "/9968336/header-bid-tag-0" | -| `creativeId` | Integer | Bidder-specific creative ID | 12345678 | -| `mediaType` | String | One of: banner, native, video | `banner` | -| `dealId` | String | (Optional) If the bid is [associated with a Deal]({{site.baseurl}}/adops/deals.html), this field contains the deal ID. | "ABC_123" | -| `adserverTargeting` | Object | Contains all the adserver targeting parameters | `{ "hb_bidder": "appnexus", "hb_adid": "7a53a9d3" }` | -| `native` | Object | Contains native key value pairs. | `{ "title": "", "body": "" }` | -| `status` | String | Status of the bid. Possible values: targetingSet, rendered | `"targetingSet"` | -| `statusMessage` | String | The bid's status message | "Bid returned empty or error response" or "Bid available" | -| `ttl` | Integer | How long (in seconds) this bid is considered valid. See this [FAQ entry]({{site.github.url}}/dev-docs/faq.html#does-prebidjs-cache-bids) for more info. | `300` | - -
- -
- -
-
- - -{% highlight bash %} -{ - "/9968336/header-bid-tag-0": { - "bids": [ - { - "bidderCode": "appnexus", - "width": 300, - "height": 250, - "statusMessage": "Bid available", - "adId": "7a53a9d3", - "creative_id": 29681110, - "cpm": 0.5, - "adUrl": "https://nym1.ib.adnxs.com/ab?e=wqT_3QLzBKBqAgAAAgDWAAUIkav6sAUQucfc0v-nzQcYj…r=http%3A%2F%2Flocal%3A4000%2Fexamples%2Fpbjs_partial_refresh_example.html", - "requestTimestamp": 1444844944095, - "responseTimestamp": 1444844944180, - "timeToRespond": 85, - "adUnitCode": "/19968336/header-bid-tag-0", - "bidder": "appnexus", - "usesGenericKeys": true, - "size": "300x250", - "adserverTargeting": { - "hb_bidder": "appnexus", - "hb_adid": "7a53a9d3", - "hb_pb": "0.50" - } - },{ - "bidderCode": "pubmatic", - "width": "300", - "height": "250", - "statusMessage": "Bid available", - "adId": "1139e34e14", - "adSlot": "39620189@300x250", - "cpm": 1, - "ad": " ", - "adUrl": "https://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId…local%3A4000%2Fexamples%2Fpbjs_partial_refresh_example.html&lpu=hotels.com", - "dealId": "", - "requestTimestamp": 1444844944105, - "responseTimestamp": 1444844944354, - "timeToRespond": 249, - "adUnitCode": "/19968336/header-bid-tag-0", - "bidder": "pubmatic", - "usesGenericKeys": true, - "size": "300x250", - "adserverTargeting": { - "hb_bidder": "pubmatic", - "hb_adid": "1139e34e14", - "hb_pb": "1.00" - } - }, - { - "bidderCode": "rubicon", - "width": "300", - "height": "250", - "statusMessage": "Bid available", - "adId": "130d3b0d9b", - "cpm": 0.795995, - "ad": "", - "ad_id": "3161645", - "sizeId": "15", - "requestTimestamp": 1444844944116, - "responseTimestamp": 1444844944396, - "timeToRespond": 280, - "adUnitCode": "/19968336/header-bid-tag-0", - "bidder": "rubicon", - "usesGenericKeys": true, - "size": "300x250", - "adserverTargeting": { - "hb_bidder": "rubicon", - "hb_adid": "130d3b0d9b", - "hb_pb": "0.50" - } - } - ] - }, - "/9968336/header-bid-tag1": { - "bids": [ - { - "bidderCode": "casale", - "width": 0, - "height": 0, - "statusMessage": "Bid returned empty or error response", - "adId": "108c0ba49d", - "requestTimestamp": 1444844944130, - "responseTimestamp": 1444844944223, - "timeToRespond": 93, - "cpm": 0, - "adUnitCode": "/19968336/header-bid-tag1", - "bidder": "casale" - }, - { - "bidderCode": "openx", - "width": "728", - "height": "90", - "statusMessage": "Bid available", - "adId": "14d7f9208f", - "ad_id": "537161420", - "cpm": 1.717, - "ad": "