Viewable Data

Viewable Data

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/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 == "geom-update") {
        updateInViewDisplay();
    }
}

3. Query the framework for viewability data

The SafeFrame framework exposes a convenience method to obtain the viewable calculation of the ad.

function updateInViewDisplay(){
	var totalViewable = $sf.ext.inViewPercentage();
            // Update a display
	var elem = document.getElementById("viewInfo");
	elem.innerHTML = "Viewable: " + totalViewable + "%";
}

From this point your ad can report on viewability via a beacon.