Decision Manager Premium for DFP Technical Integration Guide. Version 3.4

Transcription

1 Decision Manager Premium for DFP Technical Integration Guide Version 3.4 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 2

3 Change History Version Date Changes nd December, nd November, 2015 Updated the Placing Decision Manager Premium Script on the Page section Name changed as per new Product rebranding Added a note in the Placing Decision Manager Premium Script on the Page section th August, th August, 2015 Edited for clarity, grammar, editorial style. Re-structured the document into PubMatic template Added a script in the Placing Decision Manager Premium Script on the Page section th Jan, 2015 Re-structured the DFP and ADTECH details in the DM guide into two separate guides Added details and screenshots about the ADTECH campaign creation in the DM and CS API guides th July, 2014 Initial Release 3

4

5 Table of Contents Overview... 7 Decision Manager Premium Workflow... 7 Decision Manager Premium Implementation... 9 Integrating with a Publisher s Ad Server... 9 Placing Decision Manager Premium Script on the Page Trafficking a Decision Manager Premium Campaign in the Ad Server v

6

7 Overview A publisher's guaranteed and non-guaranteed campaigns are typically executed in silos. The assumption is that non-guaranteed buyers pay a lower price, which is reflected in the priority and non-guaranteed demand they receive in the publisher s ad server. As more advertising budgets shift to programmatic channels, there is a need for publishers to be able to evaluate all available demand to allow for true optimization. Decision Manager Premium (DMP) empowers publishers to achieve this by comparing pricing for each impression across all channels before the ad server makes the decision. By using Decision Manager Premium, publishers can: Increase revenue by capturing extra advertising dollars from the high-value spot demand obtained from the non-guaranteed marketplace. Obtain real-time guidance for their direct sales strategies, as they are able to see the programmatic demand for each impression. Decision Manager Premium Workflow 7

8 1. Decision Manager Premium s JavaScript code, placed on a publisher s site, makes an ad call to PubMatic before contacting the ad server. It is a single ad call covering all the placements on the page. 2. PubMatic sends back a bid response from open and private RTB marketplaces for all the placements on the page. i) The campaign data present in the publisher s ad server (priority, pacing and targeting) is taken into account while evaluating the impression for optimization and determining the price floor for the programmatic marketplace. ii) PubMatic Deal Management and Brand Control rules are also taken into account in the auction, in an effort to drive higher value and maintain brand standards. 3. PubMatic s bid response is sent to the publisher s ad server by adding this response dynamically as a key-value to the existing ad server tags. PubMatic Decision Manager Premium line items are created in the publisher s ad server at various priorities targeting the bid response from PubMatic. 4. Publisher s ad server makes the final decision on which campaign/line item to serve with PubMatic s bid response as an additional parameter. Lastly, the ad is served. 8

9 Decision Manager Premium Implementation Decision Manager Premium provides the pricing from open and private marketplaces for ad slots that publishers can consume by passing key-value pairs to the ad server in real time. Integrating with a Publisher s Ad Server Decision Manager Premium must be integrated with a publisher s ad server so it can use the direct campaigns CPM and pacing to make the right decisions. a) Enabling API access i) Enable network-level API access: ii) Provide read-only API access to an account (a new Gmail ID is recommended) provided by PubMatic with the following basic permissions: 9

10 b) Provide the network ID for your DFP account to PubMatic to complete the integration. Placing Decision Manager Premium Script on the Page There are two methods by which you can place the Decision Manager Premium script on your site: Integration Advantages Options Option 1 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 Integration can be customized Disadvantages Applicable only for DFP GPT Integration cannot be customized Requires more time for additional development Need to specify the ad slots' names 10

11 Additional code required for consuming the bid prices or targeting parameters sent by PubMatic Option 1 The following section is applicable only for DFP GPT implementation. In 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 implemented with the DMP script shown below- For login details, please contact your PubMatic Account Manager. To ensure that the DMP script loads before GPT, it is recommended to load "gpt.js" with a 50 ms delay (standard ping time for the Akamai CDN) after the DMP script calls are initiated. Example: 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); Decision Manager Premium s 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. The publisher needs to replace the highlighted text in the script shown below and host it on its site. <script type='text/javascript'> var pm_pub_id = 9999; // PubMatic Publisher ID. var pm_dm_enabled = true; // For DM Premium implementation. var pm_timeout =500; // optional timeout for PubMatic call. (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); })(); </script> 11

12 We recommend deploying 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 Premium tags for each ad slot on your page. This script performs the following actions: Defines the slots based on the GPT ad units. Makes the call to PubMatic for the bids. Adds PubMatic bid's details as targeting to the GPT call. The following example shows a synchronous version of the DMP script. We recommend using this 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_dm_enabled = true; // For DM Premium implementation. var pm_timeout =800; // optional timeout for PubMatic call. </script> 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"> </script> Option 2 In this option, which is applicable for Legacy DART and DFP GPT implementations, you need to develop additional code for consuming the bid prices and targeting parameters sent by PubMatic. Note: Refer to the following demo pages implemented with the DMP script shown 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

