Article Feeds | Richie Dev

This feed will be used when user taps on an article in a section front of the app, when opening a news article from a push notification, from in-app links to articles, when caching news for offline usage, when opening news archive search results, etc. The feed will be fetched from origin by passing the publisher_id value of the article.

Sample:

{
  "content_html_document": "<!DOCTYPE html>\n<html>...</html>",
  "content_external_url": "https://example.com/article.html",
  "assets": [],
  "photos": [],
  "analytics_data": {
    "any-key": "any-value"
  },
  "title": "Article title",
  "share_link_url": "https://example.com/article-web-url.html",
  "publisher_id": "1001",
  "access_entitlements": ['PREMIUM', 'TRIAL'],
  "metered": true
}

The endpoint must set the Content-Type header of the response to application/json. Only the Richie news article feed format is supported; other article formats, such as RSS, can not be used.

It's important that the If-None-Match mechanism is supported to avoid re-downloading and re-processing unchanged article content. The ETag header of the previously fetched feed will be provided as the value of the If-None-Match header.

Property	Description	Value
publisher_id	Required. Unique identifier for the article. This must be the same value which was used to fetch the current article feed from origin.	UTF-8 plaintext
content_html_document	Required, if content_external_url is missing. Full HTML5 document as the value, starting with the DOCTYPE declaration.	UTF-8 text data
content_external_url	Required, if content_html_document is missing. HTTPS URL which should be rendered as article content.	URL String
assets	Optional. Article-specific assets required by content_html_document. Are not used by content_external_url-based articles.	An array of asset objects
photos	Optional. Article-specific photo assets, organized into galleries. Are not used by content_external_url-based articles.	A two-dimensional array of photo objects
analytics_data	Optional. Key-value data that will be available for use in analytics event templates. This must be the same object as in section feed entry for this article.	JSON object. Keys and values UTF-8 text data
title	Optional. Title of the article. This value will be used in native functionality such as social sharing. It will not be rendered as part of the article display - content_html_document or external_content_url defines how the article is rendered.	UTF-8 plaintext
share_link_url	Optional. Link to use with social sharing	HTTPS URL
access_entitlements	Optional. If non-empty, defines the list of entitlements required by this article. Current user must have at least one of these entitlements in order to gain access. Leave out to mark this article as free. Default: article is free.	An array of strings.
metered	Optional. If true, marks this article as accessible via metered access. Metered access itself is configured separately in app-specific configuration. If the article is marked as free (has no access_entitlements), this flag has no effect. Default: false.	false, true

content_html_document

The HTML must import a file called mraid.js (using <script src="…"> tag) as the first JS file in the <head> portion of the document. This file will be made available at runtime by the native apps. It must not be included as part of the HTML itself or as a part of app assets.

The purpose of this file is to enable Richie JS API.

Article Assets

Article-specific assets can be thought of as attachements of the article. When referenced in the feed, they will be available for use by the article HTML.

The platform includes additional functionality for offline photo assets and expects them to be declared separately from other assets. Photos declared this way can be viewed in the native photo gallery feature and can also be automatically scaled to device dimensions within the Richie backend infrastructure.

Asset Objects

Asset objects include two properties; both are mandatory.

Property	Description	Value
remote_url	Required. URL to fetch the resource from	HTTPS URL
local_name	Required. Local relative path to store the file in	UTF-8 plaintext relative path

Note that remote_url contents are expected to be immutable. The apps deduplicate fetch requests and will not fetch an asset from a remote URL if the corresponding file already exists on disk.

The local_name is the local path to the resource relative to the article HTML (index.html). Absolute paths cannot be used. The file will be available in the HTML using the local_name value.

Example Asset Declaration

{
    "assets": [
        {
            "local_name": "mapbox.js",
            "remote_url": "https://cdn.example.org/utils/mapbox.js"
        },
        {
            "local_name": "authors/dominic_fracassa.jpg",
            "remote_url": "https://cdn.example.org/authors/dominic_fracassa.jpg"
        }
    ]
}

Photo Asset Objects

Compared with the generic asset mechanism, photo assets support richer configuration:

Property	Description	Value
remote_url	Required. URL to fetch the resource from	HTTPS URL
local_name	Local relative path to store the file in (optional, unlike with generic assets)	UTF-8 plaintext relative path
caption	Caption, including photo credit	UTF-8 plaintext
required_by_html	True if the HTML requires this asset to render	true, false
scale_to_device_dimensions	Scale images to fit device on Richie backend	false, true

The local_name is the local path to the image, relative to the article HTML (index.html). Absolute paths cannot be used. The file will be available in the HTML using the local_name value. Unlike generic assets, photo assets can omit the local_name property. This will cause the photo to not be downloaded for offline use. Declaring photos this way makes it possible to use them in native photo galleries, where they will be downloaded on demand.

The caption is shown as an overlay on the image in the full screen photo gallery.

If a local name is provided for a photo asset for the purpose of making it available in the native photo gallery in offline mode, but the photo is not shown directly in the article HTML, set required_by_html to false for the image. This allows the app to optimize photo download order.

The Richie backend can optionally scale the images to pixel dimensions appropriate for display on the target device. This is especially useful if the feed references photos in original, unconstrained dimensions. The automatic scaling preserves the aspect ratio of any scaled images.

The scale_to_device_dimensions option is supported for all images, but for images without a local_name it will only affect downloads in the photo gallery. If the article HTML refers to images using remote_url, those requests will not be proxied by Richie and the scaling functionality will not be available.

Finally, unlike generic assets, photos are declared in a two-dimensional array. The first level is an array of photo galleries, many of which can exist on a single story; the second level contains the photos for each gallery. Note that even if you are not using the photo gallery feature, this structure is required when defining photo assets.

Example Photo Gallery Declaration

{
  "photos":
    [
      [
        {
          "local_name": "photos/089209246698.jpg",
          "remote_url": "https://cdn.example.org/photos/089209246698.jpg",
          "caption": "Test offline photo. GETTY IMAGES",
          "scale_to_device_dimensions": true
        },
        {
          "remote_url": "https://cdn.example.org/photos/244982027456.jpg",
          "caption": "Test online photo. GETTY IMAGES"
        }
      ]
    ]
}

This example declares a single photo gallery for the story, with the first image scaled to device dimensions and cached for offline use. The native gallery is launched when the user navigates from the story to a raw image in the gallery, i.e. by following a link to photos/089209246698.jpg or https://cdn.example.org/photos/244982027456.jpg.

Other properties

Article feeds contain many properties which are the same as in the section feeds, such as publisher_id, title, share_link_url and others. Please consult the Section Feed documentation for more detailed description of those fields