Dokumentace ke zpracovávaným článkům

Dokumentace obsahuje informace o zpracovávaných meta informacíh pro import článků. V případě jakýcholiv dotazů nás můžete kontaktovat na homepage.metadata(zavináč)firma.seznam.cz

Novinky v dokumentaci

16. února 2021: 9. února 2021:

Jak data načítáme

1) RSS výdej

První načtení článku provedeme z výdeje RSS společně s položkami k jednotlivým článkům, které jsou u tohoto článku v RSS k dispozici

2) Aktualizace v článcích

Pokud dojde k úpravám článku, jsme schopni tyto změny (titulek, popis a obrázek) za určitých podmínek načíst. V tomto případě už načítáme zdrojový kód (dostupný pod URL článku), nikoli z RSS. Hlídejte prosím priority jednotlivých položek ve zdrojovém kódu. Titulek a popis načítáme jen z JSON-LD, obrázek prioritně z JSON-LD a pokud není k dispozici, zkoušíme načíst obrázek z jiných sekcí. Problém může např. nastat při absenci JSON-LD, když nesprávný náhledový obrázek použije tag og:image (viz open graph), protože pak má dle priorit obrázků obrázek tagovaný og:image přednost před hlavním náhledovým obrázkem (získaným při prvním načtení z RSS, viz předchozí bod 1). Tím by vzniklo nežádoucí chování z pohledu správného publikování dat. Volte ve zdrojovém kódu článku takové tagy, které nebudou přetěžovat prioritu ostatních tagů (pokud to není záměr).

Pro aktualizace se zachováním co největší flexibility na obou stranách doporučujeme použít sekce JSON-LD.

RSS položky

Hodnoty zpracovávané dle standardu RSS přímo ze seznamu RSS položek.

Hlídejte prosím konzistenci dat vydaných v rámci RSS položek a samotného obsahu článku (data ve zdrojovém kódu dostupném pod URL článku). Článek nejprve uložíme společně s jeho položkami z RSS. Pokud dochází k následným aktualizacím dat v článku, stahujeme obsah už ze zdrojového kódu dle priorit. Problém může např. nastat, když RSS položka pro správný náhledový obrázek použije tag media:content (viz RSS media), ale ve zdrojovém kódu bude kromě obrázku s tagem media:content také jiný další obrázek s tagem og:image (viz open graph), pak má dle priorit obrázků obrázek tagovaný og:image přednost a přepíše (načítáním aktualizovaných dat na naší straně) náhledový obrázek získaný z RSS. Tím by vzniklo nežádoucí chování z pohledu správného publikování dat. Volte ve zdrojovém kódu takové tagy, které nebudou přetěžovat prioritu tagů vydaných v RSS (pokud to není záměr).

1) Hodnoty z RSS položky

Ze standardních hodnot RSS položek načítáme hodnoty title, description, link, guid

<rss version="2.0">
  <channel>
    ...
    <item>
    <title>Nadpis článku</title>
    <description>Popis článku</description>
    <link>http://www.foo.com/bar</link>
    <guid isPermaLink="false">http://www.foo.com/article/123456</guid>
    </item>
  </channel>
</rss>

Technické parametry RSS

RSS obsahuje maximálně 20 nejnovějších článků.

Nadpis článku (headline) <title>
  • Doporučená délka textu je 50 až 60 znaků s mezerami. Delší rozsah textu může být ze strany společnosti Seznam.cz upraven a zkrácen.
  • Velká písmena doporučujeme užívat na začátku věty, pro zkratky, jména a příjmení osob atd., to vše v souladu s ustálenými pravidly gramatiky českého jazyka.
  • Zakázány jsou urážlivé pojmy, vulgarity a jiný obsah, který dehonestuje osoby či jiné subjekty.
  • Celý headline uvedený velkými písmeny není přípustný. Headline nesmí obsahovat speciální grafické znaky jako emotikony, šipky atd.
