Section Feeds

A section feed contains all the data that's required to render a single news section in the app. Each section will be fetched from its own feed.

Sample:

{
  "section": {
    "name": "Sports",
     "background_color": {
      "dark": "000020",
      "light": "eae9e2"
    }
    "analytics_data": {
      "any-key": "any-value"
    },
    // and other section-specific properties
  },
  "asset": "an-asset-from-asset-pack.html",
  "articles": [
    {
      "article_full_version": "2021-11-19T09:56:32+00:00",
      "publisher_id": "1001",
      "layout": "featured",
      "title": "Article 1 title",
      "offline_enabled": true,
      "analytics_data": {
        "any-key": "any-value"
      },
      // and other article-specific properties
    },
    {
      "article_full_version": "2021-11-19T10:56:32+00:00",
      "publisher_id": "1002",
      "layout": "small",
      "title": "Article 2 title",
      // and other article-specific properties
    },
    {
      "layout": "ad",
      "ad_provider": "google",
      "ad_data":
        "alternatives": []
        // and other ad object-specific properties
    },
  ]
}

Section Properties

The top-level section object describes the current section.

Asset support

If asset field is defined, the section front will render an HTML asset from the current asset pack. In that case, articles property will be ignored.

Article Properties

The top-level articles property contains an array of objects which will be rendered in the section front. Most of these objects will typically represent articles. However, the same array will be used to include non-article objects such as display ad slots or non-article UI elements such as headlines or buttons. The object type will be determined primarily based on the layout value.

If articles array is empty and there is no asset field defined, the section front will be hidden from the app's main navigation.

The properties listed in the table below apply to the article-type objects only.

Publisher ID

It’s usually a good idea to use the same article IDs you are using internally in other systems. This makes it easy to target specific articles in push notifications, or to tally article views across multiple channels in analytics. For example, if you're using Wordpress CMS, WP Post ID can be used as publisher_id.

Article Versioning

The article_full_version property should contain a string which changes every time the content of the article changes. For example, article's last-modified timestamp or hash of article's content could be used as value for this property.

Offline Cache

By default, article feeds, article assets & photo galleries are fetched on-demand – when user navigates to articles in the app. After these resources are fetched from the network, they're cached in a local cache by the app so that they're available to the user even without a network connection. The cache has a certain max size, and once it's reached, the oldest resources are pruned from the cache.

However, the publisher may alter this behavior by setting offline_enabled flag of article objects in section feeds to true (default value: false). It will cause the apps to cache article feeds, article assets and photo galleries for these articles even before user navigates to them. This feature might be useful in section feeds which contain articles of special importance to the user, e.g. bookmarked articles or articles about favorite topics.

Note that with photo galleries, only photos with a non-empty local_name value will be cached.

Layout Style

layout chooses the layout template the apps use to render a specific item, and the rest of the properties populate the template.

Richie platform supports the following layout styles out-of-the-box, but it is possible to add custom layout styles on a per-publisher (and per brand) basis, so the list of possible values for the style is non-exhaustive. Each layout style can also define its own set of section feed properties which are rendered by those styles.

Four built-in layout styles exist. The default style, big, represents a hero-style "top story" treatment. On tablet landscape layouts, big style renders article title on the left and article image on the right if the title fits in the space on the left. If the title doesn't fit, article image is rendered in full width, and title is rendered underneath the image.

The full_width_text style's main use case is to display a "Breaking news" -type of title (or a set of titles) before the main story of the section front. The background color (defined in app's online configuration) extends from edge to edge, and the title of the full_width_text article is rendered in white. If there are multiple subsequent full_width_text articles, a divider line is rendered in white between them.

Two special layout styles can be used. The ad style indicates that the article is, in fact, a banner ad placement intended to be shown at this position in the list of articles (a separate ad_data property would then be used to include ad serving details). Finally, the none style can be used to omit an article from the main screen and section fronts, making the article only appear by swiping to it within the article browser.

Article Content

As an alternative to providing the content of an article as an HTML document, an external URL can be provided with content_external_url. An article backed by an external URL will not be available for offline use, and can't refer to locally available app assets. The URL provided will be the base URL of the page. Note that content_external_url articles must still be available from the Article Feed endpoint.

