---
title: Ads
description: MediaPress Ads provides an interface and functionality to support ad management in WordPress.
url: https://developers.wpengine.com/docs/newsroom/mediapress/ads/
image: https://developers.wpengine.com/og/docs/newsroom/mediapress/ads.png
---

# 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](https://developers.wpengine.com/docs/newsroom/mediapress/ads/#mediapress_ads_config_path).

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 in the plugin at `/wp-content/plugins/mediapress-core/pro/ads/config-schema.json` and may be accessed from the filesystem or web browser. `example-config.json` in the same directory 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**

```php
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:

<!-- spell-checker:ignore inread -->

| 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**

```php
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;
}
```

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```