Popis článku (perex) <description>
  • Doporučená délka textu je 200 znaků s mezerami. Delší rozsah textu může být ze strany společnosti Seznam.cz upraven a zkrácen.
  • Velká písmena doporučujeme užívat na začátku věty, pro zkratky, jména a příjmení osob atd., to vše v souladu s ustálenými pravidly gramatiky českého jazyka.
  • Zakázány jsou urážlivé pojmy, vulgarity a jiný obsah, který dehonestuje osoby či jiné subjekty.
  • Perex nesmí obsahovat speciální grafické znaky jako emotikony, šipky atd.
  • Perex musí být alespoň jedna dokončená věta bez speciálních znaků.
Identifikátor článku <guid>
  • GUID = Globally Unique Identifier
  • Musí být jednoznačký identifikátor článku
  • Nesmí se měnit (např. při změně titulku článku)
  • Nemusí být platný odkaz, ale musí být nezaměnitelný s jinými servery
  • Podrobnější popis na https://validator.w3.org

2) Obrázek (obecné technické parametry)

  • Doporučená velikost náhledového obrázku je 800 × 450 pixelů. Formát obrázku je JPG nebo PNG.
  • Doporučený poměr stran obrázku je 16:9, přičemž poměr stran může být ze strany společnosti Seznam.cz přiměřeným způsobem upraven.
  • Obrázek je uveden platným internetovým odkazem (URL) odkazujícím přímo na konkrétní obrázek, prostřednictvím něhož lze obrázek automatizovaně stáhnout a upravit pro jeho zobrazování, přičemž obrázek musí být dosažitelný po celou dobu existence obsahu, jehož se obrázek týká.
  • Seznam.cz je oprávněn si pro účely Služby Seznam.cz stáhnout obrázek také přímo ze Služby Partnera.
  • Obrázek nesmí obsahovat žádné vodotisky, loga, bílé pruhy po stranách atd.

3) Obrázek (namespace szn)

<rss xmlns:szn="https://www.seznam.cz" version="2.0">
  <channel>
    ...
    <item>
      ...
      <szn:image>
        <szn:url>http://www.foo.com/bar.jpg</szn:url>
      </szn:image>
    </item>
  </channel>
</rss>

4) Obrázek (namespace media)

Tady jsou 3 možnosti zpracovávaných obrázků. První dvě přes prvek media:content, kde je obrázek načten podle MIMEtype určeného atributem type nebo je obrázek načten podle atributu medium=image. Další možností je detekce obrázku, když je obsažen prvek media:thumbnail. U všech se poté vybere atribut url. Popis obrázku je volitelný a je možné jej přidat přes tag media:description

<rss xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
  <channel>
    ...
    <item>
      ...
      <media:content type="image/jpeg" url="http://www.foo.com/bar.jpg"/>
      <media:description type="text/plain">Popis obrázku</media:description>
    </item>
    <item>
      ...
      <media:content medium="image" url="http://www.foo.com/bar.jpg"/>
      <media:description type="text/plain">Popis obrázku</media:description>
    </item>
    <item>
      ...
      <media:thumbnail url="http://www.foo.com/bar.jpg" />
      <media:description type="text/plain">Popis obrázku</media:description>
    </item>
  </channel>
</rss>

5) Obrázek z enclosure

U enclosure se bere podobně jako u media MIMEtype z atributu type

<rss xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
  <channel>
    ...
    <item>
      ...
      <enclosure type="image/jpeg" url="http://www.foo.com/bar.jpg"/>
    </item>
  </channel>
</rss>

6) GEO souřadnice (namespace geo)

<rss xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" version="2.0">
  <channel>
    ...
    <item>
      ...
      <geo:lat>49.868168</geo:lat>
      <geo:long>12.743797</geo:long>
    </item>
  </channel>
</rss>

HTML Meta u článku

Zpracovávané jsou meta tagy v hlavičce HTML stránky článku. Načtou se jen v případě, že data z RSS nebyla dodána nebo nebyla kompletní

1) Open Graph hodnoty

<!DOCTYPE html>
<html>
  <head>
    ...
    <meta property="og:title" content="Titulek článku" />
    <meta property="og:description" content="Popis článku" />
    <meta property="og:image" content="http://www.foo.com/bar/image.jpg" />
  </head>
  ...
</html>

2) Twitter hodnoty

Hodnotu pro obrázek je možno zapsat dvěma způsoby, buď hodnotou twitter:image nebo twitter:image:src

