Prebid 1.0.0 Proposal - intent to implement

[mkendall07]

Please see http://prebid.org/dev-docs/bidder-adaptor.html for the latest adapter requirements. Some of the information below is out of date

Updates

• February 6, 2017
  • Clarification on requirements/ distinction between requirements and recommendations
  • Acknowledgements: Thanks to @bretg and the Rubicon team for the feedback here.
• Oct 9th, 2017
  • Moved currency into required field for bidders.

Type of issue

Intent to implement. Open for comment.

Background and Motivation

To this point, Prebid.js releases have been iterating on major version 0 (as of the time of writing, the latest Prebid.js release is 0.18.0). Given the maturity and widespread adoption of Prebid.js, we are approaching the point at which we should start pushing towards release of version 1.0.0.

In traditional semantic software versioning, version 0.X.X implies beta software in which large public API changes should be expected. Version 1.X.X implies stabilization of public APIs (i.e. major breaking changes should no longer be expected).

The release of Prebid.js version 1.0.0 gives us the opportunity to take a firmer stance on adaptor standardization and performance, on which Prebid has been intentionally lax. To this effect, the requirements and recommendations outlined below represent a fundamental paradigm shift for Prebid.js, whereby we decide that regulation of adapter behavior, security, and page performance are in-scope.

We encourage the community to review the following proposal and offer comments and suggestions to further shape this document.

Prebid 1.0.0 Summary

Based on frequently recurring suggestions from the Prebid.js user base, the Prebid core team has identified the following high-level themes on which we aim to focus with the release of Prebid.js version 1.0.0:

1. Formalize adapter requirements and recommendations, and standardize adapter behavior
2. Reduce Prebid's impact to page performance and latency
3. Improve page security

Performance

Core

