Neglected Parking Meter

    @ekstra-bladet/jppol-safeframes

    0.0.3 • Public • Published

    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

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

    Keywords

    none

    Install

    npm i @ekstra-bladet/jppol-safeframes

    DownloadsWeekly Downloads

    5

    Version

    0.0.3

    License

    ISC

    Last publish

    Collaborators

    • mathiasnordby
    • mbjedk
    • tcarlsen
    • tegner