Guides

Integrated Ads

Suggest Edits

📘

Activation

Please contact your Viafoura client success representative to activate this feature.

Viafoura's Conversations, Live Blogs, Engagement Starter, and Trending Conversations products allow for ad tags, or any other custom code, to be placed within them. A Standalone Ad widget is also available if you wish to show an ad outside any of the Viafoura products.

Depending on the ad product, when a new ad slot is available, the following events will fire allow you to pass an ad, or any other content you may want to promote, into the position. Use the following methods to subscribe to the events based on the ad products.

/**
 * Dynamically generates an ad and inserts it into the template when the Viafoura conversations widget requests an ad.
 * @param  {String} slotName - id of the element to render the ad in
 */
function generateCommentAd(slotName) {
  // CONVERSATIONS AD INTEGRATION CODE HERE
}

/**
 * Dynamically generates an ad and inserts it into the template when the Viafoura liveblog widget requests an ad.
 * @param  {String} slotName - id of the element to render the ad in
 */
function generateLiveblogAd(slotName) {
  // LIVEBLOG AD INTEGRATION CODE HERE
  // Liveblog ads can be configured similarly to conversations
}

/**
 * Dynamically generates an ad and inserts it into the template when the Viafoura trending conversations widget requests an ad.
 * @param  {String} slotName - id of the element to render the ad in
 */
function generateContentRecirculationAd(slotName) {
  // TRENDING CONVERSATIONS AD INTEGRATION CODE HERE
  // Configure similarly to Comments, except
  // the ad size is limited to 300x250
}
/**
 * Dynamically generates an ad and inserts it into the template when the Viafoura trending conversations widget requests an ad.
 * @param  {String} slotName - id of the element to render the ad in
 */
function requestStandaloneAd(slotName) {
  // STANDALONE AD INTEGRATION CODE HERE
  // Configure similarly to Comments, except
  // the ad size is limited to 300x250
}
/**
 * Dynamically generates an ad and inserts it into the template when the Viafoura trending conversations widget requests an ad.
 * @param  {String} slotName - id of the element to render the ad in
 */
function requestConversationStarter(slotName) {
  // CONVERSATION STARTER AD INTEGRATION CODE HERE
  // Configure similarly to Comments, except
  // the ad size is limited to 300x250
}

// Subscribe to the viafoura event when the viafoura object is ready
window.vfQ = window.vfQ || [];
window.vfQ.push(function() {
   // Provide the desired ad generation functions as callbacks to the appropriate events:
   window.vf.$subscribe('vf-ads', 'requestCommentAd', generateCommentAd);
   window.vf.$subscribe('vf-ads', 'requestLiveblogAd', generateLiveblogAd);
   window.vf.$subscribe('vf-ads', 'requestContentRecirculationAd', generateContentRecirculationAd);
   window.vf.$subscribe('vf-ads', 'requestStandaloneAd', requestStandaloneAd);
   window.vf.$subscribe('vf-ads', 'requestConversationStarter', requestConversationStarter);
});

To integrate the ads, you will need three scripts:

  • one to initialize the ads
  • a subscription to the viafoura event
  • a handler to generate the ad

Below is Google DFP's sample code to initialize the ads:

<script async='async' src='https://www.googletagservices.com/tag/js/gpt.js'></script>
<script>
   var gptadslots = [];
   var googletag = googletag || { cmd: [] };
   googletag.cmd.push(function() {
       googletag.pubads().enableSingleRequest();
       googletag.pubads().disableInitialLoad();
       googletag.enableServices();
   });
</script>

The following is a sample Viafoura event subscription and handler:

<script>
/**
 * Dynamically generates an ad and inserts it into the template when the Viafoura conversations widget requests an ad.
 * Adapted from: https://support.google.com/dfp_premium/answer/4578089?hl=en#infiniteContents
 * @param  {String} slotName - id of the element to render the ad in
 */
