Intent to Implement: Adding GAM Support to Prebid long-form

[jaiminpanchal27]

Type of issue

Intent to implement.
Status: Open for comment.

Table of Contents

• Overview
• Proposed Design
  • DFP Module Spec
  • Mapping file
  • Use Cases
  • GAM Setup

Overview

Prebid.js already released long-form feature with FreeWheel as first supporting ad server. Now we are adding Google ad server support. This Spec covers the implementation details for adding long-form support to Google ad manager module in Prebid.

Proposed Design

DFP Module Spec

Prebid is already doing video header bidding for google ad server using dfpAdServerVideo module. To support long-form we will expose two new methods in this module.

• pbjs.adServers.dfp.buildAdpodVideoUrl
• pbjs.adServers.dfp.getAdpodTargeting

pbjs.adServers.dfp.buildAdpodVideoUrl

This method combines publisher-provided parameters with Prebid.js targeting key values to build a DFP video ad tag URL that can be used by a video player.

Params	Scope	Type	Description
codes	required	array[string]	Array of ad unit codes. Module will ignore all other ad units
params	required	object	Query string parameters that will be used to construct the DFP video ad tag URL. Publisher-supplied values will override values set by Prebid.js. See below for fields.
callback	required	function	Callback function to execute when master tag url is back

params object. More info on params object here https://support.google.com/admanager/answer/1068325?hl=en

Params	Scope	Type	Description	Notes
iu	required	string	ad unit
description_url	required	string	The value should describe the video playing on the page.	For long form we will add kvs for multiple bids, hence cannot take description url from bid

Sample Call

pbjs.adServers.dfp.buildAdpodVideoUrl({
    codes: ['adUnitcode-1'],
    params: {
        iu: '/123456/testing/prebid.org/adunit1',
        description_url: 'http://mycontent.com/episode-1'
        vid: 'ciy29vv7p00010gquqb1otppi',
        cmsid: '2471555',
        cust_params: {
            // your custom params
        }
    },
    callback: function(err, masterTag) {
        // Invoke video player and pass the master tag
    }
});

pbjs.adServers.dfp.getAdpodTargeting

This method can be used by publisher if they only want targeting and publisher will create master tag on its own. It will return targeting key values and cache id.

Params	Scope	Type	Description
codes	required	array[string]	array of adunit codes
callback	required	function	Callback function to execute when master tag url is back

Sample Call

pbjs.adServers.dfp.getAdpodTargeting({
  codes: ['adUnitcode-1'],
  callback: function(err, targeting) {
    // Pass targeting to publisher api which will construct the master tag
  }
});
 
 
// Sample targeting returned
{
  'adUnitCode-1': [
    {
      'hb_pb_cat_dur': '10.00_<label>_15s'
    },
    {
      'hb_pb_cat_dur': '15.00_<label>_30s'
    },
    {
      'hb_cache_id': '123'
    }
  ]
}

Mapping file

To do competitive exclusion Publishers needs to provide mapping file which will convert IAB sub category to label. Publisher can set the mapping file using

pbjs.setConfig({
    "brandCategoryTranslation": {
        "translationFile": "<url_to_file>"
    }
});

Publishers should ensure that the JSON returned from their custom translation file is valid for Prebid by adhering to the following structure:

{
    "mapping": {
        "<your-iab-sub-category>": {
            "id": "<label id or name>",
            "name": "<label name>"
        },
   ....
   }
}

Use Cases

As a Publisher, I want to request n bids for p adpods where n is number of bids and p is number of adpods. I also want to ensure exclusivity and I want Prebid to return master tag url

Prebid Config

var videoAdUnit = [{
  code: 'sample-code',
  sizes: [640,480],
  mediaTypes: {
    video: {
      context: 'adpod',
      playerSize: [640, 480],
      adPodDurationSec: 300,
      durationRangeSec: [15, 30],
      requireExactDuration: true
    }
  },
  bids: [
    {
      bidder: 'appnexus',
      params: {
        placementId: 14542875
      }
    }
  ]
}];
 
pbjs.que.push(function(){
  pbjs.addAdUnits(videoAdUnit);
  pbjs.setConfig({
    cache: {
      url: 'https://prebid.adnxs.com/pbc/v1/cache'
    },
    adpod: {
      brandCategoryExclusion: true
    },
    brandCategoryTranslation: {
       translationFile: "http://mymappingfile.com/mapping.json"
    }
  });
 
  pbjs.requestBids({
      bidsBackHandler: function(bids) {
        pbjs.adServers.dfp.buildAdpodVideoUrl({
            codes: ['sample-code'],
            params: {
                iu: '/123456/testing/prebid.org/adunit1',
                description_url: 'http://mycontent.com/episode-1'
            },
            callback: function(err, masterTag) {
              // Invoke video player and pass the master tag
            }
        });
      }
  });
});

As a Publisher, I want to request n bids for p adpods where n is number of bids and p is number of adpods. I do not care for competitive exclusion. I am only interested in targeting key value

var videoAdUnit = [{
  code: 'sample-code',
  sizes: [640,480],
  mediaTypes: {
    video: {
      context: 'adpod',
      playerSize: [640, 480],
      adPodDurationSec: 300,
      durationRangeSec: [15, 30],
      requireExactDuration: true
    }
  },
  bids: [
    {
      bidder: 'appnexus',
      params: {
        placementId: 14542875
      }
    }
  ]
}];
 
pbjs.que.push(function(){
  pbjs.addAdUnits(videoAdUnit);
  pbjs.setConfig({
    cache: {
      url: 'https://prebid.adnxs.com/pbc/v1/cache'
    },
  });
 
  pbjs.requestBids({
      bidsBackHandler: function(bids) {
        pbjs.adServers.dfp.getAdpodTargeting({
          codes: ['sample-code'],
          callback: function(err, targeting) {
            // Pass targeting to publisher api which will construct the master tag
          }
        });
      }
  });
});

GAM Setup

NOTE: Due to GAM Macro limitation, each line item must have its unique creative. GAM does not provide any macros which can access line item name or anything line item relates except line item id

Line item

In GAM, Create new order with $10.00 line item. Select Inventory sizes to vast and add the size. If you want to do competitive exclusion, also set a label. Set the type to price priority and set rate cpm. Use frequency cap to avoid repeating ads in your content

Prebid.js will send targeting key values in cust_params using the keyword hb_pb_cat_dur. If this line item is targeting $10 cpm, label news and duration 30s. Set the value to 10.00_news_30s

Final result would look like hb_pb_cat_dur=10.00_news_30s. You can also target video positions, video content and ad unit here.

Creative

As said earlier, add new creative for this line item.

• For each line item you created above, select new creative set.
• In the dialog that appears, set the creative set type to "Redirect"
• Set the VAST tag URL to the cache location. Note that each bidder, e.g. Rubicon Project, may have a different cache location URL.

https://prebid.adnxs.com/pbc/v1/cache?uuid=<hardcoded targeting value>_%%PATTERN:hb_cache_id%%
Sample value: https://prebid.adnxs.com/pbc/v1/cache?uuid=50.00_news_30s_%%PATTERN:hb_cache_id%%

• Set the duration to 30s
• No need to set the label here as you have already done that in line item

Labels

Create labels of type Competitive exclusion. Make sure you also create a mapping file as explained above for all the labels used in competitive exclusion.

More on labels here https://support.google.com/admanager/answer/190565?hl=en&ref_topic=30224

AdRules

TODO. As of now we do not have access for this area.

More on ad rules here https://support.google.com/admanager/answer/1406475?hl=en