Display Ads

Richie applications support five main approaches to serving advertising:

1. The main screen and section fronts can incorporate display advertising served with ad SDKs. The currently supported ad SDKs are Google Mobile Ads, Equativ, Xandr and Richie Ads.

2. Advertising can be shown within articles by including traditional display ad tags on the HTML article templates.

3. Article views also support inserting native advertisements from ad SDKs.

4. Interactive full page ads can be shown between swipes in the article browser and between pages in Editions. The supported ad technology for full page ads is Richie Ads.

5. Native advertising can be served as articles, and highlighted by using a custom template and an appropriate status_label.

The topic of this document is options 1 and 3, which rely on very similar mechanisms. Display advertising can be shown on the main screen and section fronts of Richie apps by including specially formatted Article objects in the news feeds. A news articles can request ads to be inserted into the article view by calling a Javascript function that accepts an identical payload as used in the news feed article objects that represent advertisements.

Note: Richie application binaries do not include any third party advertising SDKs by default. While this document details the feed changes necessary to incorporate ads, the app itself must be updated to include the appropriate ad SDK. Please contact Richie support to do this for your app.

Section Front Advertisements

The Ad Pseudo-Article

The main screen and section fronts of a Richie app display lists of articles in feed order. Ads are placed in specific positions between articles, and the way this is expressed in the feeds is that the ad positions are included as a sort of pseudo-article objects with the following properties:

Ad placements always span the full width of the screen in Richie apps minus any margins specified by the design (although the ad creative usually does not take up all the space). When placing ads, consider two-column tablet layouts: trying to place an ad between articles on the left column and the right column will result in an article on the left column, the full-width ad, and another article on the left column.

To avoid this, your article and ad placement logic should keep the width of different items (2 columns for ad, featured and big; 1 column for small and small_group_item) in mind.

Ad Data Object

The primary content of the ad data object is an array of alternatives: sets of ad placement details that are evaluated in order. The first alternative that can show an ad will be used (and the rest will not be evaluated at all).

{
  "alternatives": [
    {
      "max_width": 399
      // …and provider-specific ad slot details
    },
    {
      "min_width": 400,
      "max_width": 799
      // …and provider-specific ad slot details
    },
    {
      "min_width": 800
      // …and provider-specific ad slot details
    }
  ]
}

This structure has two uses: first, it allows you to try multiple ad slots for ads in a waterfall setup. Second, it makes it possible to build responsive ad display logic: the min_width and max_width properties can be used to target different ads to phones, tablets and even different orientations.

Ad Alternative Properties

The width values are evaluated against the design, so they take into account any margins specified for the advertisements. The values are in visual points, not pixels, so they are roughly equal across devices. Devices typically use multiple pixels per a single point to achieve sharper rendering.

These two properties are the only general properties available for ad alternatives regardless of the ad provider used. The following sections describe the specific support available for each ad provider.

Google Mobile Ads

The Google Mobile Ads ad data object is specified as follows:

{
  "alternatives": [
    {
      "ad_unit_id": "/2561223/fleet_street_journal/box",
      "manual_impression_counting": true,
      "max_width": 979,
      "custom_targeting": {
        "key1": "value1",
        "key2": "200"
      },
      "category_exclusions": ["category1", "category2"],
      "keywords": ["keyword1", "keyword2"],
      "valid_ad_sizes": [
        {
          "height": 250,
          "width": 300
        }
      ]
    },
    {
      "ad_unit_id": "/2561223/fleet_street_journal/big",
      "manual_impression_counting": true,
      "min_width": 980,
      "valid_ad_sizes": [
        {
          "height": 400,
          "width": 980
        }
      ]
    }
  ]
}

manual_impression_counting

The Google Mobile Ads SDK for Ad Manager supports manual impression counting when the ads served are trafficked directly in Ad Manager and not programmatically through exchanges. Enable this, if appropriate, with the manual_impression_counting property set to true. This decouples impression counting from the act of loading the creative, enabling better caching and user experience when moving between content tabs in the Richie app.

custom_targeting

Key-value pairs used for custom targeting. Both keys and values must be strings. Set for each Google Ads request.

category_exclusions

Array of strings used to exclude specified categories in ad results. Set for each Google Ads request.

keywords

Array of keyword strings. Set for each Google Ads request.

Equativ

With Equativ (formerly Smart AdServer), each alternative should include a page_id and a format_id:

{
  "alternatives": [
    {
      "page_id": 2343498,
      "format_id": 8023456,
      "max_width": 399
    },
    {
      "page_id": 2343433,
      "format_id": 8023430,
      "min_width": 400,
      "max_width": 799
    },
    {
      "page_id": 23434347,
      "format_id": 8023474,
      "min_width": 800
    }
  ]
}

