Follow our specifications to ensure a seamless upload of article content.
RSS Specifications
For text-based articles, MAZ can process most standard RSS feeds as-is. In order to include advertisements, image galleries, and/or video content, there are certain modifications that must be made to a standard RSS feed.
Please Note: MAZ recommends RSS with UTF-8 Encoding.
The W3C provides a free RSS/ATOM feed validator tool, which can be found here:
https://validator.w3.org/feed/. If you encounter any problems adding one of your feeds to our platform, try running it through this validator first to make sure it validates. This can be a great tool to pinpoint any errors that may be associated with your feed.
To add a RSS feed get started here!
- Navigate to the Section you would like to add RSS feed.
2. Click on +Content, +Feed, then +RSS/Atom.
3. Enter the following information in their respective fields:
- Name (Internal facing)
- Feed URL
- Title (External)
- Subtitle (External)
- Description (External)
- PDF Upload*
*PDF Upload Note: If the JSON feed is a web-based replica of a printed edition/issue of a magazine, you can upload the PDF for the edition/issue here to allow compliance with AAM circulation regulations for digital editions
4. In the next form you see, fill in the metadata for the content menu you are adding to your app and save the form. For example, access, cover date, release date, download options etc.
A complete sample feed is also included at the bottom of this document.
Few elements of the feed explained below:
Item Type: Article
The article item uses a standard format familiar to most article-based RSS feeds. MAZ will extract the body of the article, including images and formatting, directly from the <link> URL.
Sample: Article Item
___
Optional tags per item:
Item captions
In order to add captions to the image, please add <figure> and <figcaption> tags inside CDATA. Example below:
Modified timestamp
<maz:modified>1514038421</maz:modified>
This represents the timestamp of the last modification to the item. This should be in epoch time format represented in seconds and it is stored as an integer. MAZ heavily relies on this value and in case of a change in the timestamp, will compare this value from its previous value and will reprocess the article if the newer timestamp is greater than the previous one, otherwise will ignore reprocessing. If this field is missing from the feed, the article will be processed only the first time.
Templates
If the template name is not available, it will default to what is selected in the MAZ dashboard.
Multiple Templates
If Template = “web”, MAZ will not create article templates for those articles, they will open the source website instead of templates. If no custom template is passed, the default MAZ template will be applied to the articles.
Item Type: Gallery
The gallery item uses a format similar to the article item, but it has some specific tags that apply only to galleries. Galleries can consist of both photos and videos.
<maz:type>: Specifies what type of item it is.
<maz:galleryCover>: The image asset to be displayed as the thumbnail for the gallery.
<maz:galleryItem>: Specifies a single gallery item. If it is an image, no type is required. If the item is a video then you must specify the type parameter as ‘video’ (e.g. type=”video”). The gallery items will be displayed in the order by which they appear in the feed.
<maz:galleryAsset>: The source image/video to be displayed in the gallery. This can be a URL in the event of an image/video file, or an HTML video embedded using the CDATA tag.
<maz:galleryCaption>: Text that will be displayed on the screen along with the current gallery image. This tag supports the inclusion of HTML content/formatting by using the CDATA tag.
<maz:textUpper>: Optional text that will be displayed on the screen above the gallery asset thumbnail. This tag supports the inclusion of HTML content/formatting by using the CDATA tag.
<maz:textLower>: Optional text that will be displayed on the screen below the gallery asset thumbnail. This tag supports the inclusion of HTML content/formatting by using the CDATA tag.
Sample: Gallery Item
Item Type: Video
The video item is similar to the article item, but it has some specific tags that apply only to videos.
<maz:type>: Specifies what type of item it is.
<maz:video>: The source URL (Sample #1 below) of the video to be displayed. There can be only one video per <item>.
Direct video URLs (or Streaming URLs) that are natively supported on iOS devices are preferable.
<maz:videoImage>: The image asset to be displayed as the thumbnail for the video.
<maz:videoEmbedCode>: The HTML embed code (Sample #2 below) of the video to be displayed. There can be only one video per <item>. Please note that when using an embed code it must be nested within a CDATA tag. For mobile device displays, maximum width should be 350px.
<maz:textUpper>: Optional text that will be displayed on the screen above the video thumbnail. This tag supports the inclusion of HTML content/formatting by using the CDATA tag.
<maz:textLower>: Optional text that will be displayed on the screen below the video thumbnail. This tag supports the inclusion of HTML content/formatting by using the CDATA tag.
Sample #1: Video Item (URL)
Sample #2: Video Item (Embed Code)
Item Type: Advertisement
The advertisement item is displayed only when a user is swiping between articles in the article view of the app and does not appear as a separate item in the feed as articles do. Advertisements consist of a URL to an image asset and can include an optional URL for the users to be directed to when they tap on an advertisement. The advertisement related tags are:
<maz:type>: Specifies what type of item it is.
<guid>: A unique identifier for the ad
Sample: Advertisement Item
The recommended advertisement image size is 2208 pixels wide by 1242 pixels high for optimal display on the highest resolution screens for devices currently on the market. In the event that your advertisement assets do not match those dimensions exactly, making them 2208 pixels wide should be the priority (over the height). For any assets that do not fill the screen exactly, we will letterbox them with black borders when displaying them in the app. The advertisements will appear in the app in the same order that they appear in the feed (between the articles).
Item Type: Heading
The heading related tags are:
<maz:type>: Specifies what type of item it is.
<guid>: A unique identifier for the heading
<title>: The heading text that will be displayed in the app. We recommend that it should be less than or equal to 20 characters in length so that it shows up correctly across all devices.
Sample: Heading Item
Item Type: Image
The image-related tags are:
<maz:type>: Specifies what type of item it is.
<guid>: A unique identifier for the image
Sample: Image Item
___
Complete Sample Feed
Feed Processing
Feed processing times usually depend on various factors like:
- Number of articles in the feed
- The content of the articles
- Load on MAZ Servers
If you're seeing a delay in the appearance of articles in the app, it is probably because of the above reasons.
There can be a few cases where a few articles may fail during processing by the third-party article extraction tool we use ie. Diffbot. Diffbot is used to extract the body, images, headings, byline, etc. from articles that allow MAZ to create templatized versions of the articles with the templates applied based on your choice in the MAZ dashboard.
A few examples of Diffbot errors when processing articles:
- Could Not Download Page
- Automatic Page Concatenation Exceeded Timeout
- Error Downloading URL
And more can be found here.
In case of these failures, MAZ will load the original source URL of the article in a web view in the app instead of loading the templatized article ie. such articles will open to the actual article on your website without any MAZ template applied.
Some websites may have paywalls or higher security measures that may block our scrapers. In this case, please whitelist our user-agent:
MAZBot/1.0 (http://mazdigital.com)
Please contact your system administrator to whitelist this user-agent.
Important Note: We utilise etag and last-modified response headers for RSS Feed's version validation, to update the apps with the newly added content in the RSS Feed. Learn more about Feed version validation here.