13 1. Decision Manager Premium s 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. The publisher needs to replace the highlighted text in the script shown below and host it on its site. The ad slots referenced in the script indicate the ad units names in DFP. Note: Synchronous JavaScript load on page to ensure that PubMatic loads before GPT library. This is helpful for publishers who are putting our code directly on page. Ensure that we should call out this is just synchronous loading of our JS library all the ad-calls will be asynchronous. <script type = "text/javascript" > //Specify multiple slot names over here var pm_optimize_adslots = [ '/networkid/adunitid1@300x250', '/networkid/adunitid2@300x250' ]; // PubMatic platform specific publisher identifier var pm_pub_id = ; // For DM Premium implementation var pm_dm_enabled = true; // pm_custom is an optional parameter. Pass the key - values applicable for the impression in it to the ad server var pm_custom = " age=25;interest=music,car;gender=male "; </script> <script type = "text/javascript" src = " " > </script> Note: The slot name sent to PM in DM premium should be exactly same as that of the full name of DFP adunit name. The full name should typically start with networkid, so the adslot name format would be `/networkid/adunitlevel1/adunitlevel2/adunitid@size`. We recommend deploying 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 Premium tags for each ad slot on your page. This reduces the overall number of Web requests to make page loads faster and reduce latency. 2. The Decision Manager Premium tag returns the response in the following format: For Legacy DART: 13

14 var progkeyvaluemap= { 'site2_section2@300x250': 'bidstatus=0;bid=2.2;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;2.2;bidid;site2_section2@300x250', 'site3_section3@300x250': 'bidstatus;1;bid;7;bidid;site3_section3@300x250;wdeal;deal1' }; Two global JavaScript variables biddetailsmap and progkeyvaluemap will be available after the response. progkeyvaluemap Contains the slot names as a key and comma-separated list of 3 key-value pairs. bidstatus defines whether PubMatic is able to beat the publisher s ad server s campaign prices or any other specific floor set by the publisher. "bidstatus=1" indicates that PubMatic should serve ahead of guaranteed campaigns. "bidstatus=2" indicates that PubMatic should serve ahead of other non-guaranteed campaigns but below guaranteed campaigns. "bidstatus=3" indicates that PubMatic should serve at the lowest priority. bid identifies the price given by PubMatic for the specific ad slot. bidid is the same as the ad slot s name. wdeal indicates the ID of the PubMatic Marketplace deal that has provided the winning price. If a deal does not win the impression this field is empty. biddetailsmap This is used by PubMatic while rendering creatives. 3. Publishers can write their own code to consume prices provided by PubMatic and decide whether to serve the PubMatic campaign or pass appropriate key-values to the ad server. 14

15 if(typeof progkeyvaluemap!='undefined'){ var <!-- Set key value targeting[0] returns key i.e "bidstatus" targeting [1] returns value that is "0/1/2/3" 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]); } 4. 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. 15

16 Trafficking a Decision Manager Premium 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 dynamically to the ad server tags, as explained above. a. Create a new order in DFP for Decision Manager Premium. Specify PubMatic as the advertiser and add the relevant details. b. Set the price and priority of the line items. You need to create three line items for Decision Manager Premium as detailed below. Ensure that you also set the goal for each of these line items at an appropriate value; it is recommended to set it at 100% 16

17 For "bidstatus=1", the line item's type should be "Sponsorship" and priority should be Low. For "bidstatus=2", the line item's type should be "Network" and priority should be above other non-guaranteed line items but below guaranteed line items ( High ). The "Rate" field should be set at a value that is higher than other non-guaranteed line items For "bidstatus=3", the line item's type should be "Network" and priority should be below all non-guaranteed line items ( Low ). The "Rate" field should be set at a value that is lower than other non-guaranteed line items. c. Set targeting on the bidstatus value from the DMP tag s response in each line item as described in the previous step. 17

18 d. Add the DMP creative provided by PubMatic to the line item created. For Option 1-based integration: <script type="text/javascript"> if(!window.dm){ document.write('<script type="text/javascript" src="'+ ( location.protocol === " " : " ) +'//ads.pubmatic.com/adserver/js/dm_gpt_generic.js"><\/script>');} </script> <script type="text/javascript"> DM.displayCreative("%%PATTERN:bidid%%"); </script> For Option 2-based integration: <script type="text/javascript"> if(!window.pubmaticgrouped){ document.write('<script type="text/javascript" src="'+ ( location.protocol === " " : " ) +'//ads.pubmatic.com/adserver/js/gshowad.js"><\/script>');} </script> <script type="text/javascript"> PubMaticGrouped.displayCreative("%%PATTERN:bidid%%"); </script> Note: If the publisher's page contains multiple ad slots with same size then, there should be multiple copies of the same size creative created for the DM line items. 18