Marfeel Docs

# AdDealer

AdDealer is Marfeel's algorithm responsible for identifying the best places to insert advertising on every page on a website. It also manages the ad frequency in terms of how close the ads are displayed to each other and controls the aggressiveness of the number of ad impressions made.

It works by essentially breaking the article down into visual blocks and spots the most optimal locations to insert advertisements and how to space them apart. A typical block would be a paragraph of text or an image. The process is made up of taking the article's HTML code, parsing it to create blocks, merging adjacent blocks (for example, an inner title and a paragraph of text) into visual blocks, and then deciding the best places to insert ads that will maximize the CTR of the ads while promoting user engagement.

To provide an organic flow of page elements, AdDealer uses a distribution function to balance the text, media, to properly frame an article and publication.

AdDealer is able to do this for differing HTML code due to its built-in intelligence and its defined parameters. For example, it ensures fundamental components of an article like the date and author are never separated from the title, that an image and its caption are always presented together, or that a section title is never split from its first paragraph.

It's able to perform this complex function for so many diverse client web pages due to its sophisticated use of heuristics, which in the simplest of terms, is the implementation of an efficient set of rules to make decisions. For a data set, heuristics must fulfill the needs of that data set. AdDealer's heuristics must fulfill the needs of a very large data set that's made up of our 400+ clients. That's why any change we perform in AdDealer is always a significant improvement that adds value.

AdDealer works with different modifiers and mediators in place to ensure impressions are made in the optimal places in an article.

# Creation of Visual Blocks

The first function AdDealer performs is to create visual blocks once we have obtained the Tenant's HTML code.

To do this we use a TreeWalker through the DOM that parses the HTML and validates or invalidates the content with a filter to detect the tags, links, text, and so on.

Once we have this TreeWalker we move through the nodes of the tree and generate visual blocks.

# Top Media

AdDealer takes the featured image or top media for the article from the best image available in the body and removes it from there and any caption that might come with it.

Taking the best image from the body not only adds an impactful and rich image that enhances a Tenant's content, but it also offers a perfect scenario for Marfeel to increase and leverage high-quality ad inventory.

It should be noted, however, that there is also a flag in definition.json file that can be configured to prevent the caption from being removed from the top media.

"topMediaCaptionEnabled": "true"

A media remover parameter also exists that when enabled, inhibits the image from being eliminated from the body of the article regardless of its location. See Top Media section to know more about it.

# Visual Block Mergers

An example of a visual block could be an image with its caption. Although they might be adjacent blocks, they are merged to create one visual block so that ads are not inserted in-between.

This process of merging the visual blocks that have been parsed is governed by the 7 non-configurable mergers that AdDealer checks with.

  1. Calculating images as a percentage of words (InlineImagesMerger)

AdDealer calculates the images in an article as a percentage of words when merging visual blocks and inserting ads. A larger image will be calculated as an appropriate percentage of words, whereas an icon would be merged and treated according to its small size. For example, if an image is smaller than 130 pixels, it's not counted as an image at all.

  1. Images merged with captions (MediaWithTextMerger)

AdDealer has a merger that ensures images are merged with any captions they might come with.

If AdDealer doesn't detect any caption text, it will try to insert ads by text blocks and not images. Research shows that ads right before or after images perform weaker than those inserted closer to text blocks.

For image-heavy articles, AdDealer will try to place ads in the best positions to optimize CTR.

  1. Forbidden positions (ForbiddenNodesMerger)

AdDealer ensures that no ads are placed between blockquotes, links, or lists.

  1. Top of article elements (BlocksBeforeTitleMerger)

AdDealer removes any extraneous elements above the article.

  1. Links and single elements (OneLetterBlocksMerger)

One letter blocks refer to elements such as links embedded in one word that might be treated as a visual block. In this case, AdDealer merges this block with the next one.

  1. Top of content elements (FirstShortVisualBlocksMerger)

