This document details the key functionalities of the ValidClick Ad Blocks and offers instructions on how to implement it on a site.

HOW IT WORKS:

1. Search Ads: Each ad block will show display ads based on a common keyword, referring URL, and serving URL. In the rare case there are no ads to display, the block will collapse to have zero height.

2. Organic Search: Given a search term, organic search results will be returned from the Yahoo Bing search index. The height of the block will adjust to closely fit the size of the displayed results.

HOW TO IMPLEMENT:

The implementation consists of two parts: the Master Script and the Ad Block tags. The Master Script does the work of interacting with ValidClick and the Ad Block Tag is used to specify where ads should be served.

1. The Master Script: This is a single line of JavaScript that needs to be placed after every other ValidClick tag on the page. The best place to put this is just above the “</body>” tag. Here’s an example:

<script src="//feed.validclick.com/js/validclick-master-v1.1.js"> </script>

Note: the Master Script must be below the Ad Block Tags on the page. 

2. The Ad Block Tag: This is the code that instructs the master script where to place the ad block on the page. It also allows for customization the block:

<vc:block 
data-term="BBQ Grills" 
data-affId="1" id="topAds" 
data-groupOrder="1" 
data-listings="4" 
data-lat="yes" 
data-IA="no" 
data-favicon="no" 
data-sitelinkcount="4" 
data-related="3" 
data-merchantRatings="yes" 
data-stylesheet="http://assets.validclick.com/assets/styles/Master.css" 
data-width="80%" 
data-height="1000">
</vc:block>

You may also customize several aspects of each Ad Block. Below is a list of the options and a description of how each is used.

EXAMPLE OF ADS:

 

ads related to “BBQ Grills“

 

VARIABLES, OPTIONS AND REAL TIME TRACKING:

  • Required Variables:
    • data-affId – Sets the affiliate id used to authenticate the ad feed request. (required)
    • data-listings – The number of results requested for that ad block or results set.
    • data-term – The keyword or phrase used to request ads or organic results. In the case of multiple ad blocks it will be assumed that each block has the same term. Only the last ad block tag on the page will actually be used to determine the term for the ad request. Organic search results will always use the term specified in the Tag.
    • data-newWindow: By default ads are set to open in same window. If you want to open them in a new window, set this value to “new”.
  • Optional Configuration Variables:
    • data-feed – Defaults to display ads related to the keyword. May be set to ‘algo’ to request organic search results. We suggest using this as a separate block.
    • data-groupOrder – As a single page may have many blocks displaying ads based on the same term, this indicates the order in which ads returned for that term will be applied to the adblocks on the page. Blocks with the same groupOrder will each receive ads, but the priority is undefined.
    • data-stylesheet: This variable allows you to specify a stylesheet url.
    • data-sitehostLocation: Determines where the advertiser’s display url shows up. Default is on top of the description and under the title (“top”). The other option is “bottom”, which shows up under the description.
    • data-related: Additional keywords may be displayed beneath listings to further guide a user’s search. This option gives the maximum number of keywords that will be displayed, with a default of zero. The number actually displayed may be fewer based on availability.(RECOMMENDED)
    • data-width – Sets the height in pixels of the ad block.
    • data-IA – Turns images on or off. Use “yes” to turn images on. (RECOMMENDED FOR BETTER YIELD)
    • data-sitelinkcount – shows site links, which increase yield. Count specifies how many ads you want to show them on. Default is 3.
    • data-favicon – Set this to “yes” to request favicons be displayed in the ad. If this is enabled along with Images, the favicon will be shown to the right of ad and Images will be shown to left.
    • data-localAds – Requests specifically local ads and extensions from the feed. By default this is on and generally adds to yield for local searches.
    • data-blacklist: Prevents ads from being shown which contain certain keywords. These keywords are case insensitive and specified as a comma delimited list. Ex: data-backlist=“doctor, pepper”
  • Optional Tracking Variables:
    • data-clickBeacon – Here you can pass us a url to ping to signal that a link has been clicked. Future enhancements will include adding parameters to the url to indicate more about the clicked ad, such as placement and keyword used.
    • data-impressionBeacon – Here you can pass us a url to signal to you that an ad impression has occurred. Only one impression beacon will be called per page view. If multiple adblocks on the page specify an impression beacon url, only one of them will be used.
    • data-beaconKeyword: Specifies a parameter to append to an impression and click beacon to send the keyword used to generate the listings.
    • data-beaconAffId: Specifies a parameter to append to an impression and click beacon to send the affiliate id used to generate the listings.
    • data-beaconPlacement: Specifies a parameter to append to a click beacon to send the position of the ad clicked by the user. The first ad is numbered 1, the second 2, and so on.
    • data-beaconSitehostlist: Returns a comma separated list of the advertiser display urls.
    • data-beaconSitehost: Specifies a parameter to send back the display url of the ad that was clicked. If a user clicked on an ad from say USAToday, then www.usatoday.com would get passed back to the beacon URL.
    • data-Wildcard1 and data-Wildcard2: This is a wildcard variable that allows you to pass unique variables to the serve url. So for example if you wanted to pass a source to the ads as a wildcard variable you could do it by appending data-Wildcard1=Bing and we would take whatever is passed and send back to you.
  • Custom Javascript On Page Functions (Misuse can kill clicks, so test thoroughly):
    • data-impressionCallback=”callbackName” – Passes a single object argument to the given callback. The single argument for the call back will have these properties. The internal properties are subject to change. If you would like to “backfill” the ads, we suggesting using js to monitor the addisp count and using logic to not show if the number of ads returned does not meet requirements.
      • action: “listingImpression” // Internal routing label
      • addisp: 3 // Number of ads displayed. May be fewer than requested due to blacklisting or feed coverage
      • adreq: “5” // Number of ads requested from the feed.
      • affid: “1” // Publisher’s affid
      • urlid: 3 // Internal iframe id
      • kwd : “pet%20food” // Urlencoded Keyword specified for the listing
      • srv: “www.exampleurl.com” // URL serving the impression
      • style: “” // Url of the style sheet in use.
    • data-clickCallback=”callbackName” – Passes a single object argument to the given callback. The single argument for the call back will have at these properties. The internal properties are subject to change.
      • action: “followClick” // Internal routing label
      • affid: “1” // Publisher’s affid
      • id: 3 // Internal iframe id
      • keyword: “pet%20food” // Urlencoded Keyword specified for the listing
      • serveUrl: “www.exampleurl.com” // URL serving the click
      • sitehost: ”www.exampleurl.com” // Sitehost displayed in the ad
      • style: “” // Url of the style sheet in use.
      • position: 2 // 1-indexed position of the ad clicked.

