ExpandAd

Expanding an Ad

An important aspect of knowing an ad's effectiveness is understanding how many times it has been in-view in addition to just counting impressions. SafeFrame exposes geometry data to the external party via the ext API.

An example of using the geometry API can be found in the source code under examples/vieability_sample.html and examples/viewability_adfiles

Setup of the Ad

Advertisements are assumed to follow the industry standard mechanism of utilizing document.write to deliver the markup for the advertisement. In the script to deliver the advertisement, we will detect if we are running in a SafeFrame environment and link in to the appropriate event handlers.

1. Detect if the SafeFrame environment is present and register a listener

Add the following code to the advertisement script. Registering a function with the $sf.ext.register
method instructs the SafeFrame framework that the external code should be informed of updates in the environement.

var sfAPI = window.sfAPI || $sf.ext; // Create a ref to the SafeFrame API

//Register the status update listener
if (sfAPI) {
    try {
                    // Register status_update listener with initial ad size (leaderboard)
        sfAPI.register(720, 90, status_update);
    } catch (e) {
        writeLog("Exception or no safeframes available: " + e.message);
    }
}

2. Add the status_update function to receive events

The registered function is fired in response to geometry update events, such as browser scroll and resize, and to other framework requests like ad expansion. A geom-update event is fired from the parent that we will listen for.

function status_update(status, data)
{
    if(status == "expanded"){
            // ad has expanded
    } 
}

3. Expand the ad on load

The ad is expanded by calling the $sf.ext.expand() function. We wrap that call in a function expandAd that confirms the ad has enough space to expand into. We also set the ad to collapse after four seconds.

(function(){
    expandAd();

    window.setTimeout(function(){
        collapseAd();
    }, 4000);
})();

4. Write the expandAd and collapseAd functions

These two helper methods aid in getting the ad to expand how we want, then collapse after a time.

function expandAd(){
    var g, ex;

    writeLog("Ad expand on load - collapse in 4 seconds");

    if ($sf.ext) {
        try {
            g   = $sf.ext.geom(); // the geometry object
            ex  = g && g.exp;
            //if (Math.abs(ex.l) >= 400 && Math.abs(ex.t) >= 200) {
                    $sf.ext.expand(400, 200); //{l:400,t:200}
            //}
        } catch (e) {
            //do not expand, not enough room
        }
    } else {
        //api expansion not supported
    }
}

function collapseAd(){
    $sf.ext.collapse();
}