• An auction shall be defined as the result of a single call made to requestBids for one or more adUnits.
• An impression shall be defined as the inclusion of a single adUnit within a single auction.
• Each Prebid auction will generate a unique auction ID.
• Each Prebid impression will generate a unique impression ID. As per the OpenRTB 2.5 definition of the Source object, this impression ID may be shared across multiple exchanges.
• Prebid shall be able to run multiple auctions concurrently, and shall be able to match all adapter bid responses with their corresponding bid requests.
• Prebid may choose to create multiple instances of any adapter.
• Prebid will provide a standard OpenRTB adapter.
• Prebid reserves the right to monitor and report on the performance of adapters.
• Prebid reserves the right to throttle, deactivate, or remove adapters programmatically or manually, based on defined performance standards and/ or run-time conditions.
• Prebid will provide a mechanism for adapters to register partner pixels (cookie syncs, beacon calls, img URLs, etc.). Prebid will control the dropping of these pixels in a manner that minimizes impact to ongoing Prebid auctions, other Prebid adapters, and general page performance. Adapters shall not be permitted to drop partner pixels directly (in real-time during the auction). No restriction will be placed on pixels attached to winning creatives. (See #890 ).
• Prebid will allow publishers to specify a currency code.
• Support multiple instances of Prebid.js on page without conflicts.

Adapters

Requirements

• All adapters must support HTTPS requests when loaded from a secure page.
• All code must be contained within the adapter; no additional external JS libraries may be loaded.
• Each Prebid call made to requestBids will generate a unique auction ID. All adapters must return this unique auction ID on all bid responses.
• All bid response must define an adapter-specific Creative ID for identification and quality purposes.
• All adapter bid responses must be gzipped.
• Any adapter using the OpenRTB protocol must alias the standard OpenRTB adapter provided by the Prebid core framework.
• All adapters must specify a time to live for bid responses, such that Prebid may discard expired bids.
• All adapters must support the creation of multiple instances.
• All adapters must adhere to Prebid-defined policy for registering partner pixels.
• Adapters should be able to ingest a publisher-defined currency code, and return bid CPMs accordingly. Alternatively, a hardcoded currency code can be provided. If not provided, USD is assumed.

Recommendations

• Adapters should support a single request architecture (SRA), making a single bid request per page load which supports multiple adunits and multiple sizes per adunit.
• Adapter bid responses should be no greater than N KB per included impression (where N is TBD).
• Mean adapter response time should be less than N ms round trip as measured by the network latency (where N is TBD) from locations that are primarily served by the adapter client base.

Security

• All adapters will be loaded into an x-domain/safeFrame environment.
  • This will increase latency somewhat, but is necessary tradeoff to ensure security and uphold the integrity of the integration with the publisher page.
• No adapter shall be able to access the bids from any other adapter.
• All returned creatives must support the SafeFrame API (no relying on window.top access) and must support transmission over PostMessage API
• Prebid will continue to support analytics via the registration of analytics adapters. All analytics will be subject to publisher opt-in.
• Adapter bid responses may contain only JSON/ data. Adapters will not be permitted to return new library code to be executed at run time.
• Prebid shall support any additional bid encryption/ transformation defined by a given publisher.

Design

Key Considerations

• The Prebid.js 1.0.0 API will be designed with primary objectives being ease of use and ease of adoption.
• When in doubt about data encapsulation, prefer isolation. The publisher should have the sole discretion to permit data sharing.
• The core framework should remain small. Maximum flexibility by expression functionality through the use of modules
• Breaking changes to 0.x.x APIs will be permitted, and should be expected.

Modularity

Note: The use of "Sub module" here doesn't necessarily mean a git submodule. We are considering a a Monorepo type structure (https://github.com/babel/babel/blob/master/doc/design/monorepo.md)

• The Prebid core module will contain only the foundation code. All functionality beyond should be expressed as a module.
• Base module core functionality:
  • Registering / controlling module and loading
  • Ensuring security and performance
  • Handling publisher configuration/setup
  • Registering bids and holding the auction
• Sub modules will be maintained and released separately.
• Sub modules can be packaged during build time or during run time.
• Sub modules will be built for:
  • Adapters (maintained by authors)
  • Key/ value pair generation
  • Auction logic
  • Core ad server API integrations
  • Other extensible functionality

Configuration Driven

• Prebid will make no assumptions about the ad server of record, and will work with or without it.
• "Code free" integrations into the ad server of record shall be provided via adapters.
• All setup should be configurable via JSON?
• Each on-page slot may be fired independently or grouped with other on-page slots.
• The prefetching of each on-page slot will be permitted up to a specified max.
• Hooks will be provided pre/ post auction for data transformation.

Enforcement

• The Prebid core team will review and approve all sub modules and core code changes.
• The Prebid core team will invite members from the community to join (the process of this invitation is beyond the scope of this document, but will be put together separately).
• Each PR needs at least two "LGTM" from members of the Prebid core team before it will be merged to master.
• Style and convention will be enforced via Travis CI.
• Policy-level code restrictions may be necessary. If so, the Prebid core team will be responsible for making sure that these policies are followed.

Browser Support

• Prebid will support at most the last three releases of a modern browser & IE 10+

Other information

@prebid/core
@prebid/prebid-bidder-adaptors
@bretg
@snapwich

[mkendall07]

I've received a few questions on on how to submit feedback, so posting here:

Q) What's the best way to submit feedback?
A) Right here on this issue currently. If it becomes troublesome to track changes here we might move to a wiki space, but for now this is the best spot. Alternatively, you may email @prebid/core members directly.

Q) What is the formal process for getting changes into the spec?
A) The process will be to submit feedback directly here and core contributors will either accept/reject the amendment. Final decision will be left to the core team, however, we will try to be as fair as possible given a large set of stakeholders and competing priorities.

Q) What's the detailed design for Prebid 1.0?
A) The design draft will be posted after censuses has be reached on the requirements here, however, if you have ideas on design feel free to submit them ahead of time to be considered.

[christopher-allene-piximedia]

That's great news that Prebid.JS is finally achieving the 1.0 milestone! I bet many publishers are observing what we are trying to do with header bidding, and are waiting for Prebid.JS to stabilize before proceeding to implementing it. Reaching the “golden” 1.0 version will certainly help a much broader use of this technology.

I have a few remarks to the initial draft, as Matt suggested, I am going to comment this issue directly. As some of you already know, I work at Piximedia, which is a French-originating advertising technology company. We are specialized in rich media ads, and are displaying contents mainly in the EMEA market. Most, if not all, of our remarks are a consequence of us using the Prebid framework to display not only IAB display ads, but also various rich-media ads.

