OpenAds script activation

The process of activating OpenAds to your webpage is similar to incorporating header-bidding technology but with some minor configuration differences. This guide highlights where OpenAds differs from a typical Prebid.js and Prebid Server setup. For information on the server-side demand solicitation pattern used by OpenAds, see Use Case: Prebid Server | Prebid.js in the Prebid documentation.

NOTE: OpenAds currently retrieves demand only from The Trade Desk; additional third-party SSP and DSP support is coming soon.

What you need to know

Here's what you need to know about activation with OpenAds:

• Supported ad types: OpenAds currently supports only the following ads:
  • Banner
  • Video
• Bid requests: Based on the configured ad units, the OpenAds.js script calls the OpenAds Server for bids.
  • The response mirrors the format used by the Prebid Server.
  • To prevent collisions, the OpenAds Server targeting keys use the oa_ targeting keys instead of hb_. For details on ad server targeting keys, see Key Values in the Prebid documentation.
• Multiple wrappers: OpenAds supports multiple wrappers.
  • To ensure compliance with IAB Tech Lab guidelines, we recommend syncing the impression transaction ID across multiple wrappers. For details, see OpenAds Synchronization.
  • If your page runs both Prebid.js and OpenAds.js scripts, wait for bids from each wrapper before sending the ad server request. For a code sample, see Run Prebid.js and OpenAds.js concurrently.

Workflow overview

IMPORTANT: Do not add the OpenAds.js script to any pages until you have been fully configured to receive OpenAds responses. Doing so prematurely may result in errors or incomplete integrations. For details, see OpenAds user identity.

The following table summarizes the OpenAds integration workflow and links to detailed instructions to integrate OpenAds into a webpage for banner or video ads.

The following sections provide instructions and relevant code samples for each step.

Add the OpenAds script

Replace the src placeholder value with the customized JS library provided to you during onboarding and add the hosted OpenAds Javascript as high as possible in the header.

TIP: To avoid any race conditions on slow network connections, instantiate an oajs stub beforehand.

<script>
  var oajs = oajs || {};
  oajs.que = oajs.que || [];
</script>
<script async src="CUSTOMIZED_JS_LIBRARY_PLACEHOLDER"></script>

Configure a template

Further down the webpage, configure OpenAds using a configuration template that is largely compatible with a pbjs configuration object. For example, if you don't want to use server-side caching for video creatives, leave the extPrebid.cache object empty. Similarly, adjust the targeting.pricegranularity ranges to your needs.

IMPORTANT: The s2sConfig key value must be an object (not an array) and must match the following sample.

oajs.setConfig({
  ...
  s2sConfig: {
    enabled: true,
    timeout: 1000,
    extOpenAds: {
      cache: {
        bids: { returnCreative: true },
        vastxml: { returnCreative: false }
      },
      targeting: {
        pricegranularity: {
          ranges: [
            { max: 5.00, increment: 0.50 },
            { max: 10.00, increment: 1.00 },
            { max: 20.00, increment: 2.00 },
            { max: 40.00, increment: 5.00 }
          ]
        },
        includewinners: true
      }
    }
  }
});

IMPORTANT: Starting from version 1.2, OpenAds supplies your credentials and endpoints inside the binary file provided at your customized library URL. If your OpenAds is below version 1.2, contact your Technical Account Manager to upgrade to version 1.2 or higher.

As an alternative option, you can manually input your credentials into the additional fields of the s2sConfig configuration. The following example shows additional configuration for earlier versions of OpenAds.

oajs.setConfig({
  s2sConfig: {
    accountId: "YOUR_ACCOUNT_ID_PLACEHOLDER",
    bidders: ['thetradedesk'],
    endpoint: 'https://openads.adsrvr.org/openrtb2/auction',
    syncEndpoint: 'https://openads.adsrvr.org/cookie_sync',
  }
});

TIP: To find the your account ID, follow the OpenAds onboarding checklist.

Create ad units

Add ad units to the page to conduct auctions with OpenAds. For example, as shown in the following code snippet:

    ...
    var adUnits = [{
    code: 'ad-slot',
    mediaTypes: {
      banner: {
        sizes: [[300, 250]]
      }
    },
    bids: [{
      bidder: 'thetradedesk',
      params: {
        publisherId: 'PUBLISHER_ID_PLACEHOLDER',
        supplySourceId: 'YOUR_ACCOUNT_ID_PLACEHOLDER'
      }
    }]
  }];

  oajs.addAdUnits(adUnits);

  oajs.requestBids({
    timeout: 2000,
    adUnitCodes: [
      // ...
    ]
  });

TIP: If you see a "Null bidder" or "HTTP 400 Error: must contain at least one bidder" message, it means the ad unit was never assigned. Fix this by adding the ad unit to your oajs stub.

Next steps

After you've fully configured your oa.js script, see Test your OpenAds.js installation for a list of events and signals to verify.

FAQs

The following are frequently asked questions about integrating with OpenAds.

What is OpenAds exactly?

OpenAds is The Trade Desk’s initiative to create a cleaner, more transparent programmatic ad auction. For details, see OpenAds: Enabling the most trusted, efficient ad auction in the Resource Desk.

Who can use OpenAds?

Any publishers interested in validating the fairness of the auction can use OpenAds.

Does OpenAds support native ads?

Native ads support is planned to be added by the end of the year.

Can I use both Prebid.js and OpenAds.js wrappers?

Yes. For a code sample, see Run Prebid.js and OpenAds.js concurrently.

Does Google Ad Manager support header bidding trafficking for OpenAds?

No. Header bidding trafficking does not support OpenAds. You must create line items. For details, see Create line items in GAM.