Dokumentace Readivo

Kompletní průvodce integrací audio přehrávače, nastavením extrakce obsahu a použitím JavaScript API.

Readivo je SaaS služba, která automaticky převádí textový obsah webu na mluvené audio pomocí neuronových hlasů.

Rychlý start

Pro základní nasazení stačí vložit JS knihovnu a umístit přehrávač do šablony článku.

Můžete také použít oficiální plugin pro WordPress: Readivo WordPress plugin

1. Vložení knihovny

Vložte tento kód do <head> nebo těsně před uzavírací tag </body>.

<script async src="https://cdn.readivo.app/dist/loader.js"></script>

2. Vložení přehrávače

Umístěte tento tag tam, kde se má přehrávač zobrazit, například pod nadpis článku.

<readivo-player data-readivo-site="SITE_ID"></readivo-player>

SITE_ID je unikátní hash, který najdete v administraci v sekci My Sites.

Konfigurace pomocí data atributů

Chování přehrávače lze nastavit globálně v administraci nebo lokálně pomocí atributů na HTML tagu. Lokální atributy mají vždy přednost.

Atribut Typ Popis
data-readivo-site Povinný ID konfigurace webu z administrace.
data-readivo-player Volitelný ID přehrávače z administrace.
data-readivo-voice Volitelný ID hlasu, například en-US-Steffan. Přepíše nastavení z administrace.
data-readivo-sticky Volitelný 1 (zapnuto) nebo 0 (vypnuto). Určuje, zda se přehrávač při scrollování přichytí ke spodní části okna.
data-readivo-ad-url Volitelný URL pre-roll reklamy ve formátu MP3.
data-readivo-play-id Volitelný ID audio souboru pro přímé přehrání konkrétního audia.
data-readivo-custom-id Volitelný Vaše interní ID článku nebo stránky, například post-123. Audio pro toto ID se vygeneruje pouze jednou. Pokud se obsah článku změní, nová verze audia se pro dané ID nevygeneruje.
data-readivo-selector Volitelný CSS selektor pro extrakci obsahu, tedy element obsahující text článku, například .article-content. Hodí se, pokud mají články odlišnou strukturu.
data-readivo-vast-url Volitelný URL externího VAST tagu. Pokud je nastaven, Readivo načte a zpracuje VAST odpověď, vybere přehratelný audio soubor, přehraje reklamu jako pre-roll a poté pokračuje hlavním obsahem. Tento atribut má přednost před data-readivo-ad-url.
data-readivo-vast-timeout Volitelný Timeout VAST požadavku v milisekundách. Výchozí hodnota bývá obvykle 5000. Pokud dojde k timeoutu, reklama se přeskočí a spustí se hlavní obsah.
data-readivo-vast-max-wrappers Volitelný Maximální počet povolených VAST wrapperů. Výchozí hodnota bývá obvykle 5. Pokud je limit překročen, požadavek na reklamu selže a přehrávač pokračuje hlavním obsahem.
data-readivo-vast-link-text Volitelný Text odkazu pro proklik reklamy zobrazeného v titulkové části přehrávače, pokud VAST odpověď obsahuje URL ClickThrough. Příklad: Zjistit více.

Ruční předání obsahu

Pokud nechcete používat automatickou extrakci, můžete obsah předat přímo v HTML. Tím se přeskočí stahování stránky naším serverem.

AtributPopis
data-readivo-title Nadpis článku. Pokud chybí, použije se document.title.
data-readivo-content Obsah článku jako prostý text nebo Base64 kódovaný řetězec. Může obsahovat i HTML tagy.

Lokalizace textů

Všechny texty v přehrávači lze přeložit nebo upravit pomocí atributů.

<readivo-player
    data-readivo-player="..."
    data-readivo-text-init="Spustit audio"
    data-readivo-text-playing="Právě se přehrává"
    data-readivo-text-paused="Pozastaveno"
    data-readivo-text-generate="Připravuji audio..."
    data-readivo-text-finished="Dokončeno"
    data-readivo-text-error="Chyba načítání"
    data-readivo-text-ad="Reklama"
></readivo-player>

Atribut data-readivo-text-ad upravuje text zobrazený během přehrávání reklamy.

Extrakce obsahu (jak funguje)

Readivo používá jeden ze tří způsobů získání textu článku podle konfigurace vašeho webu.

Důležité: Kvalita audia závisí na kvalitě extrakce. Doporučujeme používat server-side metodu s definovaným selektorem.

1. Server-side (hlavní metoda)

Náš server navštíví URL článku, stáhne HTML a extrahuje obsah článku.

2. Client-side

Pokud server-side extrakce selže, například protože web vyžaduje přihlášení nebo blokuje boty, a máte v administraci povolenou Client-side extraction, pokusí se přehrávač získat text přímo v prohlížeči návštěvníka pomocí JavaScriptu.

3. Přímé předání obsahu (ručně)

Pokud v HTML nastavíte atribut data-readivo-content, automatická extrakce se přeskočí a použije se tento obsah.

Selektory a čištění obsahu

V administraci v detailu webu můžete nastavit pravidla parsování.

Hlavní element (Content Selector)

CSS selektor, který obaluje hlavní text. Například article, .post-body, .content. Pokud není vyplněn, Readivo se pokusí obsah rozpoznat automaticky.

Vyloučené elementy (Excluded Selectors)

Elementy uvnitř obsahu, které se mají ignorovat a odstranit před čtením. Zadávají se jako seznam CSS selektorů.

Příklady, co vyloučit:

Minimální délka (Threshold)

Pokud je extrahovaný text kratší než tento limit, audio se nevygeneruje.

Fakturace a kredity

Jak počítáme spotřebované kredity?

