@aller/ads v0.0.2

@aller/ads

This is a library to help with displaying ads for React based apps (and others). It's a fork-ish of https://github.com/dbmedialab/wolverine-frontend/packages/ads

Displaying an Advertisement

You can display an advertisement by calling the registerAd method, this can be called as many times and wherever you'd like as required.

ads.registerAd({
  id: 'ad-topbanner1',
  slotName: 'dagbladet.no/forsiden',
  dimensions: [[300, 250], [300, 600]],
})

Along with the registerAd call you also need a div on the page with the same id.

<div id="ad-topbanner1"></div>

If you are using an external service to manage initial ad load (like Didomi), set window.blockArcAdsLoad = true on page load to block ArcAds from refreshing ads. Set window.blockArcAdsLoad = false when you want ArcAds to control refreshing ads again.

The following table shows all of the possible parameters the registerAd method accepts.

Out of Page Ads

If an advertisement has an empty or missing dimensions parameter it will be considered as a DFP Out of Page creative and rendered as such.

Callback

Whenever an advertisement loads you can access data about the advertisement such as its size and id by passing in an optional callback to the initialization of ArcAds. This ties a handler to the slotRenderEnded event that DFP emits and is called everytime an advertisement is about to render, allowing you to make any page layout modifications to accomodate a specific advertisement.

const ads = new GPTAds({
  dfp: {
    id: '8578'
  }
}, (event) => {
  console.log('Advertisement has loaded...', event)
})

Refreshing an Advertisement

If you require the ability to refresh a specific advertisement you can do so via the googletag library, providing it the slot object from GPT. You can get access to the slot object in the callback of ArcAds via event.slot.

const ads = new GPTAds({
  dfp: {
    id: '123'
  }
}, (event) => {
  window.adSlot = event.slot
})

// Refresh a single ad slot
window.googletag.pubads().refresh([window.adSlot])

// Refresh all ad slots on the page
window.googletag.pubads().refresh()

Targeting

Advertisement targeting parameters can be passed to the registration call via the targeting object.

arcAds.registerAd({
  id: 'ad-topbanner1',
  slotName: 'dagbladet.no/forside',
  dimensions: [[300, 250], [300, 600]],
  targeting: {
    section: 'weather'
  }
})

Size Mapping

You can configure DFP size mapped ads with the same registration call by adding a sizemap object. To utilize size mapping the dimensions key should be updated to include an array representing a nested array of arrays containing the applicable sizes for a specific breakpoint.

[ [[970, 250], [970, 90], [728, 90]],
  [[728, 90]],
  [[320, 100], [320, 50]] ]

Followed by an array of equal lengths of breakpoints which will sit within sizemap.breakpoints.

[ [1280, 0], [800, 0], [0, 0] ]

When put together this will mean that at a window width of 1280 wide, the service can load a 970x250, 970x90 or a 728x90 advertisement. At 800 wide, it can load a 728x90, and anything below 800 it will load a 320x90 or a 320x50.

If the advertisement should refresh dynamically when the user resizes the screen after the initial load you can toggle refresh to true. otherwise it should be false.

ads.registerAd({
  id: 'ad-topbanner1',
  slotName: 'dagbladet.no/forside',
  dimensions: [ [[970, 250], [970, 90], [728, 90]], [[728, 90]], [[320, 100], [320, 50]] ],
  targeting: {
    section: 'weather'
  },
  sizemap: {
    breakpoints: [ [1280, 0], [800, 0], [0, 0] ],
    refresh: true
  }
})

Prerender Hook

We provide a way for you to get information about an advertisement before it loads, which is useful for attaching targeting data from third party vendors.

You can setup a function within the registerAd call by adding a prerender paramter, the value of which being the function you'd like to fire before the advertisement loads. This function will also fire before the advertisement refreshes if you're using sizemapping.

arcAds.registerAd({
  id: 'ad-topbanner1',
  slotName: 'dagbladet.no/forside',
  dimensions: [[300, 250], [300, 600]],
  prerender: window.adFunction
})

Your prerender function must return a promise. Once it's resolved the advertisement will display. If you do not resolve the promise the advertisement will not render.

window.adFunction = function(ad) {
  return new Promise(function(resolve, reject) {
    // The 'ad' arguement will provide information about the unit
    console.log(ad)
    // If you do not resolve the promise the advertisement will not display
    resolve()
  });
}

You can gather information about the advertisement by accessing the ad argument/object.

