Skip to end of metadata
Go to start of metadata

SafeFrame API Reference

On This Page


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.

FunctionDescription
$sf.ext.register 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. 
$sf.ext.supports 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.
$sf.ext.geom 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.
$sf.ext.expand The expand function expands the SafeFrame container to the specified geometric position, allowing intermediary expansions. It supports expansion in both push modes.
$sf.ext.collapse  The collapse function collapses the SafeFrame container to the original geometric position.
$sf.ext.status  The status function returns information about the current state of the container. States are: expanded, expanding, collapsed, collapsing
$sf.ext.winHasFocusReturns whether or not the browser window or tab that contains the SafeFrame has focus, or is currently active.
$sf.ext.inViewPercentageReturns 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.


apntag.defineTag({param})

New param 'enableSafeFrame' added to defineTag.

Parameters

NameTypeDescription
enableSafeFramebooleanDelivers the creative in SafeFrame container
          setSafeFrameConfig
        
booleanAllows configuration of SafeFrame, a managed iframe that provides additional consumer protection and publisher control beyond that provided by a standard iframe.

Example


apntag.setSafeFrameConfig({param});

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.

Parameters

NameTypeDescription
allowExpansionByPushbooleanHost can toggle expansion by push using this param.
allowExpansionByOverlaybooleanHost can toggle expansion by overlay using this param

Example


apntag.setPageOpts({param});

New parameter  enableSafeFrame to be added to setPageOpts function. This parameter will enable SafeFrame and will serve all the all ads in SafeFrame container.

Parameters

NameTypeDescription
enableSafeFramebooleanDeliver all creative in safeframe container

Example

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. 

Parameters

NameTypeDescription
widthnumberInitial width of the creative
heightnumberInitial height of the creative
callbackFnfunctionFunction to be called on any operation. In Phase 1 we are supporting 'expanded' and 'collapsed' status in the callback function.


Example 


$sf.ext.supports();

Supports returns an object with keys representing what features have been turned on or off for this particular container.

Example


$sf.ext.geom();

 This method gets the space available around the targetDiv to expand the SafeFrame container. It returns the following object:

Example

Scroll Position

Example

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. 

$sf.ext.expand({params})

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

Parameters :

NameTypeDescription
lnumberThe new left coordinate (x) relative to the current left coordinate. 
rnumberThe new right coordinate (x+width) relative to the current right coordinate(x+width).
tnumberThe new top coordinate (y) relative to the current top coordinate.
bnumberThe new bottom coordinate (y+height) relative to the current top coordinate(y+height).
pushbooleanWhether or not expansion should push the host content, rather than overlay.

Example


$sf.ext.collapse(); 

This method collapses the SafeFrame container to the original geometric position.

Example

 

$sf.ext.status(); 

This method returns the current state of the SafeFrame container. Possible States are expanded, collapsed, ready.

Example

  • No labels