extensions/amp-ad-network-doubleclick-impl/safeframe.md
Google Ad Manager's Fast Fetch implementation supports some aspects of the GPT SafeFrame API for non-AMP creatives that are rendered within a SafeFrame. Please refer to the IAB specification of SafeFrame and the GPT implementation details for a comprehensive explanation of SafeFrame. This document is primarily aimed to explain the AMP-specific differences.
SafeFrame support (including ext.js library injection) can be forced client-side by setting data-force-safeframe=true attribute on amp-ad type=doubleclick elements.
The following methods all work for creatives rendered in SafeFrames via Google Ad Manager Fast Fetch, but have AMP-specific key differences that should be noted:
This method is only supported on AMP pages, it is unavailble elsewhere. This method allows the safeframe to resize both bigger and smaller. Just like for $sf.ext.expand(), you pass in the values that you wish to change the size of the safeframe by for t, b, l, and r. To change positively, you pass in positive values which is equivalent to an expansion. To change size to a smaller size, you pass in negative values. You may not mix positive and negative values in one call.
$sf.ext.resize({t:10, b: 10, l: 20, r:30})
$sf.ext.resize({t:0, b:-10, r:-10, l:0})
$sf.ext.resize({t:-10, b:20, l:-10, r:-15})
For best results, only modify sizes for the b and r parameters, i.e. instead of resizing via: resize({t:10, b:10, r:10, l:10}), instead resize as resize({t:0, b:20, r:20, l:0}). See Important Caveats section under $sf.ext.expand() heading below.
This is a synchronous call for the ad slot's geometry. Geometry is continuously updated in the background to keep the data fresh, with updates being sent from AMP at a maximum of once per second. Returns an object formatted as follows:
{
win: { // The measurement of the application window.
t: 0,
b: 800,
l: 0,
r: 400
},
self: { // The measurement of the SafeFrame, relative to win
t: 100,
b: 150,
l: 10,
r: 330,
},
exp: { // The amount that a SafeFrame can expand
t: 0,
l: 0,
b: 750,
r: 80
},
pos: { // The position of the safeframe, relative to the viewport
t: 0,
l: 0,
b: 50,
r: 320,
},
}
Note that t=Top, b=Bottom, r=Right, and l=Left. See more details below in $sf.ext.expand() section.
Important note about pos: $sf.ext.geom().pos is only available on AMP pages. Do not expect to be able to use that API on other pages. However, you should be able to use win, self, and exp anywhere that safeframe runs, AMP or not.
Important note about exp: Expansion in AMP only technically works to the right, and bottom. There is no notion of expanding left or up. However, in the majority of cases, creatives are centered in the AMP page. Thus, expanding 100 to the right ends up being equivalent to expanding 50 to the left and right. In AMP, the exp values represent how much the creative would need to expand to consume the entire viewport. See more details about expand below.
This API call requests that the SafeFrame be expanded. The parameter passed in is an object that specifies how much to expand in each direction, and whether to expand by push or by overlay (push=true for expand by push, push=false for expand by overlay). However, within AMP, expanding is only supported to the right and bottom.
Example: A creative with height = 50px, width=320px wants to resize to 400x400. The following call should be made:
$sf.ext.expand({t: 0, l: 0, b: 350, r: 80, push: true});
Important Caveats:
Expansion Successes and Failures
AMP has very strict rules in place about when an element can expand. These rules are in place to prevent reflow, which is when an element size changes and causes page content to shift, harming user experience. To prevent reflow for SafeFrame expansion, expand will only succeed in the following scenarios:
The expansion request is made while the SafeFrame is not in viewport. If the SafeFrame is not within the user's viewport at the time a valid expansion request is made, the request to expand will succeed. The AMP runtime is able to control scroll position to assure that reflow does not occur as a result of the expansion.
The expansion request is made for an expanded-size that is less than or equal to the size of the parent amp-ad element. All SafeFrames within AMP are nested within an amp-ad element. amp-ad elements are already laid-out within the page to a specific size. If a creative calls expand() such that the expanded size of the SafeFrame will still be entirely contained within the amp-ad, then expand will succeed regardless of whether the SafeFrame is within the viewport or not.
Example:
Collapse simply returns the ad slot to its original, unexpanded size. If collapse was not preceded by a successful call to $sf.ext.expand() (i.e. if frame is not currently expanded), this will do nothing.
For AMP's implementation of SafeFrame, a collapse() request impacts two separate elements: the amp-ad element that is the parent of the SafeFrame, and the SafeFrame itself. Collapse will always succeed for the SafeFrame, regardless of where it is in the page. However, the amp-ad may not succeed in collapsing if its resize would cause reflow within the viewport. In other words, the amp-ad will only succeed in collapsing if changing its size will not cause reflow, or if its resize is triggered by a user interaction (like clicking a collapse button).
These methods all work the same as they do on non-AMP pages, so please see standard SafeFrame documentation for details