SmartFormat Specification

Introduction

SmartFormat gives publishers more control over their content in SmartView. With a SmartFormat-compliant feed, SmartView supports recommended links from the publisher and the ability to directly insert and change advertising. In version 2.0, SmartFormat has been upgraded to support SmartView First, an opt-in, optimized viewing experience for your readers that provides better publisher branding and links to your sponsored content.

Version History

  • Version 2.0 - this document
  • Version 1.1.4 - earlier version for non-SmartView First publishers

What’s New in version 2.0

  • <snf:logo> added to <channel> element
  • <snf:analytics> added to <item> or entry element
  • <snf:video> added to <item> element
  • <snf:sponsoredLink> added to the <snf:advertisement> sub-element within <item> or entry element
  • <snf:relatedLink> support depreciated

Sample Image, SmartView First

Sample Image, SmartView First

Syntax

Format

SmartFormat is an extention of RSS 2.0 (http://cyber.law.harvard.edu/rss/rss.html) or Atom (http://tools.ietf.org/html/rfc4287).

Character Code

SmartFormat only supports UTF-8.

Namespaces

SmartFormat supports the following namespaces.

Type URL Recommended Namespace
RDF Site Summary 1.0 Modules: Content http://purl.org/rss/1.0/modules/content/ content
DCMI Metadata Terms http://purl.org/dc/elements/1.1/ dc
SmartNews Format http://www.smartnews.be/snf [1] snf

[1] Specifies related links and advertising placed in SmartView.

Elements (RSS 2.0)

<xml>

Specifies XML document version and character code.

<?xml version="1.0" encoding="utf-8" ?>

<rss>

Specifies RSS version and namespaces.

<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/" xmlns:snf="http://www.smartnews.be/snf">
...
</rss>

<channel>

A description of your website.

Sub Element Required Explanation Example
<title> Title of the website (HTML not supported) The Smart Times
<link> URL of the website http://times.smartnews.com/
<description> short description(30 characters or less recommended) News for all
<pubDate> Published date (must comply with RFC822) Wed, 01 Oct 2014 06:00:00 GMT
<language> Language en
<copyright> Copyright SmartNews, Inc.
<ttl> Time to live (minutes) 15
<snf:logo> Logo Image (290 x 50 px explained below) <snf:logo><url>http://times.smartnews.co.jp/snlogo.png</url></snf:logo>
<item> Articles (explained below)

<snf:logo>

Specifies the logo image shown on top of the article.

  • 290 x 50 px PNG file with alpha channel recommended.
  • Please see below examples for more detailed design instructions.

  • Please make sure the logo looks clear on various backgounds with bright or dark colors.

<item>

Describes each article.

Sub Element Required Explanation Example
<title> Title of the article SmartNews Launches
<link> URL of the article http://times.smartnews.com/2014/10/01/smartnews-launches
<guid> An arbitrary string that uniquely identifies the article http://times.smartnews.com/2014/10/01/smartnews-launches
<description> Article summary SmartNews makes it fast and easy to discover interesting stories by ranking and displaying news in colorful, easy-to-use topic channels.
<pubDate> Publishing date (must comply with RFC822) Wed, 01 Oct 2014 06:00:00 GMT
<content:encoded> Full-text article See the sample code below
<category> Comma-separated keywords mobile,news,app
<dc:creator> Author Rich Jaroslovsky
<dc:language> Language en
<media:thumbnail> URL of the thumbnail (larger than 400 x 400px recommended) http://times.smartnews.com/2014/10/01/smartnews.png
<media:status> Status of the article (active or deleted) active
<snf:advertisement> Advertisement (see below)
<snf:analytics> Analytics script for SmartView (see below)
  • For best results, specify a thumbnail image larger than recommended size.
  • Be careful with a double escape when the title is marked up with CDATA.
  • Make sure to use the URL of the article without any UTM tracking parameters or other extentions.
  • If an article is redirected, use the redirected URL.
  • Please put the full text of the article into <content:encoded> element - no partial text or paginations.
  • You may detete the article from SmartNews by adding “deleted” in <media:status> element
  • Do not include sponsored content (including house ads), adult content, and re-distributed content without permision in <link> element.

<snf:advertisement>

Specifies advertising which is displayed in SmartView of this article.

  • One <snf:advertisement> can be specified per <item>.
  • One <snf:adcontent> can be specified per <snf:advertisement>.
  • Available ad sizes are 300 x 250px and 320 x 50px.
<snf:advertisement>
  <snf:adcontent><![CDATA[
    <script type="text/javascript"
    src="http://sample-ad.com/?id=12345"></script>
    <script type="text/javascript">
    //<![CDATA[
    if(typeof(sampleAd) != "undefined") sampleAd.show('23456');
    //]]>
    </script>
  ]]></snf:adcontent>
</snf:advertisement>
Sub Element Required Explanation Example
<snf:adcontent> Ad tag <script src="http://ad.smartnews.co.jp/m/51290410" />
<snf:adcontent> Sponsored content <snf:sponsoredLink link="http://times.smartnews.com/sponsored/article1.html" thumbnail="http://times.smartnews.com/sponsored/image1.jpg" title="sponsored link 1" advertiser="Example Company"/>

<snf:adcontent>

Specifies ad tag to be used in SmartView of this article as an element under <snf:advertisement>.

  • One <snf:adcontent> can be specified per <snf:advertisement>.
  • The largest ad tile supported is 300 x 250px.
Attribute Required Explanation Example
id ID of advertisement <snf:adcontent id="51290410">

Specifies sponsored content which is displayed under this article as an element under <snf:advertisement> (House ads allowed).

  • The name of the advertiser is required in the <advertiser> element.
    • Specifies the name of the entity underwriting the sponsored content.
    • In the case of house ad, specify your company name.
  • Up to two <snf:sponsoredLink> items can be specified per <snf:advertisement>.
  • URL of the article in <link> is limited to one under your domain.
Attribute Required Explanation Example
<link> URL of the sponsored content http://times.smartnews.com/sponsored/article1.html
<title> Title of the sponsored content What we love about our sponsor!
<thumbnail> Thumbnail URL of the sponsored content (aspect ratio 4:3, 320 x 240 px recommended) http://times.smartnews.com/sponsored/image1.jpg
<advertiser> Advertiser name of the sponsored content Big Man Boots
<snf:advertisement>
  <snf:sponsoredLink link="http://times.smartnews.com/sponsored/article1.html" thumbnail="http://times.smartnews.com/sponsored/image1.jpg" title="桜丘に新スイーツ店が誕生!" advertiser="桜丘スイーツ"/>
  <snf:sponsoredLink link="http://times.smartnews.com/sponsored/article2.html" thumbnail="http://times.smartnews.com/sponsored/image2.jpg" title="sponsored link 2" advertiser="Example Company"/>
  <snf:adcontent id="51290410"><![CDATA[
    <script src="http://ad.smartnews.co.jp/m/51290410" />
  ]]></snf:adcontent>
</snf:advertisement>

<snf:analytics>

Specifies an analytics script to track SmartView pageviews.

  • SmartFormat 2.0 supports comScore and Google Analytics, as well as other analytics tools upon request.
    <snf:analytics><![CDATA[
    <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-xxx-2', 'examplecom');
  ga('require', 'displayfeatures');
  ga('set', 'referrer', 'http://www.smartnews.com/');
  ga('send', 'pageview', '/260984/upsee/');
    </script>
    ]]>
  </snf:analytics> 

<snf:video>

Used to upload video files to SmartNews. Please use the format below to specify the raw video file to be used. SmartNews will download and transcode the file to be served by the SmartNews app.

<snf:video url="http://www.foo.com/bar.mp4" caption="foo video" />

Movie file requirements are as follows:

  • File size: 600 MB
  • Length: Up to 5 minutes (90 seconds recommended)
  • Video codec: h.264
  • Audio codec: aac
  • Bit rate: 1 Mbps
  • File format: mp4

Elements (Atom)

xml

Specifies XML document version and character code.

<?xml version="1.0" encoding="utf-8" ?>

feed

Specifes version and namespace.

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/" xmlns:snf="http://www.smartnews.be/snf">
...
</feed>

Describes the website.

Element Required Explanation Example
title Title of the website (HTML not supported) The Smart Times
link URL of the website
subtitle short description (less than 30 characters recommended) News for all
pubDate Published date (must comply with W3CDTF) 2014-05-16T06:00:00+0000
rights copyright © SmartNews Inc.
snf:logo Logo image (290 x 50 px recommended) http://times.smartnews.co.jp/logo.png
entry Articles (explain below)

entry

Describes each article.

Sub Element Required Explanation Example
title Title of the article SmartNews Launches
link URL of the article
guid An arbitrary string that uniquely identifies the article http://times.smartnews.com/2014/10/01/smartnews-launches
updated Publishing date (must comply with W3CDTF) 2014-05-16T06:00:00+0000
content Full-text article See the sample code
category Comma-separated keywords mobile,news,app
author Name of author Rich Jaroslovsky
dc:language Language  en
media:thumbnail URL of thumbnail image (Bigger than 200☓200px required, 400px~ recommended.) http://times.smartnews.com/2014/10/01/smartnews-launches/img.png
media:status status of the article (active or deleted) active
snf:advertisement Advertisement (see below)
snf:analytics Specifies an analytics script to track SmartView pageviews (see below)

Allowed HTML elements

Inside <content:encoded>

a, abbr, acronym, address, article, aside, b, base, basefont, bdi, bdo, bgsound, big, blink, blockquote, body, br, caption, center, cite, code, col, colgroup, command, data, datalist, dd, del, details, dfn, dir, div, dl, dt, em, fieldset, figcaption, figure, font, footer, form, h1, h2, h3, h4, h5, h6, header, hgroup, hr, html, i, img, ins, kbd, label, legend, li, listing, main, mark, marquee, menu, meter, nav, nobr, ol, p, plaintext, pre, q, rb, rp, rt, ruby, s, samp, section, small, spacer, span, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, time, tr, tt, u, ul, var, wbr, xmp

Sample (RSS 2.0)

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/" xmlns:snf="http://www.smartnews.be/snf">
  <channel>
    <title>The Smart Times</title>
    <link>http://times.smartnews.com/</link>
    <description>News for all</description>
    <pubDate>Wed, 01 Oct 2014 06:00:00 GMT</pubDate>
    <language>en</language>
    <copyright>SmartNews, Inc.</copyright>
    <ttl>15</ttl>
    <snf:logo><url>http://times.smartnews.co.jp/snlogo.png</url></snf:logo>    
    <image>
        <url>http://times.smartnews.com/logo.png</url>
        <title>The Smart Times</title>
        <link>http://times.smartnews.com/</link>
    </image>
    <item>
        <title>SmartNews Launches</title>
        <link>http://times.smartnews.com/2014/10/01/smartnews-launches</link>
        <guid>http://times.smartnews.com/2014/10/01/smartnews-launches</guid>
        <description><![CDATA[
        SmartNews makes it fast and easy to discover interesting stories by ranking and displaying news in colorful, easy-to-use topic channels.
        ]]></description>
        <pubDate>Wed, 01 Oct 2014 06:00:00 GMT</pubDate>
        <content:encoded><![CDATA[
            <p>SmartNews, the free, award-winning news-discovery app, today announced the release of its long-anticipated U.S. edition for Apple and Android mobile devices. SmartNews is building on its success in Japan, where it is helping five million users discover interesting, important, and popular stories. Much like the Japanese edition, the app promises to bring speed, utility and serendipity to finding news for users in the United States.</p>

            <p>SmartNews makes it fast and easy to discover interesting stories by ranking and displaying news in colorful, easy-to-use topic channels. The Japanese edition of SmartNews has earned rave reviews from users, as well as industry-wide recognition, including a “Google Play App of the Year” award and an Apple “App Store Best of” in news in 2013.</p>
        ]]></content:encoded>
        <category>mobile,news,app</category>
        <dc:creator>Rich Jaroslovsky</dc:creator>
        <dc:language>en</dc:language>
        <media:thumbnail url="http://times.smartnews.com/2014/10/01/smartnews.png" />
        <snf:advertisement>
        <snf:sponsoredLink link="http://times.smartnews.com/sponsored/article1.html" thumbnail="http://times.smartnews.com/sponsored/image1.jpg" title="桜丘に新スイーツ店が誕生!" advertiser="桜丘スイーツ"/>
        <snf:sponsoredLink link="http://times.smartnews.com/sponsored/article2.html" thumbnail="http://times.smartnews.com/sponsored/image2.jpg" title="sponsored link 2" advertiser="Example Company"/>        
            <snf:adcontent><![CDATA[
                <script type="text/javascript" src="http://sample-ad.com/?id=12345"></script>
                <script type="text/javascript">
                //<![CDATA[
                if(typeof(sampleAd) != "undefined") sampleAd.show('23456');
                //]]>
                </script>
            ]]></snf:adcontent>
        </snf:advertisement>
    <snf:analytics><![CDATA[
    <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-xxx-2', 'examplecom');
  ga('require', 'displayfeatures');
  ga('set', 'referrer', 'http://www.smartnews.com/');
  ga('send', 'pageview', '/260984/upsee/');
    </script>
    ]]>
  </snf:analytics> 
    </item>
    <item>
        ...
    </item>
    <item>
        ...
    </item>
</channel>
</rss>

Sample (Atom)

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/" xmlns:snf="http://www.smartnews.be/snf">
  <title>The Smart Times</title>
  <link type="text/html" href="http://times.smartnews.co.jp/" rel="alternate"/>
  <subtitle>News for all</subtitle>
  <updated>2014-05-16T06:00:00+0000</updated>
  <rights>(c) SmartNews, Inc.</rights>
  <logo>http://times.smartnews.com/logo.png</logo>
  <snf:logo><url>http://times.smartnews.co.jp/snlogo.png</url></snf:logo>
  <entry>
    <title>SmartNews Launches</title>
    <link type="text/html" href="http://times.smartnews.co.jp/2014/06/16/sakuragaoka" rel="alternate"/>
    <id>http://times.smartnews.com/2014/10/01/smartnews-launches</id>
    <updated>2014-05-16T06:00:00+0000</updated>
    <content><![CDATA[
       <p>SmartNews, the free, award-winning news-discovery app, today announced the release of its long-anticipated U.S. edition for Apple and Android mobile devices. SmartNews is building on its success in Japan, where it is helping five million users discover interesting, important, and popular stories. Much like the Japanese edition, the app promises to bring speed, utility and serendipity to finding news for users in the United States.</p>

            <p>SmartNews makes it fast and easy to discover interesting stories by ranking and displaying news in colorful, easy-to-use topic channels. The Japanese edition of SmartNews has earned rave reviews from users, as well as industry-wide recognition, including a “Google Play App of the Year” award and an Apple “App Store Best of” in news in 2013.</p>
        ]]></content>
    <category>mobile,news,app</category>
    <author>Rich Jaroslovsky</author>
    <dc:language>en</dc:language>
    <media:thumbnail url="http://times.smartnews.com/2014/10/01/smartnews-launches/img.png" />
    <snf:advertisement>
      <snf:adcontent><![CDATA[
                <script type="text/javascript" src="http://sample-ad.com/?id=12345"></script>
                <script type="text/javascript">
                //<![CDATA[
                if(typeof(sampleAd) != "undefined") sampleAd.show('23456');
                //]]>
      </script>
      ]]></snf:adcontent>
    </snf:advertisement>
    <snf:analytics><![CDATA[
    <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-xxx-2', 'examplecom');
  ga('require', 'displayfeatures');
  ga('set', 'referrer', 'http://www.smartnews.com/');
  ga('send', 'pageview', '/260984/upsee/');
    </script>
    ]]>
  </snf:analytics> 
  </entry>
  <entry>
    ...
  </entry>
</feed>

Allowing Access from SmartNews Server

Data Fetch

Interval

The articles are repeatedly fetched at a specified interval (minutes) in <ttl> element. The minimum interval is 1 minute.

<ttl>15</ttl> <!-- minutes -->

Note: The interval can not be specified when using ATOM.

Protocol

A connection is made via HTTP GET method.

GET /smartformat.xml HTTP/1.1

User Agent

The User-Agent request header starts with “Crowsnest”.

User-Agent: Crowsnest

When the Fetch Starts

Access to SmartFormat URL starts after you grant permission to it. Please contact us when it’s ready.

Access Restriction

If you don’t want to make your SmartFormat URL publicly accessible, you can restrict the access to it using the following methods.

  • Access restriction by IP address
  • Access restriction by basic authentication

Please contact us for details.

Validation Tool

We provide a SmartFormat validation tool online.

http://validator.engine.smartnews.be/

Important Notes

Unallowed Characters

SmartFormat is an XML format. If characters which are not allowed by XML specification are included in a document, we can not parse it correctly. For more information about XML specification, please see http://www.w3.org/XML/Core/#Publications.

Below are some things to watch.

Characters are not escaped appropriately

Inside an element, please don’t forget to convert "<", ">" to "&lt;", "&gt;" respectively. Similary, please convert "&", " " ", " ‘ " to "&amp;", "&quot;", "&apos;" respectively.

Date Format of <pubDate>

The value of <pubDate> must be specified in accordance with RFC822 ( https://www.ietf.org/rfc/rfc0822.txt ).

Time Zones

Please specify a time zone using one of the following notations.

  • Greenwich Mean Time (GMT or +0000)
  • Time zone to which the website belongs (if you are in New York, your time zone is PST or -0800)

For example, the following are correct notation to express “May 16, 2014 15:00:00 (PST)“.

  • Fri, 16 May 2014 23:00:00 GMT
  • Fri, 16 May 2014 15:00:00 -0800

FAQ

About the Specification

My website already has an RSS feed. Do I have to create a new one for SmartFormat?

SmartFormat follows RSS 2.0 or Atom specifications. It is possible that your existing RSS 2.0 or Atom feed can be used as a SmartFormat feed without any modification. However, there are some differences between them and SmartFormat. Please check them carefully in the validator.

Does SmartFormat support RSS 1.0?

Currently, we have no plans to support RSS 1.0.

Where should I place a SmartFormat document?

You can place it anywhere on your website.

Do I have to provide all the elements defined above?

Elements marked as required must be provided. Other elements are optional.

How many items should I prepare in one document?

There is no particular restriction, but too many items may cause a slowdown on our servers. The recommended maximum number of items in one document is approximately 100. The entire feed file size should be smaller than 1MB.

We use different URLs for PC and mobile. Which do I have to specify in SmartFormat?

Please specify the "canonical" URL of the article, which might be specified with the element <link rel="canonical" href="xxx" /> or <meta property="og:url" content="xxx" />.

What type of categories should I specify in <category> element?

Categories should be good representative of the article. They could help SmartNews’s algorithm better understand the article.

Is it possible to display more than one advertising tag per article?

Currently, only one advertising tag is allowed.

Is it possible to adjust the position of advertising units on SmartView?

Currently, the position is fixed.

What happens if an article contains HTML tags which are not allowed?

In such cases, the article will be shown without having unallowed tags.

Can I use JavaScript as content?

JavaScript is not allowed except for the Brightcove script explained below.

Is it possible to embed videos in the article?

Currently YouTube, Vimeo, Brightcove, Ooyala and JW Player embeds are supported.

To use YouTube, Vimeo, Ooyala or JW Player, please insert the <iframe> embed code inside the <content:encoded> element.

To use Brighcove, you must insert both the embed code and also reference the Brightcove JS inside the <content:encoded> element.

For example:

<script  language="JavaScript" type="text/javascript" 
src="http://admin.brightcove.co.jp/js/BrightcoveExperiences.js"></script>
<object id="myPlayer"  class="BrightcoveExperience">
<param name="bgcolor" value="#FFFFFF" />
<param name="width" value="790" />
<param name="height" value="529" />
<param name="playerID" value="1234567890" />
<param name="playerKey" value="AQ~~,AAAAstMe5SE~,5vOZeV6rFDb4JUBomUtNzVLbOfHyhc1i" />
<param name="isVid" value="true" />
<param name="isUI" value="true" />
<param name="@playlistTabs"  value="ref:myPlaylist6789" />
</object>

Currently, the following Brighcove scripts are supported.

http://admin.brightcove.co.jp/js/BrightcoveExperiences.js
http://admin.brightcove.co.jp/js/BrightcoveExperiences_all.js
http://admin.brightcove.com/js/BrightcoveExperiences.js
http://admin.brightcove.com/js/BrightcoveExperiences_all.js

What happens if my SmartFormat feed fails to comply with the specification?

In such cases, the feed is simply ignored.

If I prepare a SmartFormat feed, all the included articles will be delivered on SmartNews?

No. The purpose of SmartFormat is to control the display of an article on SmartView when it’s delivered. SmartFormat has nothing to do with the selection of articles.

When I prepare a SmartFormat feed, only the articles included in it will have a chance to be delivered?

We use a combination of SmartFormat and a general web crawling. That means the articles which are not present in SmartFormat could be delivered via general crawling. If you don’t want that please contact us.

How to attach a thumbnail image to the article?

You can specify it using <media:thumbnail>.

Will the images embedded in SmartFormat be delivered directory or cached?

Images specified with <media:thumbnail> will be delivered through our cache server. Other images will be delivered directly.

About the Connection

I don’t want to make our SmartFormat feed public.

We support access restriction either by basic authentication or IP address. For more information, see “Access Restriction”.

Can you access to our SmartFormat feed via other methods than HTTP, such as FTP?

Currently, we have no plans to support any methods other than HTTP.

Contact Us

If you have any questions or feedback, please contact us at partners@smartnews.com.