More advanced RSS feed curation & mappings

We have moved to docs.pugpig.com! You can find this article here

Matching timelines to editorially curated home or section pages

If your editorial team manually or automatically curates home pages or section pages, it is often preferable for the app to mirror these pages. If this is the case, we recommend:

• One RSS feed per timeline
• The order of the articles in the feed should exactly match the order you wish the articles to appear in the timeline in the app
• When an article drops off the feed, it will also be removed from the timeline.

Note: If an article is in multiple of these timelines (e.g. Home, News and Sport), the RSS entry for the article does need to be identical in all the feeds that contain it. In particular, it still need to reference all the timelines in which it appears, for example:

<category>Home</category>

<category>News</category>

<category>Sport</category>

Defining the timeline layouts for cards

In the app each article is represented by a card on the timeline, with a few different layouts for these supported out of the box. If the layouts of the timeline are not known in advance, but are specified in your editorial system, you can specify a layout in the timeline using a <layout> entry in the feed. For example:

<layout>image-large</layout>

The full list of out-of-the-box layouts for article cards is: 

'image-small'
'image-small-left'
'image-none'
'image-large'
'image-large-bottom'

Note: These layouts are independent of the position an article appears in the feed. So, for example, if you specified an image-large layout, the article would have this layout in any position in the feed.

In some cases, you may even wish to specify a different article layout depending on the timeline. In this case, you could specify something like this:

<media:category>Home:image-large</media:category>

<media:category>News:image-small</media:category>

<media:category>Sport:image-none</media:category>

Half-width cards:

We support displaying articles in half-width cards (i.e. they display side-by-side in the timeline), however it is especially important that the feed dictates two half-width cards in sequential order so that they can display correctly on the timeline. For example, these two articles would display side-by-side on the Home timeline:

Article 1

<media:category>Home:widget-half</media:category>

Article 2

<media:category>Home:widget-half</media:category>

There is also a variant layout for half-width widgets where the image is presented below the text: `widget-half-bottom`

Adding carousel cards

We’re able to support displaying a series of sequential articles in a ‘carousel’. You can flag this the feed like this:

Article 1:

<media:category>Home:carousel</media:category>

Article 2:

<media:category>Home:carousel</media:category>

Article 3:

<media:category>Home:carousel</media:category>

Basing card layouts on position in the feed

If the layout of a timeline is known in advance (e.g. always have a hero card at the top, followed by smaller ones), then it is better if the layout is not sent in the feed. In this case, talk to our professional services team to agree on the layouts of the timelines as part of the project. This has the advantage that you can just send us the content, and we do the rest.

Detecting changes in the feed

Normally the Pugpig Importer will check the <updated> date on an article to determine whether it should be re-imported. However, there are times when it might be difficult for you to provide an accurate updated date that takes all important information (for example, layout) into account. In this case, the other option is it provide a hash of all relevant information as a new element in the feed, and we will re import articles should the hash change, If this is done, then the update date of all articles should be the current time. For example:

<hash>34wfgwgf3t3gseffg</hash>

<updated>[current time in correct format]</updated>

Adding flags to cards

A “flag” is a label shown on a card. More than one can be displayed. Examples could be: LATEST, LIVE, TRENDING or anything else. Each flag should be specified as its own item in the feed, with a value or true or false. Not specifying anything implies false. For example:

<flag_latest>true</flag_latest>

<flag_live>true</flag_live>

Specifying if an article is free or paid

This should also be specified in the RSS feed if it varies by article. In most cases, a <free>true</feed> element is included for free articles. However, if your model is more complex (for example, only certain articles count towards an article meter) then more detail will be needed.

Audio and Video Feeds

Audio and video feeds can be treated in a very similar manner to article RSS feeds, with the addition of the audio or video URLs. However, we can also directly ingest RSS feeds from third party providers. For example, some common ones could be iTunes or ACast for audio feeds.