@ekstra-bladet/jppol-safeframes v0.0.3

jppol-safeframes

JPPol shared safeframes implementation

Based on https://github.com/InteractiveAdvertisingBureau/safeframe

Table of Contents

1. Install
2. Safeframe side setup
3. Host side setup
4. Calling banner
5. Special formats - Callbacks

install

View package on npm

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

• safeframeInit
• setupFinalPos

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

Se debug

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