Add native support

[matthewlane]

• Feature

A native advertisement comprises a set of assets--a title, a description, and an image url, for example--that are plugged into a publisher-defined HTML template. The template includes placeholder macros for those assets, and may be styled to match the form of the surrounding page. This change adds capabilities for requesting native demand from bidder adapters, and sending the received assets to a native template defined in an ad server via key-value targeting.

Publisher Setup

To signal a native demand request, configure an adUnit's mediaType to 'native'.

Optionally specify the individual assets to request from the demand partner with a nativeParams object. This object will be passed to bidder adapters for use in constructing their network requests. The possible nativeParams are

• title
• body
• image
• sponsoredBy
• icon
• clickUrl

Any field in nativeParams configured as {required: true} will be required on the bid response object. If not present, the bid is not added to the auction.

Prebid also has a pre-defined native type, image, which is an abstraction over a set of commonly requested native assets. This expands to the following set of native parameters

image: {required: true}
title: {required: true}
sponsoredBy: {required: true}
clickUrl: {required: true}
body: {required: false}
icon: {required: false}

Use this by setting nativeParams to type: 'image'.

Example native ad unit

pbjs.addAdUnits({
  code: slot.code,
  sizes: slot.size,
  mediaType: 'native',
  nativeParams: {
    title: {required: true},
    body: {required: false}
    image: {required: false}
    sponsoredBy: {required: true},
  },
  bids: [{
    bidder: 'appnexusAst',
    params: {placementId: 123}
  }]
});

Bidder Adapter Setup

The adapter is given the nativeParams object in its callBids function and may send these parameters directly or transform them to fit their endpoint's expected parameters. For example, the appnexusAst endpoint recognizes title and icon as native asset request parameters and passes those on directly, but expects description instead of body and creates a mapping between these identifiers.

When demand is returned to the adapter, it should mark the bid response object with mediaType: 'native', and attach the received assets to a native object on the bid with properties that match the nativeParams identifiers. For example, an adapter might construct its native bid response object in its response handler function as follows

let bid = bidfactory.createBid(STATUS.GOOD, response);

// bid.cpm, bid.code, etc. set

bid.mediaType = 'native';
bid.native = {
  title: response.title,
  body: response.desc,  // endpoint responds with `desc`, set to body
  sponsoredBy: response.sponsored,
  image: response.main_img.url,
  icon: response.icon.url,
  clickUrl: response.link.url,
  impressionTrackers: response.impression_trackers, // an array of urls that are fired if this bid wins
};

// other bid setup, etc.

bidmanager.addBidResponse(placementId, bid);

Ad Server Setup

Once the bid response object has all its required native properties set, if it wins the auction, targeting keys are set thusly:

bid attribute	targeting key
title	hb_native_title
body	hb_native_body
sponsoredBy	hb_native_brand
image	hb_native_image
icon	hb_native_icon
clickUrl	hb_native_linkurl

Toggling pbjs.enableSendAllBids() will also set landscape targeting for these native assets. Due to DFPs 20 character limit, the full bidder code appendix for these keys may be truncated.

A publisher's ad server should contain a template with macros for these keys, for example

<div class="sponsored-post">
  <div class="content">
    <h1>
      <a href="%%CLICK_URL_UNESC%%%%PATTERN:hb_native_linkurl%%" target="_blank">
        %%PATTERN:hb_native_title%%
      </a>
    </h1>
    <p>%%PATTERN:hb_native_body%%</p>
    <div class="attribution">%%PATTERN:hb_native_brand%%</div>
  </div>
</div>

Additionally, this snippet can be added to a template to call back to prebid.js to fire impression trackers for the winning native bid

<script>
window.parent.postMessage(JSON.stringify({
  message: 'Prebid Native',
  adId: '%%PATTERN:hb_adid%%'
}), '*');
</script>

closes #1012

[mkendall07]

this code should be in utils now (might have to rebase to get it)

[mkendall07]

This code is a bit confusing. Why is this mapping required?

[matthewlane]

It's required because some of the standard native assets prebid defines don't translate exactly to v3 endpoint parameters. v3 looks for description request parameter rather than body for example. Agreed this code is confusing though, I'll refactor to be more clear

[mkendall07]

also in utils

[mkendall07]

We should still fire requests for bidders that support native.

[mkendall07]

Probably don't want this line in between these 2.

[matthewlane]

This is to prevent a linting error 'nativeAdapters' is not defined

[mkendall07]

The adapter registration has to go into this file? seems inconsistent.

[matthewlane]

Writing it to adaptermanager.js like the other loader does causes a circular dependency. Can move it though if there's another place that makes more sense

[mkendall07]

LGTM!

[jaiminpanchal27]

LGTM