<!DOCTYPE html>
<html>
  <head>
    ...
    <meta property="twitter:title" content="Titulek článku" />
    <meta property="twitter:description" content="Popis článku" />
    <meta property="twitter:image" content="http://www.foo.com/bar/image.jpg" />
    <meta property="twitter:image:src" content="http://www.foo.com/bar/image.jpg" />
  </head>
  ...
</html>

3) Další meta hodnoty

Tyto hodnoty se použijí jen pokud nebyla nastavena již dříve

<!DOCTYPE html>
<html>
  <head>
    ...
    <meta name="title" content="Titulek článku" />
    <meta name="description" content="Popis článku" />
  </head>
  ...
</html>

4) Meta hodnoty s namespace szn

Rozšířená nastavení článku. Některá se používají pro autopublikaci

<!DOCTYPE html>
<html>
  <head>
    ...
    <meta name="szn:galleries-image-link" content="http://www.odkaz.na/json/data/pro/galerii" />
    <meta name="szn:hp-expire" content="2020-02-19T07:25:35.531Z" />
    <meta name="szn:is-family-friendly" content="false" />
    <meta name="szn:section" content="sport,atletika" />
  </head>
  ...
</html>

Popis typů:

szn:galleries-image-link
Z odkazu v tomto elementu se načtou obrázky pro články typu galerie. Očekává se typ JSON
{
  "images": [
    [
      {
        "title": "Titulek obrázku",
        "description": "Nepovinný popis obrázku",
        "wideImage": "https://www.odkaz.na/obrazek"
        "squareImage": "https://www.odkaz.na/nahledovy/obrazek",
        "imageLink": "https://www.odkaz.na/externi/stranku/s/obrazkem",
      },
      ...
    ],
    ...
  ],
  "allImagesUrl": "https://www.odkaz.na/vlastni/galerii"
}
Položka images je seznam galerií a každá z galerií je seznam obrázků. Aktuálně ale akceptuje pouze první galerii.
Položka allImagesUrl je povinná a je to odkaz na externí galerii. Použita na proklik na galerii na zdrojovém webu.
Povinnou položkou pro obrázek galerie je wideImage. Ostatní (title, description, squareImage a imageLink) jsou nepovinné a nemusí se posílat nebo mohou být null, ale title je doporučeno posílat, kvůli zobrazení popisu obrázku v náhledové galerii.
szn:hp-expire
Používá se pro nastavení expirace článku pro ve Feedu
szn:is-family-friendly
Příznak, zda má článek vhodný obsah, bez erotického obsahu. Výchozí hodnota pokud tento element není obsažen je true. Pro identifikaci dostupnosti tohoto nastavení je lepší tento element přidávat vždy i když je hodnota true
szn:section
Seznam sekcí, do kterých spadá článek. Seznam hodnot oddělených čárkami a hodnoty malými písmeny.

JSON-LD

Struktura JSON-LD musí být přítomna už při načtení HTML kódu stránky. Pokud bude dogenerovávána až javascriptem, tak se data JSON-LD nezpracují. Bližší popis k jednotlivým typů naleznete na https://schema.org/. Otestovat, jestli je vaše JSON-LD validní, můžete tímto nástrojem: https://search.google.com/structured-data/testing-tool?hl=cs

1) Stručné informace

Typ článku
Může nabývat hodnot Article, NewsArticle nebo ReportageNewsArticle. Ostatní typy se ignorují.
Štítky
Načítáme je z více hodnot a to about nebo keywords. U about se očekává objekt (minimálně s atributem name), seznam textových názvu nebo textový řetezec obsahující hodnoty oddělené čárkami, u keywords se očekává seznam textových položek nebo textový řetezec obsahující položky oddělené čárkami
Obrázek image
Tady může být jen jeden obrázek jako odkaz na obrázek, seznam odkazů na obrázky, objekt typu ImageObject nebo seznam objektů ImageObject. Pro uvedení zdroje nebo informací o původu obrázku je potřeba zadat tyto údaje do atributu creditText u objektu ImageObject
WikiData
Pokud je u položek author a nebo about nastaven atribut @id=wd:, tak se identifikuje autor na základě tohoto ID, místo vyhledání podle názvu
Autor
U autora se detekuje i typ. Může nabývat hodnot Person, Organization. Výchozí hodnota, pokud není definováno je Person
Fotogalerie
Pro detekci fotogalerie u článku se používá existence hasPart[@type="ImageGallery"], kde se očekává url odkazu na galerii a seznam obrázků image
Datum expirace hodnotami expires a sznRecommendExpires NEPOUŽÍVAT !
Tyto hodnoty jsou sice ještě načítány, ale raději je nepouživejte, protože můžou způsobit expiraci článku v Google vyhledavači nebo nevalidní JSON-LD data. Místo toho používejte hodnotu v hlavičce HTML <meta name="szn:hp-expire" ... />
Komentáře
Pro zobrazení komentářů z externích webů je potřeba zadat discussionUrl. Je to URL na kterou se přesměruje uživatel, který kliknul na komentáře u daného článku.

