View as Markdown

Safe Rendering Module

Overview

Since Prebid.js 11.51, the Safe Rendering module adds pbjs.renderBid, which renders a winning bid in an iframe that can’t reach the publisher’s page: a data: URL frame, which has an opaque origin, with the same sandbox attribute Google Ad Manager uses for its SafeFrames. You don’t need GPT or another ad server’s on-page library to handle rendering and SafeFrames, nor a separately hosted creative.

Use it when Prebid.js selects the winner itself, for example when running Prebid.js as an ad server, and you want the creative isolated from the page. Ad servers can still compete as demand, for example by bidding into the auction through their bid adapter. It works with any way of picking the winner, including deal priority.

This is the recommended way to isolate creatives when no ad server’s on-page library handles rendering and SafeFrames. Prefer it to hosting the IAB SafeFrame 1.1 reference implementation or building your own frames. It uses modern browser messaging (a MessageChannel per render, tied to a one-time token), and keeps Prebid.js’s rendering, events and tracking.

Usage

Include the module in your Prebid.js build, then render a bid once the auction ends:

pbjs.requestBids({
  bidsBackHandler: function () {
    pbjs.getHighestCpmBids().forEach(function (bid) {
      pbjs.renderBid(bid);
    });
  }
});

renderBid replaces the contents of the bid’s element with a single iframe and renders the ad inside it. The element is the ad unit’s element, or document.getElementById(adUnitCode) by default. It must belong to the document of the window that loaded Prebid.js, or of a same-origin iframe nested inside that window. It can still be detached from the page: the ad loads once you insert the element.

It honors auctionOptions.suppressStaleRender and auctionOptions.suppressExpiredRender: a suppressed render leaves the element untouched, and emits staleRender or expiredRender rather than adRenderFailed.

Configuration

Param Type Description Default
safeRendering.exclusive Boolean If true, Prebid.js only answers rendering messages from frames created by renderBid, and ignores all others. false
pbjs.setConfig({
  safeRendering: {
    exclusive: true
  }
});

By default, any frame that knows a bid’s adId can message Prebid.js to get that ad’s markup and trigger its rendering logic. This is how ad server creatives such as the Prebid Universal Creative render in GAM SafeFrames. With exclusive: true, only messages carrying the one-time token renderBid gives its frame are accepted.

exclusive: true also turns off rendering through ad server creatives (Prebid Universal Creative, or any creative calling Prebid.js from a cross-origin frame). Only enable it when every ad is rendered with renderBid.

Even without exclusive, once renderBid has been called for a bid, Prebid.js only accepts messages for that bid from a frame renderBid set up for it, over that frame’s channel.

Limitations

  • The SafeFrame $sf API is not provided yet, so creatives that depend on $sf.ext (geometry, expansion) won’t get it.
  • The creative frame has an opaque origin: creatives can’t use cookies or local storage in that frame. Frames the creative itself loads from a real origin can.
  • Bids that would be rendered by a renderer running in the publisher’s page (a top window renderer without a Safe Renderer) are refused. Use a Safe Renderer instead.
  • Your Content Security Policy must allow data: frames (frame-src data:, or child-src if frame-src isn’t set). Otherwise the browser blocks the frame and nothing renders.

Events

A render that can’t start emits adRenderFailed with one of these reasons:

Reason When
missingDocOrAdid The bid has no adId.
cannotFindAd No bid with that adId is known to Prebid.js.
preventWritingOnMainDocument The bid uses a renderer that would run outside the ad frame.
invalidElement The bid’s element is missing, not attached to a window, or not in Prebid.js’s page or a same-origin frame inside it.
exception Setting up the frame threw an error.

Once the frame is set up, rendering reports adRenderSucceeded or adRenderFailed as with other rendering methods.

Further Reading