1. Embedding adapters in cross-domain iframe is definitively great for the added security, however there are certain formats that would not fit Safe Frame, such as out-of-stream formats like the skin or the footer. Another exception is the in-content format, where we dynamically create a position in the page when we win the auction. Those require top-window access, which should be given bidder-by-bidder by the publisher to the bidders it trusts. I would recommend of an optional property richmedia, that would allow an exception and load the adapter in a same-domain iframe: "richmedia": true. Loading in the same-domain iframe would still allow for Safe-Frame to be supported, and would be easier to support, as each adapters would be still loaded in a separate iframe (same origin, or cross origin).

2. We have partnerships with active publishers that allow richmedia ads only on certain pages. Unfortunately, they have not found a way to tell their adserver about what pages are allowed (mostly because the page is dynamic and sometimes allows richmedia contents, and sometimes not, on the same position). Those publishers have asked us to dynamically inspect the page and bid only if some criterions are met. We would require to perform JavaScript on the adapter response. If we wanted to adhere to the “ideally, each bidder should only respond with JSON / data” recommendation, we could return some JavaScript as a string, and have our library execute that string. Would that adhere to the proposal? Or would it be best in our case to continue returning JavaScript contents that exposes the bids to a callback?

3. Some of the publishers we are working with are asking us the best way to use Prebid.JS for skins or footers. We know of at least one advertising technology company that is suggesting that publishers expose a position of a specific size (i.e. 1800x1200) that they will interpret as being a skin. I believe it would be better if the 1.0 specification could change the rule such as follows:

   1. the width/height of each position should be the in-stream size of the position, for regular ads (banners and/or expands)
   2. when a position is a rich-media out-of-stream position, its width and height should be set to 0 to expose the fact that no in-stream content will be created from this position
   3. when a position has a width and height of 0, a third item to the size array should be provided that would allow the adapter to know what kind of content is expected

   Some examples:
   [ 300, 250 ]
[ 0, 0, "footer" ]
[ 0, 0, "skin" ]

Once again, thank you everyone for your work! Let me know what you think of our remarks.

All the best,
Christopher

[mjacobsonny]

Proposal has been updated.

[pdezwart]

How do you reconcile these two statements?

Prebid reserves the right to monitor and report on the performance of adapters.
Prebid reserves the right to throttle, deactivate, or remove adapters programmatically or manually, based on defined performance standards and/ or run-time conditions.

And

Prebid will continue to support analytics via the registration of analytics adapters. All analytics will be subject to publisher opt-in.

My understanding is that PreBid reserves the right to phone home from a given client, which is, in essence, analytics. I am all for gathering data across the ecosystem about performance, though I would say:

• if it is bundled into PreBid code, it is a burden (albeit a small one) on a given publisher's website. Performance data should probably be phoned home on a sample set (say 1%), with a customer toggle to disable (opt-out).
• if is it not bundled into PreBid, then what mechanism would we be using? We could setup a pingdom account which hits a representative endpoint provided by each bidder?

[mkendall07]

@pdezwart
Thanks for the feedback. My intention was to have some way to monitor externally on bidder performance and also possibly locally for each user (i.e localStorage) to keep bidders in check. There was no intention to bundle a "phone home" analytics adapter.

[bretg]

Community update: the Prebid Org team is now focused on the 1.0 release as described above. The focus of 1.0 is performance and refactoring the modularity. You'll have noticed the 7 sub-issues opened to track the work being done -- they will be fleshed out in the coming weeks.

The goal is to get a spec out to adapter owners in the next month so they have time to make any necessary modifications, with the aim of releasing the upgrade this summer.

We will do our best to accommodate any further feedback from the community.

[thewizarodofoz]

@bretg Thanks for all your work. We were writing our adapter, then we saw v1.0 was announced, so we are now making the required changes. Where can we find the full spec?

[mkendall07]

@thewizarodofoz
Please see here for the adapter docs: http://prebid.org/dev-docs/bidder-adapter-1.html

[thewizarodofoz]

@mkendall07 Thanks, I'm familiar with this. What I'm missing is the internal models which are passed to adapter methods like the validBidRequests argument passed to buildRequests, which (after some digging) I found to be in this form:

{
  "bidder": "example",
  "bidId": "51ef8751f9aead",
  "params": {

  },
  "adUnitCode": "div-gpt-ad-1460505748561-0",
  "transactionId": "d7b773de-ceaa-484d-89ca-d9f51b8d61ec",
  "sizes": [
    [
      320,
      50
    ],
    [
      300,
      250
    ],
    [
      300,
      600
    ]
  ],
  "bidderRequestId": "418b37f85e772c",
  "auctionId": "18fd8b8b0bd757"
}

[therazor]

Is there any way to test a 1.0 prerelease version?
I cannot see any beta/prerelease tag on the npm registry or the repo, and PRs here seem to go to master.

[jaiminpanchal27]

@therazor You can use Prebid-1.0 branch for testing. We are doing all 1.0 related stuff in this branch.

[therazor]

@jaiminpanchal27 I saw that branch, but it seems like there is only one bidder adapter - not enough for testing.
Considering the aim for the first 1.0 tag is in a couple of weeks (according to the email sent out recently), do you expect most of the adapters to be there by then?

[jaiminpanchal27]

@therazor Yes that branch will only have Prebid-1.0 compliant adapters. We updated appnexusAst adapter so everyone can refer that and update their adapters.

Pulsepoint udpated their adapter #1338, that will be reviewed and merged soon.

As @mkendall07 said in his 1.0 blog post, We need your help to work with Prebid 1.0. We are hoping that everybody will pitch in.

[PWyrembak]

In order to start working on 1.0 version support-
how we should move on the gzip flag? Is the preferred option to pass a separate parameter for header bid response format on HB ad request (e.g. /hb?auid=1,2&bf=gzip) or should we pick it from accept-encoding header? If it is the latter, do you guarantee that we'll have see there only 'gzip' for requests coming through prebid v1.0 and an empty header on non-v1.0 requests?

[mkendall07]

@PWyrembak the specific compression format doesn't matter. All that matters is that you support compression on the response based on what the client sends in the standard http header Accept-Encoding. For example:
Accept-Encoding:gzip, deflate

We cannot guarantee what a client sends, that's up to each individual browser, agent etc.

[PWyrembak]

@mkendall07 thank you, your answer makes sense.

[PWyrembak]

@mkendall07 In order to make sure we're on the same page. Should we treat Accept-Encoding: gzip same was as Accept-Encoding: deflate and return gzipped header bids in both cases?

[PWyrembak]

And @mkendall07 another confirmation. In case of header nobid we will return a simple empty JSON '{}' which is not gzipped. It doesn't seem reasonable to gzip such nobid answer though. Could you please confirm this will work as expected on your end?

[bwoolcott]

@mkendall07 Regarding currency support, I saw that this currency note:

Adapters should be able to ingest a publisher-defined currency code, and return bid CPMs accordingly.

is under "Recommendations" not "Requirements." But, reading through this: #1089 one of the notes is:

Adapters will need to specify what currency the bid is in. Defaults to USD if not specified.

Would this mean that if a bidder sends in region based bids (eg. bids in EUR or GBP for EMEA pubs) that the adapter would be required to have currency support or else would be at risk of defaulting their bids to USD?

[mkendall07]

@bwoolcott

Would this mean that if a bidder sends in region based bids (eg. bids in EUR or GBP for EMEA pubs) that the adapter would be required to have currency support or else would be at risk of defaulting their bids to USD?

That's correct. I updated the doc accordingly.

[bretg]

@bwoolcott - just to be clear, as long as the adapter knows which currency the bid is in and can report it in the bidResponse, it doesn't necessarily need to take in the page's requested currency.

The client-based currency conversion will be able to convert so long as it knows what it's working with. e.g. say the page (and ad server) wants "EUR", but the bidder sees that the user is in the UK so bids in GBP. As long as the adapter puts GPB in the bidResponse, it will get properly converted to EUR before being sent to the ad server.

[PWyrembak]

@mkendall07 regarding 'ttl' parameter:
«Time-to-Live - how long (in seconds) Prebid can use this bid.»
Is prebid expected to cache this particular bid and re-use it only once during the ttl period? Will the wrapper still call hb partner for other bids?

[bretg]

Prebid 1.0 released -- http://prebid.org/blog/prebid-1-is-released