SmartFormat Specification (version 1.1.4)

Introduction

SmartFormat gives you control over your content in SmartView. You can also dynamically embed your advertising tags into your SmartView pages using the SmartFormat feed.

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] It primarily 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(less than 30 characters 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
<image> Logo image (512 x 512px recommended) http://times.smartnews.com/logo.png
<item> Articles (explained below)

<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 including lead image See the sample code below
<category> Comma-separated keywords mobile,news,app
<dc:creator> Author, supports one or more authors 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 (explained later)

Specifies links to related articles. More than one <snf:relatedLink> elements are allowed per article.

Attribute Required Explanation Example
<link> URL of the related article http://times.smartnews.com/2014/08/08/smartnews-raises-36-million
<title> Title of the related article SmartNews Raises $36 Million
<thumbnail> Thumbnail URL of the related article http://times.smartnews.com/2014/08/08/smartnews.png

<snf:advertisement>

Specifies advertising which is displayed in SmartView of this article.

  • One <snf:advertisement> can be specified per <item>.
  • One <snf:admaterial> 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 See above

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.
logo logo image of website(512 x 512 px) 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 including lead image See the sample code
category Comma-separated keywords mobile,news,app
author Author, supports one or more authors 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 (explained later)

<snf:advertisement>

Specifies advertising which is displayed in SmartView of this article.

  • One <snf:advertisement> can be specified per <item>.
  • One <snf:admaterial> 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 See above

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>
    <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[
            <img src="http://times.smartnews.com/2014/10/01/smartnews-launches/lead-image.png"><br>
            <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: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>
    </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>
  <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[
       <img src="http://times.smartnews.com/2014/10/01/smartnews-launches/lead-image.png"><br>
       <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>
  </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.

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

We recommend you to set the interval to a smaller value because a long interval makes it difficult to keep your contents up to date.

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 is a common mistake.

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. There are possibilitis 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.

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.

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.

How many related links can be specified per article?

There is no particular restriction. However, we may put limits on excessive links.

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

Currently, only one advertising tag is allowed.

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.

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 and 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 directly 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 format@smartnews.com.