Technická dokumentace – Seznam Doporučuje

RSS specifikace

Doporučené články získáváme z RSS feedu, který nám poskytnete. V ideálním případě by měl feed projít validátorem na https://validator.w3.org/feed/. Vaše RSS by pro účely doporučování mělo obsahovat minimálně 100 článků.

Příklad správně formátovaného RSS

<rss version="2.0" >
  <channel>
    <title>Novinky.cz - Kariéra</title>
    <link>https://www.novinky.cz/kariera/</link>
    <description>Novinky.cz – zpravodajský server</description>
    <item>
      <title>Rodinné podniky čeká výměna stráží</tile>
      <description>
        <![CDATA[České rodinné podniky zažívají dobré časy. Polovina ze čtyř set majitelů firem oslovených agenturou Ipsos v rámci výzkumu pro Asociaci malých a středních podniků (AMSP) uvedla, že očekává další růst. Poklesu tržeb se tedy v dohledné době nebojí.]]>
      </description>
      <pubDate>Tue, 17 Apr 2018 11:36:01 GMT</pubDate>
      <guid>https://www.novinky.cz/469439-.html</guid>
      <link>https://www.novinky.cz/kariera/469439-rodinne-podniky-ceka-vymena-strazi.html<link>
      <enclosure url="https://media.novinky.cz/890/678903-top_foto1-7jgls.jpg" type="image/jpeg" length="232"></enclosure>
    </item>
    <item>...</item>
    <item>...</item>
  </channel>
</rss>

Prvky ve feedu

Guid (doporučený prvek) – Používá se jako jednoznačný identifikátor článku v našem systému. O tom, zda se hodnota prvku k tomuto účelu využije, rozhoduje hodnota atributu isPermaLink. Pokud tento atribut chybí, nebo má hodnotu true, musí guid obsahovat trvalou a jedinečnou URL článku. Jestliže prvek guid není přítomen, nebo má atribut isPermalink hodnotu false, použije se místo něj jako unikátní identifikátor prvek link, který musí obsahovat trvalou a jedinečnou URL článku.

Správně
<guid>https://www.example.cz/cestovani/levne-do-ameriky-5864.html</guid>
<guid isPermaLink="true">http://www.example.cz/cestovani/levne-do-ameriky-5864.html</guid>

Správně, je nutné použít i prvek link
<guid isPermaLink="false">aid-3864</guid>

Chybně
<guid isPermaLink="true">tag:blogger.com,1299:blog-555</guid>
<guid>aid-3864</guid>

Link (povinný prvek) – Pokud není přítomen prvek guid, nebo má jeho atribut isPermalink hodnotu false, použije se jako unikátní identifikátor prvek link, který musí obsahovat trvalou a jedinečnou URL článku.

Správně
<link>
  http://www.example.cz/cestovani/levne-do-ameriky-5864.html
</link>

PubDate (povinný prvek) – Očekáváme datum podle specifikace RFC 822. Je doporučeno uvádět časovou zónu. UTC čas označujeme pomocí GMT. Zóny rovněž označujeme pomocí čtyř čísel se znaménkem + nebo – na začátku.

Správně
<pubDate>Wed, 02 Oct 2002 13:00:00 GMT</pubDate>
<pubDate>Wed, 21 Nov 2018 07:29:55 +0000</pubDate>
<pubDate>Wed, 02 Oct 2002 15:00:00 +0200</pubDate>

Nedoporučeno
<pubDate>Wed, 02 Oct 2002 08:00:00</pubDate>

Chybně
<pubDate>Wed, 02 Oct 2002 08:00:00 EST</pubDate>

Title (povinný prvek) – Nadpis článku. Pokud je delší než 257 znaků, bude zkrácen na tuto délku.

Description (povinný prvek) – Stručný popis článku (nebo perex). Pokud je delší než 4 096 znaků, bude zkrácen na tuto délku.

Obrázek (povinný prvek) – Ilustrační obrázek (formát JPG nebo PNG) musí mít rozměry minimálně 400 × 225 pixelů a maximálně 800 × 450 pixelů, poměr stran ideálně 16:9 a velikost do 300 kB. Obrázek nesmí obsahovat vložený text, vodotisk, logo, bílé pruhy po stranách a podobně. Odkaz na obrázek očekáváme jako hodnotu atributu url v jednom z prvků szn:image, media:content, nebo enclosure. Příklady implementace pro jednotlivé možnosti naleznete v technické dokumentaci k newsfeedu.

Rozšířené informace do RSS

Chcete-li ve svém RSS uvádět rozšířené informace, do elementu rss je nutné přidat atribut odkazující na jmenný prostor Seznamu (namespace szn):

xmlns:szn="https://www.seznam.cz"

Příklad
<rss xmlns:szn="https://www.seznam.cz" version="2.0">

Do prvku je pak možné volitelně přidat následující prvky s dalšími informacemi o článku.

Datum expirace – Označuje datum, kdy se má článek přestat doporučovat.

Název prvku: expDate

Příklad
<szn:expDate>Sat, 7 May 2022 15:00:00 GMT</szn:expDate>

Expirace článku – Slouží k označení článku, jehož obsah už zastaral a který má být vyřazen z doporučování.

Název prvku: expired

Příklad
<szn:expired />

Štítek článku – Slouží pro přidání viditelné informace o tématickém zařazení článku. Štítek je možné zobrazovat v doporučovacím boxu.

Název prvku: label

Příklad
<szn:label>Sport</szn:label>

Sekce článku – Umožňuje článek zařadit do tématické sekce (například sport, události, novinky…), která se využívá pro filtrování v rámci doporučování. Článek může být zařazen vždy pouze do jedné sekce. V názvu sekce nesmí být bílé znaky (nejčastěji mezera a znak konce řádku) a znaky s diakritikou. Všechna písmena musí být malá a budou na ně případně převedena. V případě, že je název víceslovný, mezi slovy musí být spojovník (například zivotni-styl).

Název prvku: section

Příklady
<szn:section>sport</szn:section>
<szn:section>jagr</szn:section>

Kódy k nasazení boxu

Kódy k nasazení boxu obdržíte do své e-mailové schránky. Box se nezačne vydávat hned po nasazení – je nutné ho aktivovat na naší straně. Proto nás o nasazení informujte e-mailem zaslaným na seznam.doporucuje@firma.seznam.cz.

Struktura e-mailu s nasazovacími kódy pro doporučovací boxík

Analytický skript

- Do hlavičky každé stránky, mezi tagy <head></head>, vložte následující skript:
<script src="https://d.seznam.cz/recass/js/sznrecommend-measure.min.js" data-webid="xxx"></script>

Výdejový skript

- Vložte tento element na místo ve stránce, kde chcete, aby se boxík zobrazoval:
<div data-szn-recass-hox='{"zone_id": xxx}'></div>

- Na konec stránky vložte následující skripty v zaslaném pořadí, které inicializují výdej boxíku:
<script src="https://d.seznam.cz/recass/js/sznrecommend.min.js"></script>
<script>sznRecass.getRecommendationsByTags();</script>