Ad units

Ad units are placeholder elements decorated with a little information about their intended content. Ad units are controlled by the ad manager and served via DoubleClick for Publishers (DFP).

Advertisements are targeted based on meta data about the current page provided by an inline JS configuration ( The configuration provides information such as the destination and country the page content is about and the current page layout. Each ad unit can be further targeted by decorating it with extra meta data.

The ad manager is initialised within lib/core/base.js which should be included within every application.


Each ad unit type is available as a Rizzo UI component. The available ad types are:

  • ad_sense
  • leaderboard
  • mpu
  • sponsor_logo
  • sponsor_logo_html
  • traffic_driver_html
= ui_component("ads/leaderboard", properties: {...})

Ad components can be configured in three ways:

Size mapping
Size maps allow for loading differently sized ads based on the viewport. We use this as well to differentiate ad units based on their context.
Certain ad unit types require a callback to further configure them, for instance a double height MPU unit within a card stack needs to make space for itself.
Ad units can be decorated with extra data about themselves to better target ads. It's sensible to add a position property.
// Include a simple HTML traffic driver
= ui_component('ads/traffic_driver_html')

// Include the double height MPU
= ui_component('ads/mpu', properties: { size: { mapping: 'mpu-double' } })

// Include two leaderboards with different content
= ui_component("ads/leaderboard", properties: { targeting: { position: "top"} })
= ui_component("ads/leaderboard", properties: { targeting: { position: "bottom"} })

Controlling ads

The ad manager will apply an event listeners to the page which will listen for events. Currently configured events are:

All ad units on the page can be refreshed by triggering an :ads/refresh event. The refresh action can also be filtered by type (based on the ID of the ad unit placeholder).
$(LISTENER).trigger(":ads/refresh", { type: "leaderboard" });
The config parameters for the ads can be changed too with :ads/refresh event. Just pass the new config and it will be refreshed.
$(LISTENER).trigger(":ads/refresh", { ads: { param: "newValue" } });

Individual ads can be refreshed by accessing the ad unit instance:


Also for individual ads, you can pass new config:

$(".adunit").data("adUnit").refresh({ ads: { param: "newValue" } });