Referencia de LA API de SafeFrame

SafeFrame es un iframe administrado habilitado para API. Abre una línea de comunicación entre el contenido de la página del publicador y el contenido externo contenido en iframe, como los anuncios. Funciona en un dominio secundario proporcionado por el host y lo ideal es establecerlo en una red de entrega de contenido (CDN). Este dominio secundario actúa como un espacio de procesamiento independiente entre el host y la entidad externa. Cualquier información que la entidad externa necesita saber sobre el dominio host se accede mediante la solicitud, mediante la API SafeFrame. Esta API se usa para comunicarse entre el sitio host y el contenido externo, mediante la solución de Xandr para SafeFrame: sf-ext.js. Se creó con AST, pero se entrega como un componente independiente.

La característica SafeFrame tiene muchas ventajas. Esto incluye la protección del consumidor, el control del publicador y la eficacia.

SafeFrame y vídeo

En el caso de los clientes de vídeo, SafeFrame solo se admite actualmente para las ubicaciones de vídeo outstream. Si decide usar esta funcionalidad, asegúrese de seguir las directrices para configurar etiquetas en la página para vídeo de secuencias de salida en el Centro de ayuda de Microsoft Advertising.

Implementación y funciones

• Esto pertenece a la API a la que pueden acceder los creativos.
• Las siguientes funciones están disponibles para la comunicación. Estas funciones se implementan según la especificación de IAB.

Función	Descripción
$sf.ext.collapse	La función collapse contrae el contenedor SafeFrame a la posición geométrica original.
$sf.ext.expand	La función expand expand expande el contenedor SafeFrame a la posición geométrica especificada, lo que permite expansiones intermedias. Admite la expansión en ambos modos de inserción.
$sf.ext.geom	La función geom permite un intercambio de dimensiones geométricas y la ubicación del contenedor SafeFrame. Esto incluye su contenido en relación con la ventana del explorador o la aplicación y los límites de pantalla del dispositivo en el que se está viendo el contenido del host.
$sf.ext.inViewPercentage	Devuelve el porcentaje de área que un contenedor está viendo en la pantalla como un número entero entre 0 y 100. Esto es según la especificación de IAB. Para obtener más detalles, consulte esta información.
$sf.ext.register	La función de registro de entidades externas registra la plataforma SafeFrame para aceptar llamadas API de entidades externas safeFrame. La creatividad de entidad externa declara el ancho y el alto iniciales (contraídos). Además del ancho y el alto, esta función también puede definir una función de devolución de llamada, que informa al contenido externo sobre varios detalles de estado.
$sf.ext.status	La función status devuelve información sobre el estado actual del contenedor. Los estados son: expandido, expandido, contraído, contraído
$sf.ext.supports	La función supports devuelve un objeto con claves que representan qué características se han activado o desactivado para un elemento específico: expansión, modo push, cookie de lectura y contenedor de cookies de escritura.
$sf.ext.winHasFocus	Devuelve si la ventana o pestaña del explorador que contiene safeFrame tiene el foco o está activa actualmente.

apntag.defineTag({param})

El parámetro 'enableSafeFrame' se agrega al defineTag que ofrece la creatividad en el contenedor SafeFrame.

Parameters

Nombre	Tipo	Descripción
enableSafeFrame	booleano	Entrega la creatividad en el contenedor SafeFrame.
setSafeFrameConfig	booleano	Permite la configuración de SafeFrame, un iframe administrado que proporciona protección adicional al consumidor y control de publicador más allá del proporcionado por un iframe estándar.

Ejemplo

 
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})

Esta función se puede usar para configurar SafeFrame. Hemos dado dos opciones y allowExpansionByOverlay para allowExpansionByPush SafeFrame expand API. La configuración de esta función cambiará los valores devueltos de la $sf.ext.supports función. Publisher puede revocar permisos de expansión desde aquí.

Parameters

Nombre	Tipo	Descripción
allowExpansionByPush	booleano	El host puede alternar la expansión mediante la inserción mediante este parámetro.
allowExpansionByOverlay	booleano	El host puede alternar la expansión superpuesta mediante este parámetro.

Ejemplo

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

apntag.setPageOpts({param})

El parámetro enableSafeFrame se agrega a la setPageOpts función . Este parámetro habilita SafeFrame y sirve todos los anuncios del contenedor SafeFrame.

Parámetro

Nombre	Tipo	Descripción
enableSafeFrame	booleano	Entrega toda la creatividad en el contenedor safeframe.

Ejemplo

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

Nota:

Funciones de nivel de página: todas las funciones de AST serán de nivel de página. Funciones creativas: creative llamará a todas las funciones $sf.ext.

Ejemplos de funciones de LA API safeframe

En los ejemplos siguientes se muestra cómo usar las funciones de API para SafeFrame.

$sf.ext.register(width, height, callbackFn)

La función de registro de API externa SafeFrame registra la función para aceptar llamadas API de entidades externas SafeFrame. La creatividad de entidad externa declara el ancho inicial (contraído) y la función de alto y devolución de llamada, que informa al contenido externo sobre varios detalles de estado.

Parameters

Nombre	Tipo	Descripción
callbackFn	función	Función a la que se va a llamar en cualquier operación.
height	número	Alto inicial de la creatividad
width	número	Ancho inicial de la creatividad

Ejemplo

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

$sf.ext.supports()

Esta función devuelve un objeto con claves que representan qué características se han activado o desactivado para este contenedor determinado.

Ejemplo

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()

Esta función obtiene el espacio disponible alrededor de targetDiv para expandir el contenedor SafeFrame. Devuelve el siguiente objeto:

Ejemplo

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

Ejemplo de posición de desplazamiento

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

Esto tiene en cuenta la posición de desplazamiento final del iframe del mismo dominio intermedio, cuando AST está en sí mismo en un iframe.

Nota:

geom.anx es una extensión propietaria de la especificación safeframe.

$sf.ext.expand({params})

Esta función expande el contenedor SafeFrame a la posición geométrica especificada. Todos los parámetros son obligatorios, por lo que si no va a expandir a la izquierda que mantener "izquierda": 0

Parameters

Nombre	Tipo	Description
b	número	Nueva coordenada inferior (y+alto) relativa a la coordenada superior actual(y+alto).
l	número	Nueva coordenada izquierda (x) relativa a la coordenada izquierda actual.
push	booleano	Si la expansión debe insertar o no el contenido del host, en lugar de superponerlo.
r	número	Nueva coordenada derecha (x+ancho) relativa a la coordenada derecha actual(x+ancho).
t	número	Nueva coordenada superior (y) relativa a la coordenada superior actual.

Ejemplo

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

$sf.ext.collapse()

Esta función contrae el contenedor SafeFrame en la posición geométrica original.

Ejemplo

$sf.ext.collapse();

$sf.ext.status()

Esta función devuelve el estado actual del contenedor SafeFrame. Los estados posibles son expanded, collapsed, ready.

Ejemplo

$sf.ext.status();