Audio Native na dużym portalu – firewall, archiwum i Next.js

Jeden snippet na blogu, osobny projekt na portalu

W poradniku o Audio Native na WordPressie opisaliśmy wdrożenie, które zamyka się w kwadransie: jeden snippet, plugin, gotowe. Ten tekst jest jego drugą częścią – dla serwisów, na których kwadrans zamienia się w kilka tygodni.

Duży portal wydawniczy różni się od małego bloga w trzech miejscach naraz: frontend to zwykle aplikacja (Next.js, React), archiwum liczy tysiące tekstów i żyje własnym ruchem, a domenę chroni firewall z detekcją botów. Każda z tych rzeczy potrafi wywrócić wdrożenie w innym momencie – i żadnej z nich nie opisuje dokumentacja.

Krótkie przypomnienie mechaniki, bo na niej opiera się połowa tego tekstu: Audio Native to osadzany player, który generuje wersję lektorską artykułu przy pierwszej wizycie czytelnika na stronie – nie przy kliknięciu play. Gotowe nagranie trafia do cache na CDN i kolejne wizyty dostają je od razu, bez ponownych kosztów.

Poniżej problemy w kolejności, w jakiej zwykle się pojawiają – i co z nimi zrobić.

Co zrobić, gdy player w ogóle nie startuje

Na WordPressie surowy snippet (div + <script>) po prostu działa. W aplikacji React – nie, bo React nie wykonuje tagów <script> wstawianych w trakcie renderowania komponentów. Player zostaje w fallbacku, konwersja nigdy nie rusza, a w konsoli nie ma nic, co by to wprost powiedziało.

Rozwiązanie jest udokumentowane, choć łatwo je przegapić: dedykowany komponent, który w useEffect dokłada skrypt helpera do body dynamicznie. Wzorzec znajdziesz w oficjalnym przewodniku ElevenLabs dla Reacta – u nas zadziałał bez modyfikacji.

Dwie rady na etap testów:

• Allowlista przyjmuje pojedyncze adresy. Zanim odblokujesz całą domenę, możesz dopisywać artykuły stagingowe jeden po drugim i testować na zamkniętym środowisku. Produkcję warto włączać dopiero wtedy, gdy markup i selektory są dopięte.
• Zanim zaczniesz debugować kod, sprawdź własną przeglądarkę. Blokery treści (np. Privacy Badger) wycinają skrypt helpera i player zostaje w fallbacku tylko u ciebie. Czysta przeglądarka albo tryb incognito rozstrzyga to w minutę.

Co zrobić, gdy lektor czyta to, czego nie powinien

Tryb automatyczny radzi sobie zaskakująco przyzwoicie: na typowym artykule pomija nawigację, lead i stopkę. Ale „zaskakująco przyzwoicie” to za mało, gdy między akapitami eseju lektor nagle czyta dane wydawnicze książki albo biogram autora.

Panel Audio Native ma dwa pola selektorów CSS: selektory treści (co czytać) i zablokowane (co pomijać). Kilka lekcji z praktyki:

• Unikaj selektorów dziecka (>). Zapis #content > p przestaje łapać cokolwiek, gdy w strukturze pojawi się dodatkowy wrapper – a pojawi się, wystarczy drobny redesign. Selektor potomny (#content p) przeżywa takie zmiany. Co ważne, awaria jest cicha: nic nie zgłasza błędu, parser po prostu wraca do trybu automatycznego.
• Boksy z metadanymi wykluczaj jawnie. Dane książki przy recenzji, biogramy, podpisy – wszystko, co jest tekstem w akapitach, ale nie jest treścią artykułu, powinno trafić do zablokowanych selektorów. Na WordPressie sprawdzał się semantyczny <figcaption>; na customowym CMS-ie trzeba wskazać klasy ręcznie.
• Tytuł i autor: schema.org zamiast og:title. Tagi @title i @author w czołówce nagrania biorą dane ze strony, a og:title na portalach bywa zaśmiecony („Tytuł | Dział | Nazwa serwisu”). W naszych testach porównawczych parser preferuje dane z JSON-LD schema.org – czyste headline i author.name dają czystą czołówkę. Jeśli serwis nie ma schema.org na artykułach, warto je dodać przy okazji: skorzysta i audio, i SEO.
• Czołówka i tyłówka („[Nazwa serwisu] przedstawia…”, „Dziękujemy za wysłuchanie…”) to pole „Treść niestandardowa” w panelu – działa globalnie dla wszystkich artykułów. Obsługuje pauzy <break time="1.0s" />, przy czym w naszych próbach cisza powyżej ok. 1,5 s i tak jest przycinana przez model. Dłuższej pauzy nie wymusisz, krótszą – tak.