AdDealer treats any elements at the top of the article such as the category, author name, dates, sections, or other small text individually, meaning it does not remove or attach it to another block.

  1. Small blocks below the article (TagsMerger)

Any small blocks identified below the article title such as tags are treated like an individual block and therefore are not merged with another block or removed.

Once the AdDealer has visually processed an article and has created a visual block representation it's time to insert elements in between:

# AdDealer Parameters

Once an article has been broken into visual blocks, the AdDealer can use 3 strategies to determine the best places where to insert ads to maximize the CTR:

# Mandatory Mediators

Mandatory mediators must always be fulfilled and are not configurable or subject to customization.

The following are the mandatory mediators that AdDealer adheres to when inserting ads:

  • NoAdsAfterHeaders : AdDealer never places any ads after the inner title of an article.

  • EnoughWordsForExtraAd: AdDealer maintains a parameter that inserts the last ad 75 words before the article ends. If however, an article only has 60 words remaining and there is still an ad space to insert, AdDealer will ignore this parameter and insert the ad.

  • EnoughWordsBetweenLastAdAndNativeAds: When a customer has native ads enabled, AdDealer maintains a default visual block needed between the last ad position and the native advertisement.

  • EnoughMinWordsForLastAd: Determines the number of words AdDealer calculates to insert the last ad at the bottom of the content. Customers can customize this mediator to correspond to the aggressiveness of their advertising strategy.

  • EnoughWordsBeforeLastAdPosition: AdDealer supports the specification of a mandatory placement for the last ad in an article via the definition. Therefore, Marfeel can specify in which part of an article to place the last ad. This forces no other ad to be displayed below, with the only exception being the activation of the adDealerExtraImpression flag.

  • NoAdsInComposedLayouts : AdDealer never places any ads in composed layouts.

  • NoAdsInSliders : AdDealer never places any ads in sliders.

  • NoAdsInGalleries : AdDealer never places any ads in galleries.

  • NoAdsInBalconHeaders : AdDealer never places any ads after the title of a content group.

# Optional Mediators

Some mediators can be configured that AdDealer must consult with when inserting ads into articles:

  • AdAfterTitle: AdDealer inserts an ad right after the title of an article such as a 300x100 after the fold ad.

  • CustomMinWordsForFirstAd: Determines the number of words AdDealer calculates for ad placement between the top of the article and the first ad. By default, AdDealer will place the first ad after 16 words if you have top media, and after 50 words if you don't have top media. The goal is to make the first impression as close to the first scroll as possible to increase CTR.

  • CustomMinWordsBetweenAds: AdDealer inserts ads according to word counting based on visual blocks. It's designed to increase the space and content between ads as the user becomes more engaged in the content. AdDealer follows a default formula but can also increase its aggressiveness and can be configured according to customer specifications.

  • InitialFirstAdPosition: When customAdsStartPosition is enabled in definition.json file, it defines if the first ad position is inserted according to a custom configuration.

  • FulfillBlockCountRatio: definition pending.

# Image mediators

There are also image removal mediators that are not turned on by default but can be manually configured.

They address the location and redistribution of images in cases where they are used as the featured image (top media):

  • KeepTopMediaImages: The image taken as top media from the article will always remain in the body.

  • ImageFarFromTop: Images taken from a low position in the body to be used as top media are not removed from the article, but maintained because of their advanced position.

  • KeepImagesAfterHeaders: If an image taken as top media is below an inner title, it is not removed from the body because it might be contextually important.

AdDealer also establishes and calculates the carousel which usually appears at the half-point of the article that displays next articles and is implemented to increase user engagement.

It's also responsible for the Splitter which essentially splits an article in two if a publisher has a lot of content to be displayed and provides coherence and fluidity in their page flow.

Instead of loading every article that would weaken the site's rendering, we load the first part of the article and when the user swipes to that article, we load the second half in the background, decreasing the size of the requests by half and increasing the loading time. AdDealer's particular function with the Splitter is determining where to split each article.

← Ad Implementations / Support →