2) Ukázka možných hodnot

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Toto je název článku",
  "description": "Toto je perex článku",
  "image": [
    "https://example.com/photos/photo.jpg",
    {
      "@type": "ImageObject",
      "url": "https://example.com/photos/photo2.jpg",
      "caption": "Titulek obrázku",
      "description": "Popis obrázku",
      "creditText": "Zdroj obrázku nebo další informace o obrázku"
    }
  ],
  "datePublished": "2015-02-05T08:00:00+08:00",
  "dateModified": "2015-02-05T09:20:00+08:00",
  "author": {
    "@id": "wd:Q12024882", 
    "@type": "Person",
    "name": "Jindřich Šídlo",
    "url" : "https://www.seznamzpravy.cz/autor/jindrich-sidlo-54",
    "sameAs" : [
      "https://www.facebook.com/jindrich.sidlo",
      "https://twitter.com/jindrichsidlo"
    ]
  },
  "about": [
    {"name":"Fotbal", "@id": "wd:Q2736"},
    {"name":"Arsenal", "@id": "wd:Q9617"}
  ],
  "contentLocation" : {
    "@type" : "Place",
    "geo": {
      "@type": "GeoCoordinates",
      "latitude": "50.0713456",
      "longitude": "14.4008142"
    }
  }, 
  "publisher": {
    "@type": "Organization",
    "name": "Název firmy",
    "logo": {
      "@type": "ImageObject",
      "url": "https://vasedomena.com/logo.jpg"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://vas-server.cz/url-tohoto-clanku"
  },
  "isFamilyFriendly": true,
  "hasPart": {
    "@type": "ImageGallery",
    "url": "https://www.foo.com/bar/gallery/1/",
    "image": [
      {
        "@type": "ImageObject",
        "url": "https://www.foo.com/bar/gallery/1/image1.jpg",
        "caption": "Titulek obrázku",
        "description": "Popis obrázku"
      },
      ...
    ]
  },
  "discussionUrl": "https://www.foo.com/bar/comments/1/",
}
</script>

Priorita obrázků

Výchozí hlavní obrázek pro článek se načítá podle dostupnosti dat v daném pořadí. Nastavený obrázek článku ale může ovlivnit editor z redakce. Rozdíl mezi načtení z RSS a zdrojového kódu článku popisují způsoby načítání.

  1. Z položky RSS, z elementu szn:image
  2. Z položky RSS, z elementu media:content nebo media:thumbnail
  3. Z položky RSS, z elementu enclosure
  4. Z JSON-LD (ze zdrojového kódu článku), prvek image v hlavní úrovni článku
  5. Z položky (ze zdrojového kódu článku), z elementu og:image, twitter:image nebo twitter:image:src

Tlačítko „Líbí se“

Pro integraci tlačítka „Líbí se“ do webu můžete použít buďto jedno z předpřipravených řešení, nebo zvolit vlastnoruční integraci.

Předpřiravená řešení

K dispozici jsou tyto přepřipravená řešení pro snadnou integraci:

Pokud využíváte jiný systém (Drupal, Joomla, ...) nebo platformu (Vue.js, Svelte, ...) a preferovali by jste předpřipravené řešení před vlastnoruční integrací, můžete nám navrhout přidání podpory na e-mail pocitadlolibise (zavináč) firma (tečka) seznam (tečka) cz a my přidání podpory zvážíme.

Vlastnoruční integrace