Header Bidding

We support prebid only.

Prebid.js

<script src="path/to/prebid.js"></script>
<script src="path/to/arcads.js"></script>

<script type="text/javascript">
  const ads = new GPTAds({
    dfp: {
      id: '123'
    }, 
    bidding: {
      prebid: {
        enabled: true
      }
    }
  })
</script>

You can enable Prebid.js on the wrapper by adding a prebid object to the wrapper initialization and setting enabled: true. You can also optionally pass it a timeout value which corresponds in milliseconds how long Prebid.js will wait until it closs out the bidding for the advertisements on the page. By default the timeout will be set to 700.

const ads = new GPTAds({
  dfp: {
    id: '123'
  },
  bidding: {
    prebid: {
      enabled: true,
      timeout: 1000
    }
  }
}

If you want to use the slotName instead of the ad id when registering ads, pass useSlotForAdUnit: true.

const ads = new GPTAds({
  dfp: {
    id: '123'
  },
  bidding: {
    prebid: {
      enabled: true,
      timeout: 1000,
      useSlotForAdUnit: true
    }
  }
}

On the wrapper you can also configure a size mapping configuration, which will provide information to Prebid.js on which sized advertisements it should fetch bids for on each breakpoint. For more information on what needs to be configured within the sizeConfig array click here.

const arcAds = new ArcAds({
  dfp: {
    id: '123'
  },
  bidding: {
    prebid: {
      enabled: true,
      timeout: 1000,
      sizeConfig: [
        {
          'mediaQuery': '(min-width: 1024px)',
          'sizesSupported': [
            [970, 250],
            [970, 90],
            [728, 90]
          ],
          'labels': ['desktop']
        }, 
        {
          'mediaQuery': '(min-width: 480px) and (max-width: 1023px)',
          'sizesSupported': [
            [728, 90]
          ],
          'labels': ['tablet']
        }, 
        {
          'mediaQuery': '(min-width: 0px)',
          'sizesSupported': [
            [320, 100],
            [320, 50]
          ],
          'labels': ['phone']
        }
      ]
    }
  }
})

On the advertisement registration you can then provide information about which bidding services that specific advertisement should use. You can find a list of paramters that Prebid.js accepts for each adapter on the Prebid.js website. Additionally you can turn on Prebid.js debugging by adding ?pbjs_debug=true to the url.

arcAds.registerAd({
  id: 'ad-topbanner1',
  slotName: 'dagbladet.no/forside',
  adType: 'cube',
  display: 'desktop',
  dimensions: [ [[970, 250], [970, 90], [728, 90]], [[728, 90]], [[320, 100], [320, 50]] ],
  sizemap: {
    breakpoints: [ [1280, 0], [800, 0], [0, 0] ],
    refresh: 'true'
  },
  bidding: {
    prebid: {
      enabled: true,
      bids: [{
        bidder: 'appnexus',
        labels: ['desktop', 'tablet', 'phone'],
        params: {
          placementId: '10433394' 
        }
      }]
    }
  }
})

In certain scenarios you may want to define different sizes for Prebid.js than what you use in GPT. The registerAd method will by default use your dimensions to set these for you, but you can override this by adding a mediaTypes property to your bidding configuration. You can read more about media types on the Prebid.js website.

arcAds.registerAd({
  id: 'ad-topbanner1',
  slotName: 'dagbladet.no/forside',
  dimensions: [ [[970, 250], [970, 90], [728, 90]], [[728, 90]], [[320, 100], [320, 50]] ],
  sizemap: {
    breakpoints: [ [1280, 0], [800, 0], [0, 0] ],
    refresh: 'true'
  },
  bidding: {
    prebid: {
      enabled: true,
      mediaTypes: {
        banner: {
          sizes: [[980, 300], [970, 250]],
        },
      },
      bids: [{
        bidder: 'appnexus',
        labels: ['desktop', 'tablet', 'phone'],
        params: {
          placementId: '10433394' 
        }
      }]
    }
  }
})

Slot Override

You can override the slot name of every advertisement on the page by appending ?adslot= to the URL. This will override whatever is placed inside of the slotName field when invoking the registerAd method. For example if you hit the URL arcpublishing.com/?adslot=homepage/myad, the full ad slot path will end up being your DFP id followed by the value: 123/homepage/myad.

You can also debug slot names and GPT in general by typing window.googletag.openConsole() into the browsers developer console.