Decision Manager Standard API

Transcription

1 Decision Manager Standard API Technical Integration Guide Version 2.5 March 23, 2017

2 2015 PubMatic Inc. All rights reserved. Copyright herein is expressly protected at common law, statute, and under various International and Multi-National Treatises (including, but by no means limited to, the Berne Convention for the Protection of Literary and Artistic Works). The following documentation, the content therein and/or the presentation of its information is proprietary to and embodies the confidential processes, designs, and technologies of PubMatic Inc. All copyrights, trademarks, trade names, patents, industrial designs, and other intellectual property rights contained herein are, unless otherwise specified, the exclusive property of PubMatic Inc. The ideas, concepts, and/or their application, embodied within this documentation remain and constitute items of intellectual property which nevertheless belong to PubMatic Inc. The information (including, but by no means limited to, data, drawings, specification, documentation, software listings, source and/or object code) shall not be disclosed, manipulated, and/or disseminated in any manner inconsistent with the nature and/or conditions under which this documentation has been issued. The information contained herein is believed to be accurate and reliable. PubMatic Inc. accepts no responsibility for its use in any way whatsoever. PubMatic Inc. shall not be liable for any expenses, damages, and/or related costs, which may result from the use of any information, contained hereafter. PubMatic Inc. reserves the right to make any modification to this manual or the information contained herein at any time without notice. CORPORATE HEADQUARTERS PubMatic, Inc. 901 Marshall Street, Suite 100 Redwood City, CA USA

3 Table of Contents About This Guide... 5 Overview... 5 How Does the Decision Manager Standard API Work?... 5 The Decision Manager Standard API for DFP... 7 Placing the Decision Manager Standard API JavaScript on the Page... 7 Trafficking the Decision Manager Standard API Campaign in the Ad Server The Decision Manager Standard API for ADTECH Placing Decision Manager Standard APIScript on the Page Trafficking the Decision Manager Standard APICampaign in the Ad Server The Decision Manager Standard API for OAS The Decision Manager Standard API for Other Ad Servers Supporting Key-Value Targeting Best Practices for Creating Line Items in the Ad Server Limitations iii

4

5 About This Guide Overview Publishers typically set lower priorities for programmatic demand in their ad servers, thus limiting it to remnant impressions via trafficked tags. The programmatic marketplace can only propose bids for that limited volume of inventory it s exposed to -- and as a result, publishers lose visibility and monetization of high-value programmatic demand on a large share of their traffic. The Decision Manager Standard API allows publishers to evaluate programmatic bids for every impression in their ad servers. This improves the way ad servers make decisions, as they begin utilizing real-time bids returned instead of the static bids used in the conventional alternative. The result is an increase in revenue. How Does the Decision Manager Standard API Work? The Decision Manager Standard API provides the pricing from programmatic open and private marketplaces for ad slots, which publishers can consume by passing key-value pairs to the ad server in real time. Implementing the Decision Manager Standard API requires two steps: Step 1: Add a header tag (JavaScript) to the web page or mobile website. Step 2: Set up the corresponding line items in the publisher s ad server, with settings that allow for consumption of the real-time bids at a granular level. 5

6 1. PubMatic s JavaScript code is placed on the publisher site, which makes an ad call to PubMatic before its ad server. It is a single ad call covering all the placements on the page. 2. PubMatic runs an auction with open and private RTB marketplaces for all the placements on the page while applying deal management, floor price, and brand control rules set within PubMatic. 3. PubMatic sends back a bid response from the open and private RTB marketplaces. 4. PubMatic s bid response is sent to the publisher s ad server by dynamically adding this response as a key-value to the existing ad server tags. PubMatic line items are created in the publisher s ad server at various priorities targeting the bid response from PubMatic. 5. Publisher s ad server makes the final decision on which campaign/line item to serve with PubMatic s bid response as an additional parameter, and the ad is served. 6