As another alternative, an external URL can be provided with external_browser_url attribute. This URL will take the user from news section front directly to the mobile browser. Articles with this attribute should omit the content_external_url attribute. Articles with external_browser_url attributes are not required to be available from the Article Feed endpoint.

Share Link

If a share_link_url is provided for an article, a native share widget will be enabled for the article on the article browser navigation bar.

Swipe Disabled

swipe_disabled will make a story available only by a direct tap on a section front or push notification. Swipe navigation from other stories to this story, and from this story to other stories, is disabled. In the swipe-enabled article browser, this story will be skipped. This is useful when the HTML implementation of the article is not compatible with swipe gestures, or when it simply doesn't make sense to include an article in the article browser.

Using swipe_disabled together with content_external_url is the recommended way of surfacing external content in Richie apps.

Analytics Data

The Richie applications include a flexible, template based analytics mechanism that allows publishers to configure the analytics calls the applications make.

All standard keys of the article object are available in analytics calls related to the article. Should additional analytics data be required, the optional analytics_data object can be used to specify additional keys that will be made available for use in analytics calls.

For example, you can include a canonical URL for a story and use that to construct a Google Analytics call to log a page view for that URL.

The analytics_data key can appear on the top level of the feed (on the same level as the articles array), for each individual article, and for each individual photo in the two-dimensional photos array within an article. If values conflict, the value defined in the most specific level takes precedence.

Article Title

The title is used when displaying the article on the main screen and/or the section fronts. It is not used when displaying the article in the article view (only the HTML document is used in the article view).

Omitting the title property is possible in two cases: if layout is ad, or if image_url is set and you only want to display the image on the section front with no associated title.

Image

The image_url property specifies the image to be used when showing the article on the section fronts. Each layout style specifies the dimensions used to show the image. Layout styles may also decide to not use an image at all. As with the article title, this image is not used when showing the article itself in an article view.

Aspect ratio of the image is decided by the layout style. Richie crops the image automatically when necessary, using face and feature recognition to come up with an appropriate crop. Even so, fitting portrait images into this aspect ratio requires an extreme crop. If a landscape image is available for an article, we recommend choosing it over a portrait image for image_url.

In addition to automatic cropping, Richie will also automatically scale the image to the optimal dimensions for each client device. Because of this, a large original image is appropriate for image_url.

Dates

date and updated_date are used for display purposes only. Include them in the feed only when they should be shown for the specific article on the main screen and section fronts.

The fields support ISO 8601 dates in two specific formats. The first option is a full date and time in UTC: 2018-08-29T14:23:55Z. The second option is just a date, such as 2018-08-29.

Provide just the date when the time is not meaningful to the reader (for example, an arbitrary early morning time a daily edition hits the feed). updated_date should be sent for meaningful updates to the article content, and omitted when the date is identical or very close to the original publication date.

Byline, Kicker and Summary

These optional properties provide text strings used by the layout template blocks in specific ways. The kicker is rendered in all available layout styles, with the following exception: big and featured styles hide kicker and render status_label if both are defined. The byline is only available in the big and featured styles. A summary is shown, if provided, in all styles except small_group_item.

Collection Header Title

Display a title for a collection of articles. The collection_header_title property should have the same value in each article of a group to provide a header for the whole group.

Status Label

A status label is an optional property used to communicate an exceptional status of an article. A typical use would be to label a story as "Breaking News". Depending on the layout style of the article and other factors, the status label is rendered either as an overlay on top of the article image or as a textual label similar to a kicker.

In either case, the color of the label must be specified with the status_label_color property.

Impression Beacons

Richie News support impression beacons for articles. An impression beacon is an URL to which the app makes a GET request when the article becomes visible in the section front. The response data of each GET request is ignored.

Note that each impression is counted - for example, if the article first appears on screen, then user scrolls it off screen, and then scrolls it back on screen, the app makes two GET requests. impression_beacons is an array of such beacon URLs.

Article Hierarchy and the parent field

The articles in a feed can form hierarchies. If an article defines a parent value it should contain the publisher_id value of another article in the same feed. This is typically useful for a main article and supporting articles giving context on the subject, assuming the chosen layout styles support it. This is an one-directional relationship from multiple children to one parent.

Search

Richie apps come with a built-in news search support. The publisher provides an endpoint which accepts search query as an URL query parameter. Search results are generated by this endpoint as a standard section feed.

Sample:

https://example.com/search?query=<search-query>