@ekstra-bladet/jppol-safeframes
v0.0.3
Published
JPPol shared safeframes implementation
Downloads
17
Readme
jppol-safeframes
JPPol shared safeframes implementation
Based on https://github.com/InteractiveAdvertisingBureau/safeframe
Table of Contents
install
npm install "@ekstra-bladet/jppol-safeframes" --save
Safeframe side
Upload the safeframe folder of this project to an external address eg. //ebimg.dk/ux/data/safeframes/
Host side
Include jppolhost.min.js in page Creates an object called jppolAdOps, with the following exposed elements
Initialize JPPol Safeframes from publisher site
safeframeInit
- function
The initialize function takes an object as argument, with safeframeURL and adtechNetworkId as mandatory settings
Initialize function
var sfOptions = {
safeframeURL: '//ebimg.dk/ux/data/safeframes/index.html', // [Path from setup](#safeframe-side)
adtechNetworkId: '123'
}
jppolAdOps.safeframeInit(sfOptions)
Initialize function with prebid enabled
var sfOptions = {
prebid: true,
safeframeURL: '//ebimg.dk/ux/data/safeframes/index-prebid-dac.html', // [Path from setup](#safeframe-side)
adtechNetworkId: '123'
}
jppolAdOps.safeframeInit(sfOptions)
debug info from safeframe
Options
safeframeURL
- Mandatory [string]
Set the URL of were the safeframe HTML file is placed
setup example
var sfOptions = {
safeframeURL: '//ebimg.dk/ux/data/safeframes/index.html' // [Path from setup](#safeframe-side)
}
adtechNetworkId
- Mandatory [string / object]
Set the ADTECH network id, can be passed as an object to differentiate between network ids based on device type
String setup example
var sfOptions = {
adtechNetworkId: '123'
}
Device Object setup example
var sfOptions = {
adtechNetworkId: {
desktop: '123',
smartphone: '123.0',
tablet: '123'
}
}
prebid
- optional [boolean]
Set if prebid should be used or not NB! beware, remember to edit safeframeURL to '.../index-prebid-dac.html'
setup example
var sfOptions = {
prebid: true
}
baseBannerSrc
- Optional [string / object]
- default: '//adserver.adtech.de/addyn/3.0/'
Set the base banner url, from which the final banner script src will be build, can be passed as an object to differentiate between network ids based on device type
String setup example
var sfOptions = {
baseBannerSrc: '//adserver.adtech.de/addyn/3.0/'
}
Device Object setup example
var sfOptions = {
adtechNetworkId: {
desktop: '123',
smartphone: '123.0',
tablet: '123'
}
}
device
- Optional [string]
- default: 'desktop'
Set current device type, used to differentiate adtechNetworkId and baseBannerSrc
Setup example
var sfOptions = {
device: 'desktop'
}
messageCallback
- Optional [function]
See also: Callbacks
Set the function which should be called when the safeframe is triggering onPosMsg An object[example shown below] is passed as argument to the callback function containing 4
Argument example
var messageObject = {
'placement': 'string', // string
'type': 'string', // ['msg'/'error']
'content': 'string', // safeframes doesnt support other types at the moment
'nuked': nuked
}
Init setup example
var sfOptions = {
messageCallback: handleCallBack
}
wallpaper
wallpaperHandler
- Optional [boolean]
- default: false
Should be set to true if wallpaper is an option on the page, usually only for desktop devices
example
var sfOptions = {
wallpaperHandler: true
}
wallpaperSelector
- Optional [string]
Can be body or regular CSS selector / ID
example
var sfOptions = {
wallpaperSelector: 'adtechWallpaper'
}
wallpaperPositions
- Optional [Array / string]
Name of positions of which to check for wallpaper.
example
var sfOptions = {
wallpaperPositions: ['wallpaper','monster']
}
allowNuke
- Optional [boolean]
- default: true
Mainly for debugging purposes
example
var sfOptions = {
allowNuke: true
}
debug
- Optional [boolean]
- default: false (will be set to true, if fulldebug is true)
For debugging purposes Log statements from jppol-safeframes is prefixed with jppol-safeframes, followed by either filename or "inside safeframe"
setup example
var sfOptions = {
debug: false
}
output example
jppol-safeframes: jppolhost.js safeframe posMsg followleft msg safeframeloaded|w160|h604
fulldebug
- Optional [boolean]
- default: false
For debugging purposes BEWARE: This will add debug information directly into the banner container
example
var sfOptions = {
fulldebug: false
}
Calling a banner
To call a specific banner call setupFinalPos with position data
setupFinalPos
- function
Takes an object with all the data needed to create the correct banner
positionData
var positionData = {
placement: 'monster',
bannerID: '4040617',
type: '277',
sfWidth: 930,
sfHeight: 180,
sfZIndex: 1,
shared_data: {
elementPos: document.getElementById(destID).getBoundingClientRect()
}
}
placement
- Mandatory [string]
placement id / name for banner
var positionData = {
placement: 'monster'
}
bannerID
- Mandatory [string]
ADTECH placement ID or alias for banner
var positionData = {
bannerID: '4040617'
}
type
- Mandatory [string]
ADTECH placement type / sizeid
var positionData = {
type: '277'
}
destID
- Mandatory [string]
ID of element to serve banner in
var positionData = {
destID: 'monster_trgt'
}
Dimensions
- Mandatory
- sfWidth [number]
- sfHeight [number]
- sfZIndex [number]
Set the width, height and z-index of the safeframe
var positionData = {
sfWidth: 930,
sfHeight: 180,
sfZIndex: 1
}
keyValues
- optional [array]
Key values to be added to banner called besides criteo, bluekai and rubicon key values Could be prebid key values
var positionData = {
keyValues: ['prebidwhatever=1']
}
shared_data
- Optional [object]
Pass shared data to the safeframe, this data is open to every banner to use
var positionData = {
shared_data: {
elementPos_top: document.getElementById(destID).getBoundingClientRect().top
}
}
Passing private data to banner
privateDataOptions
- Optional [object]
var privateDataOptions = {
key: 'privateKeyForSF',
private_data1: 'Private data',
private_data2: {
more_data: 'More private data'
}
}
Callbacks
Handling special banner formats, like wallpaper, skyskraper(follow) etc.
At the moment safeframes only support strings to be sent from inside the safeframe
load
When the banner is loaded the safeframe sends the a message with the content "safeframeloaded"
data
Since the safeframe API doesnt support objects in messaging, additional data is appended with a pipe [|] If a prebid placeholder is present the prebid type will be appended, otherwise the width and height dimensions will be appended. See example implementation from safeframe below
if (sf_align.querySelector('.prebidPlaceholder') !== null) {
loadedMessage += '|prebid'
} else if (sf_align.querySelector('.prebidPlaceholder_xhb') !== null) {
loadedMessage += '|prebid_xhb'
} else {
loadedMessage += '|w' + sf_align.clientWidth + '|h' + sf_align.clientHeight
}