Customizing the Look and Feel

The ValidClick JS script supports custom style sheets on a per ad block basis. The below represents the default CSS for all ad blocks.

There are now options for customizing which classes are applied to four kinds of elements in the ad unit. Strings given to these options will be applied to the className of the respective element. This can be used to apply styles from an existing stylesheet (specified by the data-stylesheet option), which is especially useful if you already have many different stylesheets in use across various sites. Just like the className DOM property, multiple class names may be specified, as long as they are space separated.

  • Custom CSS Vars for the Ad Block
    • data-wrapperClass=”” This styles the container for a given ad listing
    • data-titleClass=”” This styles the title text in the ad listing
    • data-descriptionClass=”” This styles the description text of the listing
    • data-sitehostClass=”” This styles the sitehost text in the listing.
body {
background-color: #FFFFFF  ;
outline-color: #FFFFFF  ;
outline-style: solid;
margin: 0px;
outline-width: 0px;
padding: .25em;
}

.textbox > div {
margin-top: auto;
}

.adTitle {
color: #0000FF  ;
font-family: Arial, Helvetica, Sans-serif;
font-size: 1em;
text-decoration: none;
font-style: normal;
}

.title-wrap {
text-align: left;
}

.adDescription {
color: #444444  ;
font-family: Arial, Helvetica, Sans-serif;
font-size: 1em;
text-decoration: none;
font-style: normal;
}

.description-wrap {
text-align: Left;
}

.adSitehost {
color: #256126  ;
font-family: Arial, Helvetica, Sans-serif;
font-size: 1em;
text-decoration: none;
font-style: normal;
}

.sitehost-wrap {
text-align: Left;
}

.adbox {
margin-bottom: 1em;
display: flex;
}

.adbox:hover {
background-color: #f6f6f6;
}

.adbox:hover .adTitle {
color: #ff0303;
}

img.ia-pic {
vertical-align: middle;
margin-right: .4em;
width: 70px;
height: 70px;
}

img.favicon {
vertical-align: middle;
width: 1em;
height: 1em;
margin-right: .3em;
}

.adsByDisclaimer, .algolabel {
font-size: .7em;
font-weight: bold;
color: #999;
}