Ads

MediaPress Ads provides an interface and functionality to support ad management in WordPress.

Core Concepts

Currently, this plugin is geared towards Google Publisher Tag for serving display ads within content. GPT configuration is handled for you, following best practices for ad viewability and performance.

Ads will be lazy-loaded and automatically displayed when in view, and pre-fetched ahead of time.

Ad Slots

Ad slots are uniquely named HTML containers which will eventually render ads.

A single ad slot can be configured to render a range of ad sizes, where the ad server will select the most appropriate size automatically. In addition to this, an ad slot can reference a “size mapping” - which can be used to render a range of ad sizes across different breakpoints.

The Ad Slot block provided by this plugin will let you visualize exactly which ads can be rendered into a slot, based on the config provided.

By default, ad slots will inherit a base configuration which will determine it’s settings, targeting and ad path, but this can also be over-ridden at the block level.

Ad Lifecycle

• Slot rendered - An empty HTML container is rendered onto the page, either server-side or dynamically
• Slot defined - The slot should be defined as early as possible so that the ad server is aware it exists
• Ad fetched - Ad data is pre-fetched ahead of being displayed
• Ad displayed - An ad is displayed in an ad slot. If this occurs and the ad is not visible, this may have a negative impact on viewability, so this is usually delayed until the ad is approaching the viewport
• Ad impression tracked - An impression is tracked when 50%+ of ad pixels have been visible in the viewport for >1 second. If an ad is displayed but never meets this criteria, viewability will decrease

Additional Configuration

Out of the box, we include a sample config for testing purposes. You should replace this with your own JSON config file, and point to this file using the appropriate filter.

This config file is where you define your ad slots and their appropriate (responsive) sizes. It is used to produce block variations of the “Ad Slot” block based on these definitions.

The exact format of the config file is documented within the config-schema.json included within the plugin, and example-config.json shows how this can be implemented.

Filters/Actions

PHP

Filters

mediapress_ads_config_path

Allows the adjustment of the ads config JSON file location

Parameters

Name	Type	Description
path	string	The path to the config.json file

Usage

add_filter( 'mediapress_ads_config_path', 'my_plugin_ads_config_path' );
function my_plugin_ads_config_path( string $path ): string {
  $path = __DIR__ . '/config/my-ads-config.json';
  return $path;
}

mediapress_ads_slot_rules

This filter lets you define ‘rules’ using xpath selectors in order to inject ad slot HTML into your markup.

Parameters

Name	Type	Description
rules	array<string,Rule>	Array of rules with unique keys

Rule Shape

Each rule is an associative array with the following keys:

Key	Type	Required	Description
slot_id	string	Yes	The unique ID of the ad slot to inject. This is suffixed with a number to ensure each dynamically inserted slot also has a unique ID e.g: article_inread--1
selector	string	Yes	XPath selector to target HTML elements for ad injection.
position	string	No	Where to insert the ad relative to the selector (before, after).
height	string	No	Optional CSS height for the ad slot container (e.g., 40vh, 300px). The ad will be sticky within this container, keeping it within the viewport for longer.
before	string	No	Optional HTML to insert before the ad slot.
after	string	No	Optional HTML to insert after the ad slot.

Usage

add_filter( 'mediapress_ads_slot_rules', 'my_plugin_ads_slot_rules' );
function my_plugin_ads_slot_rules( array $rules ): array {
  if ( 'post' !== get_post_type() ) {
    return $rules;
  }

  $rules['post_inread'] = [
    'slot_id'  => 'article_inread',
    // after every 6th p, heading or ul element
    'selector' => '/*/*[self::p or self::h1 or self::h2 or self::h3 or self::h4 or self::h5 or self::h6 or self::ul][(position() mod 6) = 0]',
    'position' => 'after',
    'height'   => '40vh',
  ];

  return $rules;
}