ArcAds

ArcAds is a GPT (Google Publisher Tag) wrapper created by Arc XP. Using ArcAds you can make use of many GPT features such as size mapping, refreshing, and targeting. In addition you can also make use of header bidding vendors such as Prebid.js and Amazon A9/TAM by using the appropriate configuration.

Getting Started

To get started you must include the script tag for ArcAds in your page header, located here. You can also optionally run npm install followed by npm run build to compile it yourself in case you need to make any modifications. Once included you can initialize the ArcAds wrapper class like so in your page header.

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

<script type="text/javascript">
  const arcAds = new ArcAds({
    dfp: {
      id: '123',
      collapseEmptyDivs: true
    }
  })
</script>

collapseEmptyDivs is an optional parameter that directly toggles googletag.pubads().collapseEmptyDivs()

Alternatively, if you're using a bundler you can use the library as a module.

npm install arcads 

You can then include it in your own JavaScript projects like so.

import { ArcAds } from 'arcads'

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.

arcAds.registerAd({
  id: 'div-id-123',
  slotName: 'hp/hp-1',
  dimensions: [[300, 250], [300, 600]],
  display: 'desktop'
})

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

<div id="div-id-123"></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.

| Parameter | Description | Type | Requirement | | ------------- | ------------- | ------------- | ------------- | | id | The id parameter corresponds to a div id on the page that the advertisement should render into. | String | Required | | slotName | The slotName parameter is equal to the slot name configured within GPT, for example sitename/hp/hp-1. The publisher ID gets attached to the slot name within the ArcAds logic. | String | Required | | dimensions | The dimensions parameter should be an array with array of arrays containing the advertisement sizes the slot can load. If left empty the advertisement will be considered as an out of page unit. | Array | Optional | | adType | The adType parameter should describe the type of advertisement, for instance leaderboard or cube. | String | Optional | | display | The display parameter determines which user agents can render the advertisement. The available choices are desktop, mobile, or all. If a value is not provided it will default to all. | String | Optional | | targeting | The targeting parameter accepts an object containing key/value pairs which should attached to the advertisement request. | Object | Optional | | sizemap | The sizemap parameter accepts an object containing information about the advertisements size mapping, for more information refer to the Size Mapping portion of the readme. | Object | Optional | | bidding | The bidding parameter accepts an object containing information about the advertisements header bidding vendors, for more information refer to the Header Bidding portion of the readme. | Object | Optional | | prerender | The prerender parameter accepts an a function that should fire before the advertisement loads, for more information refer to the Prerender Hook portion of the readme. | Function | Optional |

Out of Page Ads

If an advertisement has an empty or missing dimensions parameter it will be considered as a GPT 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 GPT emits and is called every time an advertisement is about to render, allowing you to make any page layout modifications to accommodate a specific advertisement.

const arcAds = new ArcAds({
  dfp: {
    id: '123'
  }
}, (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 arcAds = new ArcAds({
  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: 'div-id-123',
  slotName: 'hp/hp-1',
  adType: 'cube',
  dimensions: [[300, 250], [300, 600]],
  display: 'all',
  targeting: {
    section: 'weather'
  }
})

The service will automatically give the advertisement a position target key/value pair if either the targeting object or position key of the targeting object are not present. The position value will increment by 1 in sequence for each of the same adType on the page. This is a common practice between ad traffickers so this behavior is baked in, only if the trafficker makes use of this targeting will it have any effect on the advertisement rendering.

If adType is excluded from the registerAd call the automatic position targeting will not be included.

Size Mapping

You can configure GPT 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.

arcAds.registerAd({
  id: 'div-id-123',
  slotName: 'hp/hp-1',
  adType: 'cube',
  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

ArcAds provides 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 parameter, 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: 'div-id-123',
  slotName: 'hp/hp-1',
  dimensions: [[300, 250], [300, 600]],
  display: 'desktop',
  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' argument 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.

| Key | Description | | ------------- | ------------- | | adUnit | An object containing the GPT ad slot. This can be used when calling other GPT methods. | | adSlot | Contains a string with the full slot name of the advertisement. | | adDimensions | Contains an array with the size of the advertisement which is about to load. | | adId | Contains a string with the id of the advertisement. |

For a more detailed example of how to utilize this functionality please see the wiki.

Header Bidding

ArcAds supports Prebid.js and Amazon TAM/A9. To enable these services you must first enable them when you configure the wrapper.

Prebid.js

If you'd like to include Prebid.js you must include the library before arcads.js. You can get a customized version of Prebid.js with the adapters your site needs from their website here.

<scri