Pro integraci je nutné nejdřív vložit do stránky script tlačítka (např. do <head> nebo na konec <body>):

<script src="https://pocitadlolibise.seznam.cz/pocitadlolibise.js" async></script>

Tlačítko je možné umístit do stránky vložením <seznam-pocitadlolibise> elementu na požadované místo. Tento element má povinný atribut entity, jehož hodnota by měla být kanonická URL stránky, pro kterou se mají hlasy započítávat:

<seznam-pocitadlolibise entity="https://www.vasestranky.cz/zajimavy-clanek"></seznam-pocitadlolibise>

Pozor, zajištění správné funkčnosti je nutné použít samostatnou uzavírací značku </seznam-pocitadlolibise>, není možné použít samo-zavírací značky (<seznam-pocitadlolibise entity="..."/>).

Pro další možnosti integrace viz podrobný integrační návod (aktuálně pouze v angličtině).

Ukázky:

Podmínky užití tlačítka "Líbí se"

Doplněk „Líbí se“

  1. Společnost Seznam.cz, a.s., se sídlem: Praha 5 - Smíchov, Radlická 3294/10, PSČ: 15000, IČO: 26168685, zapsaná v obchodním rejstříku vedeném Městským soudem v Praze, oddíl B, vložka 6493 (dále jen „společnost Seznam.cz“), poskytuje pro třetí strany, zejména pro provozovatele internetových stránek a on-line služeb (dále „Provozovatel“) doplňkovou službu „Líbí se“ (dále „Doplněk“), která po implementaci ze strany Provozovatele na jeho internetovou stránku či on-line službu (dále „Služba“) získává relevantní údaje o zájmu registrovaných uživatelů společnosti Seznam.cz o konkrétní typy obsahu, který je na Službě umístěn. Registrovaní uživatelé společnosti Seznam.cz mohou svůj zájem o konkrétní obsah projevit klikem na tlačítko s označením „Líbí se“.
  2. Implementací Doplňku na Službu Provozovatel souhlasí s těmito podmínkami, zavazuje se je dodržovat a současně se zavazuje dodržovat technickou specifikaci Doplňku, která je dostupná na internetové adrese (URL): https://metadata.seznam.cz/#pocitadlo-libi-se.
  3. Provozovatel, který je součástí partnerské sítě společnosti Seznam.cz, bere na vědomí, že informace získané prostřednictvím Doplňku mohou mít vliv na zobrazování obsahu Provozovatele v rámci různých služeb společnosti Seznam.cz, např. služby NewsFeed Seznam.cz.
  4. Provozovatel, který není součástí partnerské sítě společnosti Seznam.cz, implementací Doplňku na Službu souhlasí, že společnost Seznam.cz je oprávněna na svých službách zobrazovat odkaz na obsah umístěný na Službě, včetně krátkého náhledu, u něhož rozhodný počet registrovaných uživatelů společnosti Seznam.cz klikl na tlačítko s označením „Líbí se“. Rozhodný počet registrovaných uživatelů ve smyslu předchozí věty určuje společnost Seznam.cz. Společnost Seznam.cz je oprávněna na svých službách zobrazovat odkazy na obsah umístěný na Službě v podobě zobrazení jediného prvku nebo libovolné kombinace některých z následujících prvků: logo Provozovatele, název Služby, internetový odkaz (URL) na konkrétní obsah na Službě, headline obsahu na Službě, perex obsahu na Službě, ilustrační obrázek či obrázky v obsahu na Službě.
  5. Společnost Seznam.cz neposkytuje žádné záruky týkající se funkčnosti, kvality, obsahu, dostupnosti či výkonu Doplňku a neodpovídá za jakoukoliv škodu či újmu (včetně ušlého zisku či jiných nároků), která by mohla Provozovateli v souvislosti s užitím Doplňku vzniknout. Společnost Seznam.cz si vyhrazuje právo Doplněk či jakoukoliv jeho část kdykoliv změnit, zcela ukončit či zpoplatnit.
  6. Implementací Doplňku na Službu Provozovatel souhlasí s tím, že společnost Seznam.cz sbírá data o svých registrovaných uživatelích, kteří v rámci Služby kliknou na tlačítko s označením „Líbí se“. Ke sběru dat ze strany společnosti Seznam.cz dochází v souladu s platnými Zásadami zpracování osobních údajů dostupnými na internetových stránkách společnosti Seznam.cz, a to v příslušné sekci.
  7. Provozovatel bere na vědomí, že součástí kódu Doplňku je kód technického řešení Consent Management Platform certifikovaného platformou Interactive Advertising Bureau Europe (dále jen „rámec CMP“), který slouží pro sběr a správu souhlasů registrovaných uživatelů společnosti Seznam.cz se zpracováním osobních údajů.
  8. Po implementaci Doplňku na Službu a při jeho následném užívání se Provozovatel zavazuje dodržovat platné právní předpisy upravující ochranu osobních údajů a informovat své uživatele o sběru dat ze strany společnosti Seznam.cz ve smyslu těchto podmínek.

