SafeFrame Extensions Proposal

Chris Cole

Extensions to SafeFrame

The SafeFrame Working Group recognizes that implementers will often need to add in their own proprietary functionality or desire to demonstrate new functionality in the wild prior to it becoming fully ratified and formally incorporated into the SafeFrame Specification. To keep from implementations fragmenting, I'm proposing a standard extension namespace and process.

Namespace Extensions and Methods

Extensions may require code to be added to both the host side and the external side of the equation. To accommodate this, the namespace xtra will be added to both. In the reference implementation, there will be a new xtra.js bootstrap file in both areas.

$sf.xtra = {};    // Global extension utility methods here

$sf.host.xtra = {};  // Installed Host-side extensions rooted here

$sf.ext.xtra = {};  // Installed External vendor side extensions rooted here

There will be a single entry point method for registering an extension. This method may be called from the publisher (host) side, vendor (ext) side, or both for extensions that execute across the context. A trivial Hello World example is below:

$sf.xtra.register("helloWorld", 
   { 
     host: { 
         greet: function() { alert('hello host world') } 
     },
     ext: {
         greet: function() { alert('hello vendor ad world') } 
     }
   });

If the SafeFrame framework discovers an init method, it will execute it upon registration. In the case of the ext object, the ad configuration will be passed to init as an argument.

With this script included on both publisher side and vendor side, the extension methods may be accessed as follows:

// host side
$sf.host.xtra['helloWorld'].greet();

// external vendor (ad) side
$sf.ext.xtra['helloWorld'].greet();

Extension Folders in Reference Implementation

Extension code should be placed in the xtra folder located under the appropriate location in the source tree - js, or html. Pull requests must follow this convention to be considered for inclusion in the reference implementation.

Process for Incorporating an extension into the SafeFrame Specification

Extensions may wish to become formally part of the specification and reference implementation. The extension must have a sponsor to be considered for incorporation. The sponsor should start a thread under the Spec Discussion topic of the Discussion area of this project page. This thread should include details on the intent of the extension and pointers to the associated code files.