# Advertisement tags

# Introduction

This document describes all matters related to setting up an advertisement tag (adtag) for MyChannels.

An adtag is used for showing prerolls preceding our videos. In its essence, an adtag is just an URI (albeit, a very big one). This URI is usually loaded in a video player. Upon watching a video, the (end)user loads this player (either web or app) and this player makes a call to a one of De Pergroep's DFP servers. The DFP server returns an XML document that the player can interpret so it can serve the advertisement.

# Structure

This section is optional, it describes the general structure of the adtag, but this knowledge is not required for implementing an adtag. That being said, it can help making debugging easier.

Let me paste an example adtag here, and then go through its parts.

https://pubads.g.doubleclick.net/gampad/ads?iu=/7455/ad/ad.video/de_stentor/app-ios&sz=620x349&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&description_url=[description_url]&url=[referrer_url]&correlator=[timestamp]&npa=0&ad_rule=1&cmsid=2479277&vid=25000&cust_params=channel_id%3D285%26channel_title%3Dde_stentor%26child_friendly%3Dtrue%26content%3Dsyndication%26nr%3D1%26organisation_id%3D27%26output%3Dvmap%26pos%3Dpre%26production_id%3D25000%26publisher%3DBrandDeli%26show_id%3D976%26show_title%3Dsnel_nieuws%26station%3Dad%26theme%3DNews%26video_label%3Dunknown

# 1. The base url

Every adtag starts with a base url, which is this:

https://pubads.g.doubleclick.net/gampad/ads

# 2. The 'iu', or 'adunit'

iu=/7455/ad/ad.video/de_stentor/app-ios

The first parameter is 'iu' and is a string which is composition of

1. The network ID. We currently have two networks, one for Netherlands (ID: 7455) and one for Belgium (ID: 7191 (!this is the test id, the final id is still to be determined!))
2. Brand name. Just the string representing the brand name.
3. Brand name, plus ".video". Like 2) but then again, and with the string ".video" appended on it
4. Web- or app quantifier. What the value of this string is, depends on the network. You can look it up in the code or ask one of our DFP administrators. You can find their contact info at the end of this document.

These four strings are concatenated by a '/' and then form the adunit

# 3. The 'required_parameters'

sz=620x349&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&description_url=[description_url]&url=[referrer_url]&correlator=[timestamp]&npa=0&ad_rule=1&cmsid=2479277&vid=25000

Then follow a couple of query parameters that are required for the adtag to work properly. The iu is actually also a required parameter, but its structure justified an extra paragraph in this document. Now follows a list of these parameters and their semantics.

• sz Dimensions of the advertisement, i.e. 640x480
• impl Semantics unknown
• gdfp_req= User has, or has not approved GDPR settings
• env Semantics unknown
• output Ad prototcol, i.e. 'vast' or 'vmap'
• unviewed_position_start Semantics unknown, but one can guess
• description_url URL where information about the resource can be found
• url URL of where this video/ad is being displayed
• correlator Unique value to distinguish it from other calls. Usually, a timestamp is use
• npa Stands for non-personal ads
• ad_rule Semantics unknown
• cmsid ID of the CMS this production was created is. Corresponds to the ID of our VMS
• vid ID of the production being played with this ad

The ones with 'sematics unknown' have a static value. You can find them in the source code. You will also see values between square brackets. These are macro's. They will be filled in by the IMA SDK (on the DFP server or on the client), so we do not have to bother about them. We can can just send them as is.

# 4. The 'custom_parameters'

cust_params=channel_id%3D285%26channel_title%3Dde_stentor%26child_friendly%3Dtrue%26content%3Dsyndication%26nr%3D1%26organisation_id%3D27%26output%3Dvmap%26pos%3Dpre%26production_id%3D25000%26publisher%3DBrandDeli%26show_id%3D976%26show_title%3Dsnel_nieuws%26station%3Dad%26theme%3DNews%26video_label%3Dunknown

At last, there follows a special query parameter, the custom_parameters, that have the key value cust_params. It is a list of information about the production, its show, channel, etc. It has a value is this format:

cust_params=key1%3D2val1%26key2%3Dval2%26...keyn%26valn

So, the value of cust_params is one big string consisting of list of key/value pairs, which are url encoded. It is not mandatory to include these in the adtag, but it is used by the DFP administrators to generate rapports. And they will probably complain when it is absent.

# Our implementation

At the time of this writing, two important things should be taken into consideration. One is the fact that we have to deal with to two DFP servers, one in Belgium and one in the Netherlands. The Belgian DFP server is responsible for serving the ads for HLN, De Morgen and other Belgian brands. The Dutch DFP server is responsible for all the Dutch brands. The other important issue is the fact that we have code for generating the adtag for 1) app and 2) web.

# App and web, Belgium and Netherlands

In our codebase we have two main entries for generating adtag. One is for apps and this code resides in the VaasApi codebase. The elixir module you want to look for is called VaasApi.AdTagHelpers. Then, for the web side of things, there is a ad-tag-factory.js. It loads up other JS files that create specific adtag for different brands. That is, there are three JS files:

• default-ad-tag.js, which currently generates the adtag for all brands, except for HLN and the mychannels website. This is the largest file.
• hln-ad-tag.js, which currently generates a static adtag for HLN web. We are now in the process of making this dynamic; you will see a start for a dynamic function in this PR
• mc-ad-tag.js, this is a legacy JS file for having ads on mychannels.com, which is now defunct.

The VaasApi.AdTagHelpers module already has support for multiple brands and multiple networks. Depending on the brand that is associated with the API user, the correct values for the adtag will be loaded.

# Proposed improvements

The fact that there are two main places in the code where adtags are being generated, is undesirable. Especially when one considers the fact that both these adtag generators adhere to the same adtag format. It would be desirable to have only one (api) module that generates and returns the adtag which both web and app can use. The problem with this approach is that on the web part, one would have to make an extra (synchronous) call to this service. That is, the player is being loaded with a production, and then an extra call would have to be made to this new adtag service to obtain the adtag. The player has to wait with playing the video until this adtag is properly processed. One has to consider if these extra complexities are worth the effort.

# Testing

This is a tricky subject. Even though an adtag could technically be correct, this is not a guarentee that an ad will show up. There are multiple reasons why a valid adtag will not produce an ad

1. There are no ads 'booked' on a certain adtag. This means the following: The DFP administrators have to 'see' the call to a certain adtags before they consider it valid and book an actual advertisement on this tag. This is mainly the case when there is a new channel, so they will recieve an adunit they have never seen before
2. The DFP server keeps track of how many ads it already served, and to whom. For example, there could be a DFP server rule that says that an end user only receive one advertisement per thirty seconds (which seems reasonable). The effect is that refreshing one's browser will not lead to displaying a new advertisement.

That being said, the best way to test if an adtag is valid, is by checking it on the VAST inspector (Turn off your adblocker!).

Besides that, it is advised to speak to one of the DFP administrators and ask them if they can create an adtag that will always display an advertisement.

# Help and contact

When things go wrong, contact the DFP administrators:

• Netherlands: Michiel van Hooij, m.van.hooij@persgroep.nl
• Belgium: Kurt Waegeman, Kurt.Waegeman@persgroep.be