Meta data rádií

Pro předání informací o aktuálně hraných skladbách (nebo pořadech) můžete využít některý z následujících formátů. Ve všech variantách můžete vyplnit (až na uvedené výjimky povinných položek) položky podle potřeby. Pokud zvolíte variantu pluginu, musíte nám tento způsob použití (typ pluginu) oznámit, abychom data správně načítali. Pokud si nejste jistí výběrem, doporučujeme plugin songtext nebo jednu z variant přehledu dat. U varianty, která neobsahuje položky pro pořad a moderátora, můžete k tomuto účelu využít položky pro interpreta a skladbu.

Data pro rádia přístupná přes Play.cz umíme zpracovat automaticky (pokud mají data přes Play.cz vystavena) a není třeba mít výdej samostatně.

1) Plugin typu "songtext"

Informace o právě přehrávané skladbě nebo pořadu můžete vystavit formou jednoduchého řetězce na vlastním api, které je volně přístupné přes URL. Načtení pak probíhá prostřednictvím metody GET, protokolu HTTP/1.1. Z praktických důvodů uvažujeme jen prvních 150 znaků řetězce a ostatní znaky se ignorují. Interpreta (případně jméno moderátora) doporučujeme uvést velkými písmeny.

INTERPRET - Název skladby

2) Plugin typu "rozhlas"

Předávaná data načítáme podle statusu, který mají nastavený. Status je povinná položka. Časové údaje jsou dle uvedeného formátu (viz RFC 3339).

a) status quiet - nehraje aktuálně žádná skladba nebo pořad

{
  "data": {
    "status": "quiet",                    // povinná hodnota v případě, že nic nehraje
    "since": "2021-01-29T10:59:56+01:00"  // čas od kdy nic nehraje (RFC 3339)
  }
}

b) status onair - hraje aktuálně skladba nebo pořad

{
  "data": {
    "status": "onair",
    "interpret": "Interpret",
    "track": "Název skladby",
    "since": "2021-01-29T11:05:53+01:00",  // čas začátku přehrávání skladby (RFC 3339)
  }
}

3) Přehled dat

Přehled dat je třetí možnou variantou, která nemá dohodnutý žádný plugin, kterým rozlišujeme jak data zpracovat. Data mohou být strukturovaná nebo nestrukturovaná, což rozlišujeme podle nastavené hodnoty statusu. Status určuje, zda jsou data strukturovaná nebo ne. Pozor na to, že názvy některých položek dat nemusí být u obou variant stejné.

a) nestrukturovaná data
Musí být vyplněn status (neprázdný řetězec). Časové informace jsou u položek starttime nebo timestamp v podobě timestamp.

{
  "status": "ok",                      // musí být vyplněno (např. "ok")
  "title": "Název skladby",
  "artist": "Interpret",
  "album": "Album",
  "starttime": 1598439601,             // čas (timestamp) začátku přehrávání skladby
  "moderatorName": "Jméno moderátora",
  "showName": "Název pořadu",
}

b) strukturovaná data
Status vůbec neobsahují. Časové informace u položky timestamp uvádějte v podobě timestamp.

{
  "song": {
    "artist": "Interpret",
    "title": "Název skladby",
    "played_on": {
      "timestamp": 1611915950     // čas (timestamp) začátku přehrávání skladby
    }
  },
  "programme": {
    "title": "Název pořadu"
  },
  "speaker": {
    "title": "Jméno moderátora"
  }
}