SafeFrame API Reference
SafeFrame is a managed, API-enabled iframe. It opens a line of communication between the publisher page content and the iframe-contained external content, such as ads.
SafeFrame operates in a secondary domain provided by the Host, and ideally established on a content delivery network (CDN). This secondary domain serves as an agnostic processing space between the host and external party. Any information that the External Party needs to know about the Host domain is accessed by request, using the SafeFrame API. This API is used to communicate between the host site and external content, using the AppNexus solution for SafeFrame: sf-ext.js. This was built with the AppNexus Seller Tag, but is delivered as a separate component.
The SafeFrame feature has many benefits. This includes consumer protection, and publisher control and efficiency.
SafeFrame and Video
For video customers, SafeFrame is currently only supported for Outstream video placements. If you decide to use this functionality, make sure that you follow the guidelines for enabling SafeFrame in Set Up On-Page Tags for Outstream Video.
Implementation and Functions
- This pertains to the API that is accessible by creatives.
- The following functions are available for communication. These functions are implemented as per IAB Spec.
Portions of the
$sf.ext.geom function will not be implemented until the next phase of this project. It is not as per the IAB Spec at this point in time.
|The external party register function registers the SafeFrame platform to accept SafeFrame external party API calls. The external party creative declares the initial (collapsed) width and height. In addition to width and height, this function can also define a callback function, which informs the external content about various status details.|
|The supports function returns an object with keys representing what features have been turned on or off for a specific: Expansion, Push mode, Read cookie, Write cookie container.|
|The geom function enables an exchange of geometric dimensions and location of the SafeFrame container. This includes its content in relation to the browser or application window, and the screen boundaries of the device in which the host content is being viewed.|
|The expand function expands the SafeFrame container to the specified geometric position, allowing intermediary expansions. It supports expansion in both push modes.|
|The collapse function collapses the SafeFrame container to the original geometric position.|
|The status function returns information about the current state of the container. States are: expanded, expanding, collapsed, collapsing|
|Returns whether or not the browser window or tab that contains the SafeFrame has focus, or is currently active.|
|Returns the percentage of area that a container is in view on the screen as a whole number between 0 and 100. This is as per the IAB Spec. Please reference this for additional detail.|
New param 'enableSafeFrame' added to defineTag.
|boolean||Delivers the creative in SafeFrame container|
|boolean||Allows configuration of SafeFrame, a managed iframe that provides additional consumer protection and publisher control beyond that provided by a standard iframe.|
This function can be used to configure SafeFrame. In phase 1 we have given two options, "allowExpansionByPush" and "allowExpansionByOverlay" for SafeFrame expand API. Configuration by this function will change the return values of $sf.ext.supports function. Publisher can revoke expand permissions from here.
|allowExpansionByPush||boolean||Host can toggle expansion by push using this param.|
|allowExpansionByOverlay||boolean||Host can toggle expansion by overlay using this param|
enableSafeFrame to be added to setPageOpts function. This parameter will enable SafeFrame and will serve all the all ads in SafeFrame container.
|enableSafeFrame||boolean||Deliver all creative in safeframe container|
Page level functions: All AppNexus Seller Tag functions will be page level.
Creative functions : All $sf.ext functions will be called by creative.
Safeframe API Function Examples
$sf.ext.register(width, height, callbackFn) :
The SafeFrame External API register function registers the function to accept SafeFrame external party API calls. External party creative declares the initial (collapsed) width and height and callback function, which informs the external content about various status details.
|width||number||Initial width of the creative|
|height||number||Initial height of the creative|
|callbackFn||function||Function to be called on any operation. In Phase 1 we are supporting 'expanded' and 'collapsed' status in the callback function.|
Supports returns an object with keys representing what features have been turned on or off for this particular container.
This method gets the space available around the targetDiv to expand the SafeFrame container. It returns the following object:
This takes into account the eventual scroll position of intermediary same-domain iframe, when AST is itself in an iframe.
geom.anx is a proprietary extension to the safeframe specification.
This method expands the SafeFrame container to the specified geometric position. All the params are compulsory, so if you are not going to expand left than keep 'left' : 0
|l||number||The new left coordinate (x) relative to the current left coordinate.|
|r||number||The new right coordinate (x+width) relative to the current right coordinate(x+width).|
|t||number||The new top coordinate (y) relative to the current top coordinate.|
|b||number||The new bottom coordinate (y+height) relative to the current top coordinate(y+height).|
|push||boolean||Whether or not expansion should push the host content, rather than overlay.|
This method collapses the SafeFrame container to the original geometric position.
This method returns the current state of the SafeFrame container. Possible States are expanded, collapsed, ready.