Link Search Menu Expand Document

PDF

Prebid Client Integration

Apollo

Publisher

Last updated on June 3, 2021


The Prebid Client screen is where you perform a Prebid Client integration. This is where you create new bundles, manage existing ones, deploy changes and a/b tests, and review past deployments. Follow the sections on this page to complete the integration.


on this page


Prior to Starting Your Integration

Prior to starting your integration make sure you consult the Prebid Docs and then answer the following two questions:

  • What do you want your Price Granularity at?
  • How do you want to structure your Prebid reporting in Google Ad Manager (GAM)?
    • Option A: All Prebid Bidders under one set of Order / Lineitems
    • Option B: Each Prebid Bidder having their own sets of Orders / Lineitems

There are both pros and cons for each option:

  • Option A: Easy to set up and requires no maintenance, but you will not be able to do any bid level analysis.
  • Option B: Provides you the ability to calculate bid and win rates for each bidder, but your team will need to manage any new partners that are onboarded.

If your main interest is seeing revenue and not performing an in depth analysis of each bidder, Option A is our suggestion. In addition, Prebid Analytics will allow you to do an in-depth analysis of your performance across bidders even with Option A.

Please reach out to your various SSPs/Prebid Partners and ask them for their required Prebid parameters. It is also helpful if you ask them for a sample of what their bidder should look like.


General Google Ad Manager (GAM) Integration

Once you have answered the questions above, please grant Admin/API access to OpenX via your GAM Account, and we will handle set up for you.


Prebid Client Integration Requirements

The items necessary for a Prebid Client integration are:

  • A Google Ad Manager (GAM) account.
  • An ad unit on GAM with the same type and size as a corresponding Prebid ad unit.
  • A Prebid compatible order on the GAM for the particular ad unit.
  • A bundle in OpenX Apollo with your desired configuration with at least one ad unit.

Creating a Bundle

A bundle contains all of the information necessary to deploy your Prebid.js packages. The following steps show you how to create and deploy a bundle.

To create a bundle:

  1. Click on the Prebid Client tab.

  2. On the top right of the screen, click .

  3. Complete the Bundle Details section:

    In this fieldDo this
    NameEnter a unique bundle name to use as part of the path to your Prebid.js package (javascript file). Use only lowercase letters, numbers, hyphens (-), underscores (_), and dots (.).
    OrganizationYour organization is set by default.
    TypeWeb (Prebid.js) is set by default for a Prebid client configuration.
    TemplateSelect Standard. This template provides a low-code solution for publishers that only use Google Ad Manager. If you follow the implementation documentation and it does not work, proceed to the API implementation.

    Note: The Advanced template provides explicit control of your Prebid.js.
  4. Complete the Prebid.js Configuration section to add any configurations your site will need:

    • initialRefreshOnScriptLoad: Calls googletag.refresh() after initialization. This is used in situations where this is a Standard Template and you do not refreshAds. This is how Prebid knows how to call GAM. If you are not using googletag.pubads().refresh(), set this to true.

           {
               "initialRefreshOnScriptLoad": true,
               "config": {
                   "bidderTimeout": 1500,
                   "priceGranularity": "high",
                   "enableSendAllBids": true
               },
           }
      
    • config: The standard Prebid configuration object. Refer to the Prebid.org Docs for details on possible Prebid.js configuration settings.

       "config": {
           "bidderTimeout": 1500,
           "priceGranularity": "dense",
           "enableSendAllBids": true
         },
      
    • mapping: The mapping configuration will tell us which of your adunits to include in auctions. There are 4 types of object properties available: equals, startsWith, endsWith, and includes. Each key maps to an object of adunit code to Prebid Adunit Objects.

       "mapping": {
         "equals": {
           "div-desktop-1234-0": {
             "mediaTypes": {
                 "banner": {
                     "sizes": [[300, 250]]
                 }
             },
             "bids": [
               {
                 "bidder": "openx",
                 "params": {
                   "unit": "541024394",
                   "delDomain": "sademo-d.openx.net"
                 }
               }, {
                 ...
               }
             ]
           }
         }
       }
      
  5. Complete the bundle creation and deploy it to production by clicking verify its status says “Complete”.

    If you are not still ready to deploy to production, click to save your changes only without deploying the bundle.