7 The Decision Manager Standard API for DFP This section provides information on how to implement the Decision Manager Standard APIfor DFP. Placing the Decision Manager Standard API JavaScript on the Page There are two options by which you can place the Decision Manager Standard API script on your site: Integration Options Advantages Disadvantages Option 1: A default recommended solution for new publishers. Simple and quick deployment. No need to specify any ad slots' names. No additional code required for consuming the bid prices or targeting parameters sent by PubMatic. Option 2: Applicable for both Legacy DART and DFP GPT. Legacy integration can be customized. Applicable only for DFP GPT. Integration cannot be customized. Requires more time for additional development. Need to specify the ad slots' names. Additional code required for consuming the bid prices or targeting parameters sent by PubMatic. 7

8 Option 1 The following section is applicable only for DFP GPT implementation. For this option, you do not need to develop any additional code for consuming the bid prices or targeting parameters sent by PubMatic. Note: Refer to the following demo page to see an implementation of the Decision Manager Standard API script described below: For login details, please contact your PubMatic account manager. Please ensure that PubMatic JS library "dm_gpt_generic.js" is loaded before DFP "gpt.js, otherwise the PubMatic code won t start execution. You can achieve implementation using one of the following approaches: Configure the same in your tag management solution. OR Use synchronous version of the DM script. We recommend using this approach if a publisher is putting our script directly on the page. <script type= text/javascript > var pm_pub_id=9999; // PubMatic Publisher ID. var pm_timeout = 1000; // Optional timeout for PubMatic call. var pm_sync_exec = true; // Optional flag to be used for synchronous GPT. <script type= text/javascript src= //ads.pubmatic.com/adserver/js/dm_gpt_generic.js > OR Load the "gpt.js" tag with a 50 ms delay (average ping time for Akamai CDN) after PubMatic Decision Manager Standard API library load calls are initiated. For example: 8

