@aller/ads
v0.0.2
Published
Library for doing ads with React
Downloads
4
Keywords
Readme
@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.
| 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 DFP, for example sitename/dagbladet.no/forside
. 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
|
| targeting
| The targeting
paramter accepts an object containing key/value pairs which should attached to the advertisement request. | Object
| Optional
|
| sizemap
| The sizemap
paramter 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
paramter 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 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.
| 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. |
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.