Co zrobić, gdy w audio brakuje fragmentów tekstu

Ten problem jest podstępny, bo nagranie brzmi dobrze. Dopiero uważny odsłuch obok tekstu pokazuje, że z niektórych artykułów wypadają całe fragmenty.

U nas przyczyną był markup: część tekstów miała akapity rozdzielane podwójnym <br><br> wewnątrz jednego bloku, zamiast osobnych znaczników <p>. Parser Audio Native gubił pierwszy segment każdej takiej sklejki – bez błędu, bez ostrzeżenia.

Rozwiązania, od najczystszego:

1. Poprawny markup na renderze: każdy akapit jako osobne <p>, odstępy CSS-em. Jednorazowa zmiana w warstwie szablonu, korzysta na niej też dostępność i SEO.
2. Gdy zmiana renderu jest kosztowna: transformacja, która skleja segmenty niewidocznym znakiem łączącym (word joiner, U+2060). Parser widzi wtedy jeden ciągły akapit i czyta wszystko, a układ strony nie zmienia się ani o piksel.

Obie drogi mają wspólny mianownik: bez odsłuchu i porównania z tekstem nie dowiesz się, że problem istnieje. O metodzie weryfikacji – na końcu.

Co zrobić, gdy nowe teksty nagle przestają dostawać audio

Scenariusz z gatunku „przecież nic nie zmienialiśmy”: wdrożenie działa od tygodni, aż któregoś dnia nowe artykuły utykają na „Converting the page to audio” i nigdy nie kończą. Starsze nagrania grają normalnie – bo gotowe pliki są serwowane z CDN ElevenLabs, nie z twojej strony.

Kluczowa jest tu anatomia konwersji: stronę artykułu pobiera serwer ElevenLabs, nie przeglądarka czytelnika. To pobranie przechodzi przez firewall twojej domeny. Platformy hostingowe i CDN-y (Vercel, Cloudflare i inne) potrafią automatycznie włączyć ochronę przed botami przy wykryciu wzmożonego ruchu – challenge JavaScript, który przeglądarka rozwiązuje niezauważalnie, a serwerowy scraper nie. Od tej chwili ElevenLabs nie widzi treści i zwraca ogólnikowe „unable to convert the url”.

Kolejność diagnozy, która oszczędza godziny błądzenia:

1. Wyklucz silnik i kredyty. API pozwala stworzyć projekt Audio Native z pliku HTML zamiast z adresu – to omija pobieranie strony. Jeśli konwersja z pliku działa, silnik i rozliczenia są w porządku, a problem leży w fetchu.
2. Odtwórz wywołanie playera. Widget uruchamia konwersję publicznym żądaniem convert – znajdziesz je w devtools, w zakładce Network, przy pierwszej wizycie na artykule. Jeśli to samo żądanie pada dla świeżego adresu, problem nie leży po stronie twojej przeglądarki.
3. Obejrzyj nagłówki własnej strony pobranej bez przeglądarki, z czystego adresu IP. Challenge zostawia w odpowiedzi charakterystyczne nagłówki mitygacji – to one są dowodem, nie ogólny komunikat błędu.

Naprawa: wyjątek w firewallu dla stałych adresów egress ElevenLabs. Lista jest oficjalnie opublikowana w dokumentacji (sekcja o statycznych IP – te same adresy obsługują wszystkie usługi ElevenLabs). Dopasowanie po User-Agencie nie zadziała: challenge jest JavaScriptowy, UA scrapera nie jest publicznie skatalogowany, a ElevenLabs nie figuruje na listach „zweryfikowanych botów” przepuszczanych automatycznie. Najpewniejsze trafienie dają logi firewalla – widać w nich dokładnie, które żądania zostały zablokowane i skąd przyszły.

Co zrobić, gdy archiwum zjada miesięczny budżet w jedno popołudnie

Mechanika „generuj przy pierwszej wizycie” na małym blogu jest zaletą: płacisz tylko za to, co ktoś naprawdę czyta. Na portalu z kilkunastoletnim archiwum ta sama mechanika staje się pułapką – bo pierwszą wizytę składa także robot indeksujący, agregator i czytelnik z długiego ogona wyszukiwarki.

Skala potrafi zaskoczyć: żywe archiwum to setki unikalnych starych adresów odwiedzanych każdej doby. Przy dłuższych formach (8–15 tys. znaków na tekst) miesięczna pula znaków planu potrafi zniknąć w kilka–kilkanaście godzin, a licznik overage bije dalej.