9 settimeout(function(){ var gads = document.createelement('script'); gads.async = true; gads.type = 'text/javascript'; var usessl = ' == document.location.protocol; gads.src = (usessl? ' : ' + '// var node = document.getelementsbytagname('script')[0]; node.parentnode.insertbefore(gads, node); }, 50); The Decision Manager Standard multi-slot tag is a JavaScript code, which loads as dm_gpt_generic.js. This JavaScript reads ad slot names and the publisher ID while querying the PubMatic ad server for the price of the ad slots. You will need to replace the highlighted text in the below script and host it on your site. <script type='text/javascript'> var pm_pub_id = 9999; // PubMatic Publisher ID. var pm_timeout =1000 // optional timeout for PubMatic call. var pm_sync_exec = true; // Optional flag to be used for synchronous GPT. (function(){ var pmads = document.createelement('script'); pmads.async = true; pmads.type = 'text/javascript'; pmads.src = '//ads.pubmatic.com/adserver/js/dm_gpt_generic.js'; var node = document.getelementsbytagname('script')[0]; node.parentnode.insertbefore(pmads, node); })(); We recommend you deploy it in the head section of your HTML page before the GPT code. It s a special tag that supports getting the price for multiple ad slots on the page using a single ad request. You don t need to deploy separate Decision Manager Standard API tags for each ad slot on your page. This script will: Define the slots based on the GPT ad units. Make the call to PubMatic for the bids. Adding PubMatic bid and other information as targeting to GPT call using key/value Option 2 pairs The following section is applicable for Legacy DART and DFP GPT implementations. For this option, you need to develop additional code for consuming the bid prices and targeting parameters sent by PubMatic. 9

10 Note: Refer to the following demo page to see implementations of the Decision Manager Standard API scripts described below. For login details, please contact your PubMatic account manager. DART legacy tags: GPT tags with synchronous implementation: GPT tags with asynchronous implementation: DART legacy iframe tags: Step :1 Decision Manager multi-slot tag is a JavaScript code, which loads gshowad.js. This JavaScript reads ad slot names and the publisher ID while querying the PubMatic ad server for the price of the ad slots. You need to replace the highlighted text in the below script and host it on your site. The ad slots referred to in the below script indicate ad units names in DFP. // Specify multiple slot names over here var pm_optimize_adslots = ['site2_section2@300x250','site3_section3@300x250']; // PubMatic platform specific publisher identifier var pm_pub_id = 777; // pm_custom is an optional parameter. Pass the key-values applicable for the impression in it to the ad server var pm_async_callback_fn= 'pm_async_callback'; // Optional callback function name <script type="text/javascript" src=" We recommend you deploy it in the head section of your HTML page. It s a special tag that supports fetching the price for multiple ad slots on the page using a single ad request. You don t need to deploy separate Decision Manager Standard tags for each ad slot on your page. This reduces the overall number of Web requests, creating faster page loads and reducing latency. 10

11 Step 2: The Decision Manager Standard tag returns the response in the following format: For Legacy DART: var progkeyvaluemap= { 'site2_section2@300x250': 'bidstatus=0;bid=0;bidid=site2_section2@300x250', site3_section3@300x250': 'bidstatus=1;bid=7;bidid=site3_section3@300x250;wdeal=deal1' }; For DFP GPT: var progkeyvaluemap= { 'site2_section2@300x250': 'bidstatus;0;bid;0;bidid;site2_section2@300x250', 'site3_section3@300x250': 'bidstatus;1;bid;7;bidid;site3_section3@300x250;wdeal;deal1' }; Two global JavaScript variables progkeyvaluemap and biddetailsmap will be available after the response. progkeyvaluemap contains the slot names as a key and comma-separated list of three key-value pairs. bidstatus defines whether PubMatic is able to beat the floor set by the publisher. "bidstatus=1" indicates that PubMatic is able to beat the floor set by the publisher. "bidstatus=0" indicates that PubMatic is unable to beat the floor set by the publisher. bid identifies the price given by PubMatic for the specific ad slot. bidid is the same as the ad slot s name. wdeal is the ID of a PubMatic Marketplace deal that has provided the winning price. If a deal does not win the impression, this field is empty. biddetailsmap is specifically used by PubMatic while rendering creatives. Step 3: Publishers can write their own code to evaluate prices provided by PubMatic and decide whether to serve the PubMatic campaign or pass appropriate key-values to the ad server. 11

12 12

13 if(typeof progkeyvaluemap!='undefined'){ var <!-- Set key value targeting[0] returns key i.e "bidstatus" targeting [1] returns value that is "0/1" similarly targeting[2] and targeting[3] return bid and corresponding value, targeting[4] and targeting[5] represent bidid --> s1.settargeting(targeting[4],targeting[5]); s1.settargeting(targeting[0],targeting[1]); s1.settargeting(targeting[2],targeting[3]); } Step 4: When the publisher s ad server selects the PubMatic campaign, it returns a small JavaScript code including the global variable biddetailsmap for rendering the actual creative. Trafficking the Decision Manager Standard API Campaign in the Ad Server This step is required so impressions can be allocated to PubMatic by the ad server, based on actual bid price and the recommendation from PubMatic. These are passed to the ad server using key-value pairs added to the ad server tags dynamically, as explained in the sections above. Note: The preferred option for the PubMatic TAM team is to support the order creation in DFP. The client just needs to provide trafficker-level access. PubMatic's order insertion tool can be used to insert relevant order into DFP and create granular line items. 13

14 Step 1: Create a new order in DFP for a Decision Manager Standard API with PubMatic as the advertiser and add the relevant details. 14

15 Step 2: Set the price and priority of the line items. Step 3: Set targeting on the bidstatus value as 1 from the Decision Manager Standard API tag s response. In addition to bidstatus, you can also set targeting on bid. For more information, please refer to the Best Practices to Create Tags in the Ad Server section. 15

16 Step 4: Add the Decision Manager Standard API creative provided by PubMatic to the line item you created. For Option 1-based integration: if(!window.dm){ document.write('<script type="text/javascript" src="'+ ( location.protocol === " " : " ) +'//ads.pubmatic.com/adserver/js/dm_gpt_generic.js"><\/script>');} DM.displayCreative("%%PATTERN:bidid%%"); For Option 2-based integration: if(!window.pubmaticgrouped){ document.write('<script type="text/javascript" src="'+ ( location.protocol === " " : " ) +'//ads.pubmatic.com/adserver/js/gshowad.js"><\/script>');} PubMaticGrouped.displayCreative("%%PATTERN:bidid%%"); 16

17 The Decision Manager Standard API for ADTECH This section provides information on how to implement the Decision Manager Standard API for ADTECH. Placing Decision Manager Standard API Script on the Page Note: Refer to the following demo page to see an implementation of the Decision Manager Standard API script described below: For login details, please contact your PubMatic account manager. The Decision Manager Standard multi-slot tag is a JavaScript code, which loads as gshowad.js. This JavaScript reads ad slot names and the publisher ID while querying the PubMatic ad server for the price of the ad slots. Step 1: Replace the highlighted text in the below script and host it on your site. The ad slots referenced in the below script indicate the placement IDs in ADTECH. // Specify multiple slot names over here var pm_optimize_adslots = ['site2_section2@300x250','site3_section3@300x250']; // PubMatic platform specific publisher identifier var pm_pub_id = 7777; <script type="text/javascript" src=" We recommend you deploy it in the head section of your HTML page. It s a special tag that supports getting the price for multiple ad slots on the page using a single ad request. You don t need to deploy separate Decision Manager Standard API tags for each ad slot on your page. 17

18 This reduces the overall number of Web requests, creating faster page loads and reducing latency. Step 2: The Decision Manager Standard API tag returns a response in the following format: var progkeyvaluemap= { 'site2_section2@300x250': 'bidstatus=0;bid=0;bidid=site2_section2@300x250', site3_section3@300x250': 'bidstatus=1;bid=7;bidid=site3_section3@300x250;wdeal=deal1' }; Two global JavaScript variables progkeyvaluemap and biddetailsmap will be available after the response. progkeyvaluemap contains the slot names as a key and comma-separated list of three key-value pairs. bidstatus defines whether PubMatic is able to beat the floor set by the publisher. "bidstatus=1" indicates that PubMatic is able to beat the floor set by the publisher. "bidstatus=0" indicates that PubMatic is unable to beat the floor set by the publisher. bid identifies the price given by PubMatic for the specific ad slot. bidid is the same as the ad slot s name. wdeal is the ID of a PubMatic Marketplace deal that has provided the winning price. If a deal does not win the impression, this field is empty. biddetailsmap is specifically used by PubMatic while rendering creatives. Publishers can write their own code to evaluate prices provided by PubMatic and decide whether to serve the PubMatic campaign or pass appropriate key-values to the ad server. 18

19 Extract Client-sideAPI key-values and format it according to ADTECH specifications: <script type= text/javascript > var //get bidstatus var // get bid var //use ADTECH sub2 - sub4 variable whichever is not currently used. Add key-value to ADTECH call document.write('<scr'+'ipt language="javascript1.1" src=" k;'+t1_k1+';'+t1_k2+';'+t1_k3+'"></scri'+'pt>'); Step 3: When the publisher s ad server selects the PubMatic campaign, it returns a small JavaScript code to include the global variable biddetailsmap for rendering the actual creative. Trafficking the Decision Manager Standard API Campaign in the Ad Server This step is required so impressions can be allocated to PubMatic by the ad server, based on actual bid price and the recommendation from PubMatic. These are passed to the ad server using key-value pairs added to the ad server tags dynamically, as explained in the sections above. For creating Decision Manager Standard API Campaign in ADTECH, use the following process to create campaign and traffic the below-mentioned creative: if(!window.pubmaticgrouped){ document.write('<script type="text/javascript" src="'+ ( location.protocol === " " : " ) +'//ads.pubmatic.com/adserver/js/gshowad.js"><\/script>');} document.write('<script type="text/javascript">pubmaticgrouped.displaycreative("_adsub1_");<\/script>'); Step 1: Create a new campaign in ADTECH for Decision Manager Standard API with PubMatic as the advertiser and add the relevant details. 19

20 Step 2: Set the price and priority of the flights. 20

21 Step 3: Set key-value targeting on bidstatus value as 1 from the Decision Manager Standard API tag s response. In addition to bidstatus, the publisher can also set targeting on bid. For more information, refer to the Best Practices to Create Tags in the Ad Server section. 21

22 The Decision Manager Standard API for OAS For creating the Decision Manager Standard API Campaign in OAS, follow the usual process to create the campaign and traffic the below creative: if(!window.pubmaticgrouped){ document.write('<script type="text/javascript" src="'+ ( location.protocol === " " : " ) +'//ads.pubmatic.com/adserver/js/gshowad.js"><\/script>');} PubMaticGrouped.displayCreative("slot_name@728x90"); For OAS, the demo page URLwill be: 22

23 The Decision Manager Standard API for Other Ad Servers Supporting Key-Value Targeting This section describes implementation of the Decision Manager Standard APIfor any standard ad server supporting key-values. The PubMatic Decision Manager Standard API script that will be implemented on the page is standard and remains the same. Depending on the ad server, there will be changes around the convention of passing the Decision Manager Standard API key-value pairs. In the ad server, create multiple Decision Manager Standard API line items using the tag below and target them to the key bid as per your requirements. if(!window.pubmaticgrouped){ document.write('<script type="text/javascript" src="'+ ( location.protocol === " " : " ) +'//ads.pubmatic.com/adserver/js/gshowad.js"><\/script>');} PubMaticGrouped.displayCreative("slot_name@728x90"); 23

24 Best Practices for Creating Line Items in the Ad Server To control monetization through Client Side API at a granular level, you may: Create multiple Client Side API line items in the ad server for each ad unit/ad size/cpm range/geo. Use bid as the targeting attribute. Place the line items at different priorities based on their pricing and relevance. While creating line items at multiple price points, we recommend you create line items with more granular pricing where the bid density is high. For example: If 80% of the bids are between $0 to $3, create line items at a $0.1 granularity. For other ranges you can create line items at a higher granularity. Here are some variations on how that might look: 30 line items between $0-$3 with rate increment of $0.1 LineItem 1 (covers $0-$0.09) Targeting: bid=0.01*,bid=0.02*...,bid=0.09*, rate=$0.05 LineItem 2 (covers $0.10-$0.19) Targeting: bid=0.1*, rate=$0.15 and so on for next 28 line items 15 Line items between $3-$8 with rate increment of $0.30 LineItem 31 (covers $3.0-$3.29) Targeting: bid=3.0*,bid=3.1*,bid=3.2*, rate=$3.15 LineItem 32 (covers $3.30-$3.59) Targeting: bid=3.3*,bid=3.4*,bid=3.5*, rate=$3.45 and so on for next 13 line items 12 Line items between $9-$20 with rate increment of $1.0 LineItem 46 (covers $9.0-$9.99) Targeting: bid=9.*, rate=$9.5 LineItem 47 (covers $10.0-$10.99) Targeting: bid=10.*, rate=$3.45 and so on for next 10 line items A final high- priority line item for very high bids Line Item 58 (Covers $20 and above) Targeting : bid=20*,bid=21*,bid=22*... bid=50*) rate= $21 24

25 Limitations The PubMatic generic script in Option 1 supports Advanced GPT implementations as per following GPT documentation with limitations around some tags/ads/apps. Please make allowances for the following limitations to ensure the script will run properly. S.No. Name Example!googletag.ContentService 1 Instance of the content service. 2 out-of-page ad slot 3 Passbacks tags 4 Inline display ads googletag.defineoutofpageslot googletag.pubads().definepassback('/ /sports', [468, 60]). settargeting('color', 'red'). settargeting('sport', ['rugby', 'rowing']). display(); googletag.pubads().display('/ /sports', [728, 90], 'div-1'); 5 Video ads NA 6 Mobile apps NA 25