From 4a4b5bff126df92fd0a2e0264750ecdd74ec368a Mon Sep 17 00:00:00 2001 From: Demetrio Girardi Date: Wed, 3 Apr 2024 10:50:09 -0700 Subject: [PATCH] Document JS dynamic creatives (#5120) --- adops/creative-considerations.md | 6 +++- adops/js-dynamic-creative.md | 45 +++++++++++++++++++++++++++ dev-docs/modules/nativeRendering.md | 22 +++++++++++++ overview/prebid-universal-creative.md | 21 +++++++++---- 4 files changed, 87 insertions(+), 7 deletions(-) create mode 100644 adops/js-dynamic-creative.md create mode 100644 dev-docs/modules/nativeRendering.md diff --git a/adops/creative-considerations.md b/adops/creative-considerations.md index 9972238b20..396f19feaa 100644 --- a/adops/creative-considerations.md +++ b/adops/creative-considerations.md @@ -30,10 +30,14 @@ The first decision you’ll need to make when it comes to creatives (with the ex The big advantage to using the PUC is that it’s the simplest approach to configuring Prebid in your ad server. It provides a robust mechanism that can be used across several formats, platforms, devices, and ad servers. -The primary disadvantage to using the PUC is that it takes an extra fetch to load the PUC file vs doing everything inline to the creative. Also, in version 1.14.1 and earlier of the PUC, loading a “universal” creative means that more bytes are loaded than are actually necessary for the display of a single creative. This all leads to a very slight performance penalty. +The primary disadvantage to using the PUC is that it takes an extra fetch to load the PUC file vs doing everything inline to the creative. Also, loading a “universal” creative means that more bytes are loaded than are actually necessary for the display of a single creative. This all leads to a slight performance penalty. You’ll need to determine whether the ease of implementation is worth the small performance penalty. +## Prebid.js dynamic creatives + +If you have line items that target only browsers running Prebid.js, you can use [dynamic creatives](/adops/js-dynamic-creative.html) to avoid the PUC performance penalty but keep the same ease of setup and maintenance. The disadvantage of this approach is that it does not support platforms that do not run Prebid.js, such as AMP or mobile apps. + ## Where to Host the PUC If you choose to use the Prebid Universal Creative, you'll need to decide where to load it from: diff --git a/adops/js-dynamic-creative.md b/adops/js-dynamic-creative.md new file mode 100644 index 0000000000..3eb5fc493a --- /dev/null +++ b/adops/js-dynamic-creative.md @@ -0,0 +1,45 @@ +--- +layout: page_v2 +title: Prebid.js dynamic creatives +head_title: Prebid.js dynamic creatives +sidebarType: 3 +--- + +# Prebid.js dynamic creatives +{:.no_toc} + +- TOC +{: toc} + +## Overview + +For line items that target browsers only, you may use Prebid.js dynamic creatives as an alternative to [Prebid Universal Creative](/overview/prebid-universal-creative.html). The former provides slightly better performance and ease of use, but relies on Prebid.js, meaning that it does not support non-JS use cases (such as mobile apps or AMP). + +## Comparison vs PUC for Prebid.js + +A creative set up to use Prebid Universal Creative: + +- loads a separate script, typically from a CDN; the script contains various rendering routines, including some specific to Prebid.js; +- if the script determines that the ad render was initiated by Prebid.js, it retrieves from it information about the winning bid and renders it; +- requires different setups for different use cases (such as banner vs native). + +A Prebid.js dynamic creative: + +- does not load any additional script - it's instead set up with a small block of inline Javascript; +- it expects to always find Prebid.js, retrieving from it information about the winning bid _and_ the rendering logic to use for it; +- uses the same setup for all cases - but does not work when the render is not initiated by Prebid.js. + +## How to use + +{: .alert.alert-warning :} +Dynamic creatives require Prebid.js version 8.36 or higher. + +Set up the creative following [this example](https://github.com/prebid/Prebid.js/blob/master/integrationExamples/gpt/x-domain/creative.html). If you are not using GAM, replace the macros in the second `script` tag with appropriate equivalents. + +To render native ads, you also need to include the [nativeRendering](/dev-docs/modules/nativeRendering.html) module in your Prebid.js bundle. + +## Further reading + +- [Creative Considerations](/adops/creative-considerations.md) +- [Prebid Universal Creative](/overview/prebid-universal-creative.html) +- [Native rendering module](/dev-docs/modules/nativeRendering.html) diff --git a/dev-docs/modules/nativeRendering.md b/dev-docs/modules/nativeRendering.md new file mode 100644 index 0000000000..c597a3552c --- /dev/null +++ b/dev-docs/modules/nativeRendering.md @@ -0,0 +1,22 @@ +--- +layout: page_v2 +page_type: module +title: Module - Native rendering +description: Render native bids with renderAd or dynamic creatives +module_code : nativeRendering +display_name : Native Rendering +enable_download : true +sidebarType : 1 +--- + +# Native rendering module + +This module enables rendering of native ads through [pbjs.renderAd](/dev-docs/publisher-api-reference/renderAd.html) or [dynamic creatives](/adops/js-dynamic-creative.html). + +There's no configuration necessary except for installing the module; once included, you may use those rendering methods for native bids. If _not_ included, rendering native ads is only supported through [Prebid Universal Creative](/overview/prebid-universal-creative.html). + +## Further reading + +- [renderAd reference](/dev-docs/publisher-api-reference/renderAd.html) +- [Prebid.js dynamic creatives](/adops/js-dynamic-creative.html) +- [Prebid Universal Creative](/overview/prebid-universal-creative.html) diff --git a/overview/prebid-universal-creative.md b/overview/prebid-universal-creative.md index 97fbf0492d..522bd1b2b7 100644 --- a/overview/prebid-universal-creative.md +++ b/overview/prebid-universal-creative.md @@ -24,13 +24,13 @@ when a Prebid ad has won the auction. There are a number of use cases: {: .table .table-bordered .table-striped } | Use Case | PUC file | Alternate Approach | | --- | --- | --- | -| web banner: iframe | banner.js (or creative.js) | [Banner and Outstream Video iframes](#alt-iframes) | -| web banner: safeframe | banner.js (or creative.js) | [Banner Safeframes](#alt-safeframes) | -| web outstream video: iframe | video.js (or creative.js) | [Banner and Outstream Video iframes](#alt-iframes) | +| web banner: iframe | banner.js (or creative.js) | [Dynamic creatives](#alt-dyn), [Banner and Outstream Video iframes](#alt-iframes) | +| web banner: safeframe | banner.js (or creative.js) | [Dynamic creatives](#alt-dyn), [Banner Safeframes](#alt-safeframes) | +| web outstream video: iframe | video.js (or creative.js) | [Dynamic creatives](#alt-dyn), [Banner and Outstream Video iframes](#alt-iframes) | | web outstream video: safeframe | n/a | Outstream renderers each choose where to render differently, but none writes to the safeframe. | | AMP banner: always safeframe | amp.js (or creative.js) | n/a | -| native: iframe | native.js (or native-render.js) | n/a | -| native: safeframe | native.js (or native-render.js) | n/a | +| native: iframe | native.js (or native-render.js) | [Dynamic creatives](#alt-dyn) | +| native: safeframe | native.js (or native-render.js) | [Dynamic creatives](#alt-dyn) | Note that as of PUC v1.15, the recommended way of loading the creative in the ad server involves using the `hb_format` ad server key-value. Before 1.15, the ad server needed to load creative.js which covered banner and outstream video, or native-render.js for native. 1.15 simplifies this @@ -77,6 +77,14 @@ While Prebid recommends the use of creative.js because we regularly add features and fix bugs, publishers may choose to hardcode the functionality into their ad server creatives. + + +### Prebid.js dynamic creatives + +If you only need to display creatives rendered by Prebid.js (as opposed platforms like AMP or mobile SDKs), +you can avoid loading the PUC script - and the performance cost that entails - but still keep some of its advantages, such as regular updates, +by using [Prebid.js dynamic creatives](/adops/js-dynamic-creative.html). + ### Alternate methods for Banner and Outstream Video iframes @@ -97,9 +105,10 @@ If you only ever need to display non-safeframed banner and outstream-video creat If safeframe support is required, some options are: 1. Copy the contents of `https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/creative.js` into each ad server creative. -1. Copy the example at [github.com/prebid/Prebid.js/blob/master/integrationExamples/gpt/x-domain/creative.html](https://github.com/prebid/Prebid.js/blob/master/integrationExamples/gpt/x-domain/creative.html) into each ad server creative. This is basically just part of the PUC that's been isolated to be standalone. +2. [Prebid.js dynamic creatives](/adops/js-dynamic-creative.html) ## Further Reading - [Step by Step Guide to Google Ad Manager Setup](/adops/step-by-step.html) - [Setting up Prebid with the Xandr Monetize Ad Server](/adops/setting-up-prebid-with-the-appnexus-ad-server.html) +- [Prebid.js dynamic creatives](/adops/js-dynamic-creative.html)