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. It 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 Xandr's solution for SafeFrame: sf-ext.js. This was built with AST, but is delivered as a separate component.

SafeFrame feature has many benefits. This includes consumer protection, 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 setting up on-page tags for outstream video in the Microsoft Advertising Help center.

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.

apntag.defineTag({param})

Param 'enableSafeFrame' is added to defineTag which delivers the creative in SafeFrame container.

Parameters

Example

 
var tag = apntag.defineTag({
            enableSafeFrame : true,
            tagId : 10107529, //10066308,
            sizes : [[300,250]],
            targetId: 'apn_ad_40954389053',
           //new field
            safeframeConfig: {
              allowExpansionByPush:true,
              allowExpansionByOverlay:true
            }
          //end new field
        });

apntag.setSafeFrameConfig({param})

This function can be used to configure SafeFrame. 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

Example

apntag.setSafeFrameConfig({
        "allowExpansionByPush" : true,
        "allowExpansionByOverlay" : true
});

apntag.setPageOpts({param})

Parameter enableSafeFrame is added to setPageOpts function. This parameter enables SafeFrame and serves all the all ads in SafeFrame container.

Parameter

Example

apntag.setPageOpts({
        //other setPageOpts params
        "enableSafeFrame" : true
});

Safeframe API function examples

The following examples show how to use the API functions for SafeFrame.

$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

Example

var statusUpdate = function(status) {
        if(status === 'expanded') {
                //do something
        } else if(status == 'collapsed') {
                //do something
        }
}
$sf.ext.register('300','250',statusUpdate);

$sf.ext.supports()

This function returns an object with keys representing which features have been turned on or off for this particular container.

Example

var supports = $sf.ext.supports();
if(supports['exp-ovr']) {
        //expansion by overlay is supported so expand can be called safely with overlay param
}
if(supports['exp-push']) {
        //expansion by push is supported so expand can be called safely with push param
}

$sf.ext.geom()

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

Example

 var g = $sf.ext.geom();
 if (/*check available space to expand before calling expand function*/) {
      $sf.ext.expand(obj);
 }

Scroll Position Example

 var geom = $sf.ext.geom();
 geom.anx.scrollTop; // scrollTop
 geom.anx.scrollLeft; // scrollLeft

This takes into account the eventual scroll position of intermediary same-domain iframe, when AST is itself in an iframe.

$sf.ext.expand({params})

This function 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

Example

$sf.ext.expand({
        'l' : 0,
        'r' : 0,
        't' : 0,
        'b' : 500,
        'push' : true
});

$sf.ext.collapse()

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

Example

$sf.ext.collapse();

$sf.ext.status()

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

Example

$sf.ext.status();