function generateCommentAd(slotName) {
    // Generate next slot name
    var adUnitString = '/1234/travel/asia'; // This string should be replaced by your
                                            // network code and ad unit you are targeting
    var size = [300, 250]; // the comment ad positions can accommodate any ad size,
                          // but we recommend not using very tall ads and using ad size
                          // mapping for different device sizes. See ad size mapping below
    // Define the slot itself, call display() to
    // register the div and refresh() to fetch the ad.
    googletag.cmd.push(function() {
        // Destroy any lingering ad slots if they exist in the widget
        const slots = googletag.pubads().getSlots()
            .filter((slot) => slot.getSlotElementId() === slotName);
        googletag.destroySlots(slots);
        // Define ad sizes based on viewport size
        // NOTE ads are not responsive but new ads will be rendered to the appropriate size
        // Adapted from https://support.google.com/dfp_premium/answer/4578089?hl=en#responsiveDesign
        var mapping = googletag.sizeMapping()
            .addSize([100, 100], [88, 31]) // Small ad
            .addSize([320, 400], [[320, 50], [300, 50]]) // Accepts both common mobile banner formats
            .addSize([320, 700], [300, 250]) // Same width as mapping above, more available height
            .addSize([750, 200], [300, 250]) // Landscape tablet
            .build();
        // Create a new ad slot, pointing to the slotName given to this function
        var slot = googletag.defineSlot(adUnitString, size, slotName)
            .defineSizeMapping(mapping)
            .addService(googletag.pubads());
            // Add any targeting or any other modifications to the ad here
        // Display the new ad
        googletag.display(slotName);
        googletag.pubads().refresh([slot]);
    });
};
// Subscribe to the viafoura event when the viafoura object is ready
window.vfQ = window.vfQ || [];
window.vfQ.push(function() {
    window.vf.$subscribe('vf-ads', 'requestCommentAd', generateCommentAd);
});
</script>

If You Are using Custom Ad Integration

If you are using the Google Ad manager, the Conversations widget will automatically display the ads when the ad is successfully loaded. However; if you are using a different ad provider, then inside requestCommentAd (or requestLiveblogAd, requestContentRecirculationAd, requestStandaloneAd) callback, you must manually force the ad to render in order for it to be visible.

Below is an example of that:

/**
 * Dynamically generates an ad and inserts it into the template when the Viafoura conversations widget requests an ad.
 * @param  {String} slotName - id of the element to render the ad in
 */
function generateCommentAd(slotName) {
  // REST OF THE AD INTEGRATION CODE HERE
  
  // Find the ad slot and manually display it
  document.findElementById(slotName).style = 'display: block';
}

// Subscribe to the viafoura event when the viafoura object is ready
window.vfQ.push(function() {
   window.vf.$subscribe('vf-ads', 'requestCommentAd', generateCommentAd);
});

Disable Ads on a Page

If you need to disable ads on a particular page, it is possible to stop any ads from loading by including the following meta tag:

<meta property="vf:ads-disabled">

This tag must be present at page load time, and resetting the Viafoura context or other dynamic changes will not allow overloading this setting.

To prevent ad positions from being displayed, also target the class ".vf3-conversations-list__promo" and set to "display: none".

.vf3-conversations-list__promo {
    display: none;
}

Widget: Standalone Ad

The "vf-standalone-ad" is a widget that only shows the ad without other engagement tools. This widget uses the same settings and layout as the "vf-content-recirculation" widget.

It's very simple to use the "vf-standalone-ad" widget, just define the following code:

<div class="viafoura">
  <vf-standalone-ad></vf-standalone-ad>
</div>

It's important to mention that this widget has no parameters in the HTML element.

Troubleshooting

Cropped Ads

If you notice your ads not being displayed at the full, expected width, make sure you do not have any CSS styles affecting iframes globally. This might occur due to a CSS reset or normalization done at the base level of your styles.

/* BAD */
iframe {
    max-width: 100%;
}

/* BETTER */
iframe {
    max-width: none;
}

.my-own-iframe-class {
    max-width: 100%;
}

Frequency of Ads

To adjust the frequency of ads in Viafoura components, visit the "Advertising" tab within the Viafoura Admin. There you can adjust various settings, for example: when the first ad appears in Conversations (First Promo Position), the frequency of ads in the Conversations (Promo Interval), and the frequency of ads in reply threads (Promo Interval Replies).

Updated 9 months ago

What’s Next