Display Ads

Richie applications support four 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. Interactive full page ads can be shown between swipes in the article browser. The supported ad technology for full page ads is Richie Ads.

4. 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 option 1. 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.

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.

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.