Get started with Google Publisher Tag

Render creatives using SafeFrame

Learn about using SafeFrame for communication between advertiser and publisher content

From January 24, 2022, SafeFrame will always use randomized subdomains to isolate SafeFrame content and provide stronger security guarantees. This means the SafeFrame security setting will no longer be available.

If you previously selected the "Fixed" setting, your SafeFrame security will be updated.

SafeFrame is an API-capable iframe that provides a single, unified mechanism for communication between advertiser and publisher content. SafeFrame technology in Ad Manager provides transparent and rich interactions between page content and ads, while preventing external access to sensitive data and providing more granular control over which creatives are rendered using the SafeFrame container with GPT.

IAB standards require publishers to update their websites to render ads inside SafeFrame containers. However, SafeFrame is supported in Ad Manager and activated by default when using GPT tags.

To minimize the chances of malicious creatives serving, we recommend activating SafeFrame whenever possible, in conjunction with the HTML5 sandbox attribute to prevent top-level navigation. Learn more about the sandbox attribute

For detailed information, including the full SafeFrame specification, read the IAB documentation.

SafeFrame and creative types

SafeFrame is either ON or OFF by default depending on the display creative type being used.

Activating SafeFrame for a creative that is intended to serve in a non-SafeFrame page or vice versa may cause rendering issues for the creative. Understand where the creative is intended to serve and set SafeFrame accordingly.

SafeFrame and Google Publisher Tag (GPT)

In Ad Manager, you can explicitly control if a creative is rendered using a SafeFrame for four types of creatives:

  • custom
  • third-party
  • system-defined templates
  • user-defined templates

Select the Serve into a SafeFrame checkbox when adding a new creative or template for these creative types.

Before turning on SafeFrame, work with the advertisers or vendors who provide your creatives to determine if those creatives are SafeFrame-compatible. If you're using the sandbox attribute, work with the agency or advertiser to ensure that clicks open the landing page in a new tab rather than navigating from the current page.

SafeFrame does not support creative preview.

developer documentationYou can use the Google Publisher Tag API to force any particular ad slot or all slots on a page to render using a SafeFrame container with the setForceSafeFrame parameter.

SafeFrame with AMP pages

The SafeFrame API is compatible with any non-AMPHTML ad that serves on an AMP page using Ad Manager AMP ad tags.

The maximum expansion size of the SafeFrame container is limited to that of the viewport. SafeFrame doesn't allow ad slots within the viewport to resize for AMP pages, so a creative's request to resize is only honored when the ad slot is outside of the viewport.

For AMP pages, standard HTML creatives are always served into SafeFrame, regardless of your selection. Please make sure your creative code is compatible with SafeFrame.

AMPHTML ads

AMPHTML ads don't serve into SafeFrames; instead, because AMPHTML is more secure, they serve into friendly iframes by default.

If you have a Content Security Policy (CSP) on your site, the restrictions of the CSP also apply to AMPHTML ads in friendly iframes. In that case, call googletag.pubads().setForceSafeFrame(true) before making any ad requests, to allow the ad to render in a cross-domain iframe without the CSP's restrictions.

How SafeFrame works

The GPT SafeFrame integration consists of three parts:

  1. The SafeFrame iframe container itself, created by GPT when the ad displays.
  2. Code inserted within the creative, providing the (external) SafeFrame API to the creative and communicating to the host page using postMessage.
  3. Code running outside the SafeFrame iframe as part of GPT which is the other end of the postMessage communication channel. This code performs all of the expansion and geometric measurement for viewability.

Ad Manager supports creatives that use a Safeframe API to interact with websites, such as expanding an ad slot (either as a pushdown or an overlay) when a user clicks on an ad. However, you must modify your tag to allow expansion of ad slots and allow pushdown/overlay interaction with the setSafeFrameConfig function.

GPT does not externally host this API implementation, as the rendering of the SafeFrame is handled by GPT. You can continue using the GPT API to set up your ads without any changes to your GPT.

GPT implements the SafeFrame external party API to allow creatives to interact with the website.

Supported SafeFrame API methods

Download the full SafeFrame API spec.

$sf.ext.register
$sf.ext.supports
$sf.ext.geom
$sf.ext.status
$sf.ext.inViewPercentage

/* supports expansion in both push and overlay modes;
not supported for fluid-sized native ads */
$sf.ext.expand

Unsupported or partially supported API methods

  • $sf.ext.cookie is not supported as we don't allow creatives to access publisher cookies.
  • $sf.ext.meta is not supported for publisher defined objects and limited to following system defined objects:
    • {String} sf_ver The string representation of the current version of SafeFrame.
    • {Number} ck_on Identified whether cookies are activated on the browser: 1 for true, 0 for false.

Rich media and viewability with SafeFrame

SafeFrame increases publisher control by limiting interaction between ads and publisher content to those that can be achieved through methods available in the API. The technology standardizes rich media formats, so that creatives using the API can run on any network that supports SafeFrame.

Viewability

The SafeFrame provided API can be used to calculate viewability. While SafeFrame 1.0 does not directly report viewability metrics, the API allows for access to creative information that can be used by the advertiser to determine whether or not the SafeFrame container is "in view."

Available via the API are the geometric dimensions and location of the SafeFrame container and its content, in relation to the browser or application window, and the screen boundaries. Duration information can be derived by registering a listener to determine how long the ad is viewable.

Active View, which is a Google provided solution for viewable impressions, is not part of the SafeFrame viewability specification. This will continue to function without any change.

Use the Google Publisher Console

You can use the Google Publisher Console to see if a slot is using SafeFrame.

Was this helpful?

How can we improve it?
Search
Clear search
Close search
Google apps
Main menu
6801528008059518942
true
Search Help Center
true
true
true
true
true
148
false
false