Additionally, the site_id and base_url are configured in app-wide settings. When requesting Equativ support for your Richie applications, include the site_id and base_url in your request.

Xandr

A Xandr (formerly AppNexus) ad data object looks like this:

{
  "member_id": 38484,
  "alternatives": [
    {
      "inventory_code": "icode",
      "max_width": 399,
      "allowed_sizes": [
        {
          "width": 200,
          "height": 300
        },
        {
          "width": 300,
          "height": 300
        }
      ]
    },
    {
      "inventory_code": "icode2",
      "min_width": 400,
      "allowed_sizes": [
        {
          "width": 400,
          "height": 300
        },
        {
          "width": 800,
          "height": 700
        }
      ]
    }
  ]
}

Note the member_id property on the main object. On the alternatives, an allowed_sizes array includes the allowed creative sizes and is passed on to the Xandr SDK. The min_width/max_width mechanism works independently of the allowed_sizes arrays.

Richie Ads

Richie Ads is designed primarily for serving responsive HTML5 creative, typically in a full screen setting. Due to this, the ads have no concept of a pixel size. A display ad within a list view does, however, need a size, so a size for the ad view is specified using the mandatory native_width and native_height properties in an alternative. The size does not have to be fixed: a minimum and maximum width can be specified using the optional scale_down_to_min_width and scale_up_to_max_width parameters.

A full example of a Richie Ads ad data object looks like this:

{
  "alternatives": [
    {
      "slot_name": "s1",
      "native_width": 500,
      "native_height": 400,
      "scale_down_to_min_width": 250,
      "scale_up_to_max_width": 450
    },
    {
      "slot_name": "s2",
      "native_width": 800,
      "native_height": 600,
      "min_width": 500,
      "scale_down_to_min_width": 550,
      "scale_up_to_max_width": 900
    },
    {
      "slot_name": "s3",
      "native_width": 950,
      "native_height": 750,
      "min_width": 800,
      "scale_down_to_min_width": 800,
      "scale_up_to_max_width": 1080
    }
  ]
}

The Richie Ads SDK is included in all Richie apps by default. A Richie App ID needs to be configured by Richie to enable ad serving. Please contact support for details.

Native Ad SDK Integration in News Articles

Richie apps support inserting ads from native ad SDKs into news article views. A news article can call a Javascript function, richie.insertNewsArticleAds, defined in the Richie mraid.js library, if it wants to have a native ad inserted into the article view.

richie.insertNewsArticleAds takes two parameters:

1. a JS object defining the ads that should be loaded.
2. a callback.

The JS object requires one key, slots. The value of slots is an array of JS objects, each representing one ad to load and requiring two keys:

These values are identical to the ones used in the section feed pseudo articles.

The callback supplied to richie.insertNewsArticleAds is called once for each loaded ad. It must accept one parameter, an object with two keys:

The Richie JS library will resize the DOM element to be of appropriate size for the ad and then request the native app to insert the ad view. The JS library will also install a tracker for the position of the DOM element so if it moves, the ad will be also moved.

Native Article Ad Example

richie.insertNewsArticleAds(
  {
    "slots": {
      [
        "provider": "google",
        "adData": {
          "alternatives": [
            {
              "ad_unit_id": "/2561223/fleet_street_journal/box",
              "manual_impression_counting": true,
              "max_width": 979,
              "custom_targeting": {
                "key1": "value1",
                "key2": "200"
              },
              "category_exclusions": ["category1", "category2"],
              "keywords": ["keyword1", "keyword2"],
              "valid_ad_sizes": [
                {
                  "height": 250,
                  "width": 300
                }
              ]
            },
            {
              "ad_unit_id": "/2561223/fleet_street_journal/big",
              "manual_impression_counting": true,
              "min_width": 980,
              "valid_ad_sizes": [
                {
                  "height": 400,
                  "width": 980
                }
              ]
            }
          ]
        }
      ]
    }
  },
  function (loadedAd) {
    /* check loadedAd.slot if you need slot specific logic */
    const elementCallback = loadedAd.elementCallback;
    const thirdParagraph = document.querySelector('.article-body p:nth-of-type(3)');
    const adContainer = document.createElement('div');
    thirdParagraph.after(adContainer);
    elementCallback(adContainer);
  }
);

Limitations on Native Ad Support

Once you have provided the ad integration an element where the ad should be inserted, you should not make its display CSS property none. The current version does not track that and it will not make the ad disappear.

The current version also do not support ads that resize themselves.