JavaScript API

Přehrávač lze ovládat programově.

Získání instance

const readivo = document.querySelector('readivo-player');

// Nejlepší je použít událost 'readivo:ready'
document.addEventListener('readivo:ready', () => {
    readivo.play();
});

Metody

MetodaPopis
readivo.play()Spustí přehrávání, případně nejprve přehraje reklamu.
readivo.pause()Pozastaví přehrávání.
readivo.togglePlay()Přepíná mezi přehráním a pauzou.
readivo.seek(seconds)Přesune přehrávání na konkrétní čas v sekundách.
readivo.seekBy(delta)Posune přehrávání o delta sekund, například -5.

Vlastnosti

Čtení aktuálního stavu přehrávače pouze pro čtení.

Vlastnost Typ Popis
readivo.duration number Celková délka audia v sekundách, nebo 0 pokud ještě není načtené.
readivo.currentTime number Aktuální pozice přehrávání v sekundách.
readivo.paused boolean true, pokud je přehrávání pozastavené nebo zastavené.
readivo.isPlaying boolean true, pokud se audio právě přehrává.

Události

Přehrávač dispatchuje CustomEvent události, které bubbleují. Můžete je poslouchat přímo na elementu nebo na document.

Seznam událostí

Název událostiData v event.detailPopis
readivo:ready{}Přehrávač byl inicializován.
readivo:loading{}Začalo generování nebo stahování.
readivo:loaded{ duration: 120.5 }Audio je připravené.
readivo:play{}Začalo přehrávání obsahu.
readivo:pause{}Přehrávání bylo pozastaveno.
readivo:ended{}Přehrávání skončilo.
readivo:error{ message: "..." }Došlo k chybě.
readivo:ad-start{}Začal reklamní režim. U VAST reklam se tracking jako impression a start odesílá až ve chvíli, kdy se reklamní media skutečně začnou přehrávat.
readivo:ad-end{}Reklama skončila nebo byla po chybě přeskočena.

Příklad: Google Analytics 4

document.addEventListener('readivo:play', (e) => {
    gtag('event', 'audio_play', {
        'event_category': 'Readivo',
        'event_label': window.location.pathname
    });
});

Audio reklamy

Readivo podporuje pre-roll audio reklamy. Reklama se vždy přehraje před hlavním obsahem.

Podporované režimy reklam

Vlastnosti reklam

Příklad přímého URL audia

Přidejte atribut data-readivo-ad-url.

<readivo-player
    data-readivo-player="..."
    data-readivo-ad-url="https://example.com/promo.mp3"
></readivo-player>
Upozornění: URL musí směřovat přímo na přehratelný audio soubor, například MP3.

VAST reklamy

Readivo podporuje externí VAST pre-roll reklamy. Místo přímého odkazu na audio soubor zadáte URL VAST tagu a přehrávač automaticky zpracuje celý reklamní workflow.

Jak VAST v Readivo funguje

Pokud je přítomen atribut data-readivo-vast-url, Readivo neočekává přímý MP3 soubor. Místo toho si od reklamního serveru vyžádá VAST XML dokument.

Přehrávač poté provede následující kroky:

Chování při chybách

Pokud selže VAST požadavek, XML je neplatné, není nalezen podporovaný audio soubor nebo reklamní audio nelze přehrát, Readivo odešle odpovídající VAST error tracker, pokud je k dispozici, a reklamu přeskočí.

V takových případech platí:

Základní příklad VAST

<readivo-player
    data-readivo-site="SITE_ID"
    data-readivo-vast-url="https://ads.example.com/vast?pv={PV_ID}&url={PAGE_URL}&cb={CACHEBUSTER}"
></readivo-player>

VAST příklad s plnou konfigurací

<readivo-player
    data-readivo-site="SITE_ID"
    data-readivo-vast-url="https://ads.example.com/vast?pv={PV_ID}&url={PAGE_URL}&article={ARTICLE_ID}&cb={CACHEBUSTER}"
    data-readivo-vast-timeout="5000"
    data-readivo-vast-max-wrappers="5"
    data-readivo-vast-link-text="Zjistit více"
    data-readivo-text-ad="Reklama"
></readivo-player>

Podporovaná makra v data-readivo-vast-url

Makro Popis
{PV_ID} Unikátní identifikátor pageview, který se vygeneruje jednou při načtení stránky a znovu se používá pro všechny reklamní requesty na dané stránce.
{PAGE_URL} Aktuální URL stránky, URL encoded.
{REFERRER} Aktuální referrer dokumentu, URL encoded.
{ARTICLE_ID} Identifikátor aktuálního článku, pokud je k dispozici.
{PLAYER_ID} Identifikátor aktuální instance přehrávače Readivo.
{CACHEBUSTER} Náhodná hodnota pro obejití cache.
[CACHEBUSTING] IAB styl makra pro cache busting podporovaný ve VAST URL a tracking URL.
[TIMESTAMP] IAB styl makra pro timestamp podporovaný ve VAST URL a tracking URL.

ClickThrough a ClickTracking

Pokud VAST odpověď obsahuje URL ClickThrough, může Readivo zobrazit klikací odkaz přímo v titulkové části přehrávače. Když uživatel na odkaz klikne, přehrávač otevře cílovou URL a zároveň odešle všechny související ClickTracking URL.

Text odkazu se řídí pomocí data-readivo-vast-link-text. Pokud ve VAST odpovědi není přítomen ClickThrough, žádný odkaz se nezobrazí.

Poznámky k VAST

Důležité: VAST URL nevrací přímo audio soubor. Vrací VAST XML odpověď, která přehrávači říká, jaký media soubor má přehrát a které tracking URL má zavolat.