Getting the Bundle’s URL

Once you have created and deployed a bundle to production, you can get (copy) the bundle’s URL.

To get the bundle’s URL:

  1. Click on the Prebid Client tab.

  2. From the list, click on the bundle’s name you deployed to production.

  3. On the View Bundle screen, click on the Deployments tab.

  4. From the Deployments list click one of the following:

    • Copy as a script tag: Click on this icon to copy an HTML script component to your clipboard.
    • Copy URL only: Click on this icon to copy the URL to your clipboard.

    URL format example

     https://prebid.openx.net/ox/cdn/<ORG_NAME>/prebid.<BUNDLE_NAME>.js
    

Completing the Integration

To complete the integration:

  1. Add googletag.disableInitialLoad() to your current site:

     googletag.cmd.push(function() {
             googletag.defineSlot('/18064236/TestPage_300x250', [[300, 250]], 'medRec').addService(googletag.pubads());
             googletag.defineSlot('/18064236/TestPage_728x90', [[728, 90]], 'leaderboard').addService(googletag.pubads());
             googletag.pubads().disableInitialLoad();
             googletag.enableServices();
           });
    
  2. Copy the bundle’s URL you obtained earlier, and then add the following script tag to your website’s page:

     <script src="https://prebid.openx.net/ox/cdn/<ORG_NAME>/prebid.<BUNDLE_NAME>.js" async></script>
    

    HTML detailed example

     <html>
       <head>
    
         <script type="text/javascript" async src="https://www.googletagservices.com/tag/js/gpt.js"></script>
         <script src="https://prebid.openx.net/ox/cdn/<ORG_NAME>/prebid.<BUNDLE_NAME>.js" async></script>
    
         <script type="text/javascript">
           var pbjs = pbjs || {};
           pbjs.que = pbjs.que || [];
           var googletag = googletag || {};
           googletag.cmd = googletag.cmd || [];
    
           googletag.cmd.push(function() {
             googletag.defineSlot('/18064236/TestPage_300x250', [[300, 250]], 'medRec').addService(googletag.pubads());
             googletag.defineSlot('/18064236/TestPage_728x90', [[728, 90]], 'leaderboard').addService(googletag.pubads());
             googletag.pubads().disableInitialLoad();
             googletag.enableServices();
           });
         </script>
    
       </head>
    
       <body>
         <button onclick="refreshAdSlots()">Refresh</button>
         <div id="medRec">
           <script>
             googletag.cmd.push(function() {
               googletag.display("medRec");
             });
           </script>
         </div>
         <div id="leaderboard">
           <script>
             googletag.cmd.push(function() {
               googletag.display("leaderboard");
             });
           </script>
         </div>
       </body>
     </html>
    

About the Standard Template

The Standard Template works similar to header bidder tags. Think of it like a prebid-powered header tag. It is intended for publishers who are already using an existing managed Prebid service or publishers new to Prebid.

Implementation steps:

  1. Place our script tag at the top of your page.
  2. Remove prior Prebid.js code from the page.
  3. Only GPT-related code on the page.
  4. Setup GPT with the following commands:
    • googletag.pubads().enableSingleRequest()
    • googletag.pubads().disableInitialLoad()

Add the following script to your page. The PBJS_FAILSAFE_TIMEOUT should be long enough to allow for the code to load but short enough to get ads loaded on page in time if the tag fails.

var PBJS_FAILSAFE_TIMEOUT = 3500;
googletag.cmd.push(function() {
  setTimeout(function() {
    // we call refresh directly if pbjs doesn't initialize
    if(pbjs && pbjs.que && !pbjs.que.unshift){
      googletag.pubads().refresh();
    }
  }, PBJS_FAILSAFE_TIMEOUT)
});

Support

For any support inquiries, feel free to contact the OpenX Apollo support team at apollo-support@openx.com.