Support native click tracking

[matthewlane]

Type of change

• Feature

Description of change

As per OpenRTB Native 1.2 , click trackers should be supported as an array of URLs. This PR adds support to Prebid for click trackers associated with native bid responses.

If a native bid response contains click trackers, bidder adapters should attach the click tracker array to the native.clickTrackers property of the bid response object (see appnexusAstBidAdapter for an example of this).

As native creatives that are served from adservers are likely to be in a cross-origin frame, it is necessary to use postMessage from the native creative template to communicate to Prebid that a link was clicked. Prebid is (even before this PR) configured to fire native impression trackers when it receives a message with the following structure:

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

This PR introduces the ability to fire click trackers for the associated adId when a 'click' action is added to the message:

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

Ad ops teams may use these structures of postMessage in their native creative templates in any way that fits their use case. One example usage is given below:

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

<script>
function fireTrackers(action) {
  var message = {message: 'Prebid Native', adId: '%%PATTERN:hb_adid%%'};
  if (action === 'click') {message.action = 'click';}  // fires click trackers when called via link
  window.parent.postMessage(JSON.stringify(message), '*');
}

fireTrackers(); // fires native impressions on creative load
</script>

Other information

Click through/landing page URLs are a required field in the OpenRTB 1.2 spec. This PR also requires native bid responses to have a landing page url, defined by native.clickUrl on the native bid response object.

[dbemiller]

Looks pretty reasonable to me... few minor comments.

[dbemiller]

typo: define

[dbemiller]

Not sure I'd build tests around this return value... what you really want is to make sure that triggerPixel gets called with the expected args. Since this is a separate code path, there's no guarantee that it stays in sync with triggerPixel calls. Code may get added/removed over time.

I know it sucks for testing, but... it seems more robust to set a stub for triggerPixel and make sure that it gets called with the expected args.

[dbemiller]

Should probably rename to getNativeTargeting, parseNativeTargeting, or something like that.

set pretty universally means "this function changes some state." In this case, you're building a transformed copy of some existing state without changing it.

[dbemiller]

No need to return this anymore

[matthewlane]

Eh?

[dbemiller]

Oh I'm sorry... had a brain fart and thought this was the return trackers line. Nevermind.

[mkendall07]

I wonder if we should be validating the different bid types and objects... food for later thought.

[rmloveland]

@matthewlane based on your comment, looks like we need to update our Ad Ops docs for Native to show how to use these click trackers.

Are there any changes needed to the developer setup docs for Native?

[matthewlane]

@rmloveland Yeah, updating the Ad Opcs docs to show how to use click trackers is a good idea. On the developer setup docs, the native object section may be updated to indicate that clickTrackers can now optionally be required. If they are required but not present on the bid response, this will cause an error (like other native required-but-missing assets). However the pub doesn't have to require these, and if they are present on the native bid response they will still fire