Co z tym zrobić – w kolejności od bezpiecznika do rozwiązania:

• Ustaw limit wydatków w rozliczeniu usage-based. To bezpiecznik na rachunek, nie rozwiązanie: chroni budżet, ale gdy się wyczerpie, nowe teksty też zostają bez audio. Uwaga praktyczna: licznik zużycia w panelu bywa opóźniony i doliczany partiami – nie diagnozuj stanu kredytów z samej tej liczby.
• Filtr „audio tylko dla tekstów od daty X” musi mieszkać w serwisie. Allowlista ElevenLabs go nie zrobi: przyjmuje wyłącznie konkretne adresy albo całe domeny – bez masek, zakresów czy dat (sprawdziliśmy w dokumentacji i na żywym API). Skuteczny filtr to warunkowe osadzanie playera w szablonie artykułu według daty publikacji. Zasada jest żelazna: konwersję uruchamia wyłącznie osadzony widget, więc brak playera na stronie to gwarantowane zero kosztu.
• Już wygenerowanych nagrań nie trzeba poświęcać. Odtwarzanie gotowego audio nie zużywa kredytów, a ponowna wizyta niczego nie regeneruje – plik po prostu gra z CDN. Listę skonwertowanych adresów można wyciągnąć z API i dołączyć do warunku w szablonie („data od X lub adres z listy”). Nic nie przepada.
• Dobra wiadomość na koniec: na stronach, gdzie konwersja jest niemożliwa lub niedozwolona, player chowa się sam (iframe dostaje wysokość zero). Czytelnik nie ogląda zepsutego widgetu – strona wygląda, jakby playera nigdy tam nie było.

Jak sprawdzać, żeby nie zgadywać

Najważniejsza lekcja z tego wdrożenia nie dotyczy żadnego pojedynczego błędu, tylko metody pracy:

• DOM to nie audio. To, że fragment jest w HTML, nie znaczy, że zostanie przeczytany – i odwrotnie. Każdą zmianę selektorów czy markupu weryfikuj na realnym nagraniu: pobierz MP3, przepuść przez speech-to-text i porównaj z tekstem źródłowym. Dopiero transkrypcja pokazuje, co naprawdę weszło do nagrania, co wypadło i czy wykluczenia działają.
• Rozdzielaj warstwy. „Audio się wygenerowało” (API, CDN) i „player renderuje się czytelnikowi” (przeglądarka) to dwa osobne światy. Pierwszy psują firewall i kredyty, drugi – blokery treści. Mieszanie tych warstw w diagnozie kosztuje najwięcej czasu.
• Jeden czysty test zamiast dwudziestu nerwowych. Intensywne odpytywanie własnej strony i API potrafi samo wywołać limity i zaciemnić obraz. Świeży stan, jedna zmiana, jeden pomiar.
• Liczby zamiast wrażeń. Ile tekstów miesięcznie, ile znaków na tekst, ilu unikalnych adresów dotyka ruch w archiwum, co kosztuje każda opcja – dopiero na takich danych da się sensownie zdecydować, czy audio ma dostać całe archiwum, czy tylko nowe publikacje.

Checklista przed startem na dużym serwisie

1. Frontend na React/Next.js – dedykowany komponent zamiast surowego snippetu.
2. Markup artykułów – prawdziwe znaczniki <p>, semantyczne podpisy, boksy poboczne w osobnych klasach.
3. Metadane – schema.org JSON-LD z headline i author.name.
4. Selektory treści i wykluczenia – dobrane do struktury i zweryfikowane odsłuchem, nie inspekcją HTML.
5. Firewall – wyjątek dla adresów egress ElevenLabs przed startem, nie po pierwszej awarii.
6. Polityka archiwum – warunek na datę publikacji w szablonie plus limit wydatków jako bezpiecznik.
7. Weryfikacja – MP3 + speech-to-text po każdej istotnej zmianie.
8. Monitoring pierwszych tygodni – zużycie znaków i to, czy nowe teksty faktycznie dostają audio.

Audio Native pozostaje najkrótszą drogą do wersji lektorskiej artykułów – również na dużym serwisie. Różnica polega na tym, że na dużym serwisie trzeba wiedzieć, gdzie ta droga skręca.

Planujesz player audio na większym serwisie? Pomożemy przejść tę listę od góry do dołu – z firewallem i archiwum włącznie. Sprawdź naszą ofertę wdrożeń →