DF Audio Product: odsłuch audio kart produktu

Wprowadzenie

DF Audio Product dodaje odtwarzacz audio na każdej karcie produktu w sklepie PrestaShop. Jedno kliknięcie w „Odsłuchaj opis” i nazwa produktu, opis krótki oraz opis długi są czytane na głos, z prędkością wybraną przez odwiedzającego.

Moduł współpracuje z czterema silnikami syntezy mowy: silnikiem przeglądarki (bezpłatny, bez klucza API) oraz trzema silnikami serwerowymi klasy premium (OpenAI, Google Cloud, ElevenLabs), których pliki MP3 są zapisywane w pamięci podręcznej, aby kontrolować koszty.

Wymagania

• PrestaShop 8.0 do 9.x
• PHP 8.0 lub nowszy
• Włączone rozszerzenie cURL (tylko dla silników serwerowych)
• Katalog var/ z prawem zapisu dla PHP (tylko dla silników serwerowych)
• Brak zależności Composera

Instalacja

1. W panelu administracyjnym przejdź do Moduły > Menedżer modułów.
2. Kliknij Wgraj moduł i wskaż plik dfaudioproduct-1.0.0.zip.
3. Po zakończeniu instalacji kliknij Konfiguruj.

Podczas instalacji moduł automatycznie tworzy tabelę pamięci podręcznej, zakładkę administracyjną w sekcji Katalog, katalog pamięci podręcznej var/dfaudioproduct/ zabezpieczony plikiem .htaccess oraz rejestruje się na potrzebnych hookach.

Wybór silnika syntezy mowy

Silnik przeglądarki (Web Speech API)

To silnik domyślny. Głos jest syntezowany bezpośrednio na urządzeniu odwiedzającego przez jego przeglądarkę (Chrome, Edge, Safari, Firefox). Bez klucza API, bez kosztów, bez wysyłania danych do usług zewnętrznych i bez plików przechowywanych na Twoim serwerze.

Moduł przekazuje tekst karty do przeglądarki, która automatycznie dobiera głos odpowiadający językowi odwiedzającego. Jakość i dostępny zestaw głosów zależą więc od systemu operacyjnego odwiedzającego: bardzo dobre na macOS i iOS, poprawne na Windows i Androidzie.

OpenAI TTS

Naturalne głosy wysokiej jakości. Podaj swój klucz API OpenAI, wybierz model (tts-1 dla szybkości, tts-1-hd dla maksymalnej jakości, gpt-4o-mini-tts dla najlepszego kompromisu) oraz głos spośród: alloy, echo, fable, onyx, nova, shimmer. Jeśli pole Głos pozostanie puste, używany jest alloy.

Google Cloud Text-to-Speech

Podaj klucz API Google Cloud z włączonym API Text-to-Speech. Pole Głos jest opcjonalne: zostaw je puste, a moduł automatycznie wywnioskuje kod języka z języka odwiedzającego (fr-FR, en-US, es-ES, de-DE, it-IT). Aby wymusić konkretny głos, wpisz jego pełną nazwę, na przykład fr-FR-Neural2-A. Kod języka jest wtedy odczytywany z nazwy głosu.

ElevenLabs

Podaj swój klucz API ElevenLabs oraz obowiązkowo identyfikator głosu (Voice ID) w polu Głos. Znajdziesz go w swojej bibliotece głosów ElevenLabs. Moduł korzysta z modelu wielojęzycznego eleven_multilingual_v2, który natywnie obsługuje pięć języków.

Konfiguracja

Włącz

Przełącznik globalny. Po wyłączeniu odtwarzacz znika z kart produktu, a kontroler generowania audio przestaje odpowiadać.

Domyślna prędkość odtwarzania

Prędkość stosowana przy pierwszym wczytaniu strony: 0,75×, 1×, 1,25×, 1,5× lub 2×. Odwiedzający może potem przełączać się między tymi wartościami przyciskiem prędkości w odtwarzaczu.

Maksymalna liczba znaków

Maksymalna długość czytanego tekstu, od 200 do 20 000 znaków (domyślnie 3 000). Tekst jest ucinany czysto, na końcu ostatniego pełnego zdania. To ustawienie wprost wpływa na koszt silników serwerowych rozliczanych za znak: niska wartość zmniejsza rachunek, wysoka odczytuje całość opisów.

Czytaj opis krótki i opis długi

Dwa niezależne przełączniki. Nazwa produktu jest zawsze czytana jako pierwsza. Możesz czytać wyłącznie opis krótki (szybko, oszczędnie) albo całość.

Pozycja wyświetlania

• Pod blokiem zakupu (hook displayProductAdditionalInfo): pozycja zalecana, dobrze widoczna pod ceną i przyciskiem dodania do koszyka.
• W akcjach produktu (hook displayProductActions): mocniej zintegrowana z przyciskami motywu.

Moduł jest zarejestrowany na obu hookach, ale wyświetla odtwarzacz tylko na wybranym: zmiana pozycji nie wymaga żadnych operacji w pozycjonowaniu modułów.

Czas życia pamięci podręcznej (dni)

Wartość 0 oznacza, że pliki audio nigdy nie wygasają (zalecane). Wyższa wartość powoduje automatyczne usuwanie plików wygenerowanych wcześniej niż N dni temu, przy kolejnym generowaniu. Przydatne, jeśli regularnie zmieniasz głos lub silnik.

Jak działa pamięć podręczna

Pamięć podręczna dotyczy wyłącznie silników serwerowych; silnik przeglądarki nie generuje żadnych plików.

1. Odwiedzający po raz pierwszy klika „Odsłuchaj opis”.
2. Moduł pobiera tekst karty po stronie serwera, czyści go z HTML i skraca zgodnie z Twoim limitem znaków.
3. Wylicza unikalny odcisk na podstawie silnika, modelu, głosu, języka, sklepu i samego tekstu.
4. Jeśli żaden plik nie pasuje, wywołuje API silnika, odbiera plik MP3 i zapisuje go w var/dfaudioproduct/.
5. Plik jest serwowany z nagłówkiem ETag i Cache-Control na jeden dzień. Kolejni odwiedzający dostają plik z pamięci podręcznej, a przeładowania strony zwracają odpowiedź 304 bez ponownego przesyłania audio.

Ważna konsekwencja: płacisz najwyżej za jedno wygenerowanie na produkt i na język, a nie za jedno na wizytę. Twój koszt zależy od wielkości katalogu, nigdy od ruchu.

Prędkość odtwarzania nie wchodzi w skład odcisku: stosuje ją przeglądarka na istniejącym pliku. Jeden plik MP3 obsługuje więc wszystkie pięć prędkości.

Automatyczne unieważnianie

Pamięć podręczna audio danego produktu jest czyszczona automatycznie, we wszystkich językach i wszystkich sklepach, gdy tylko produkt zostanie zmodyfikowany lub usunięty, przez hooki actionObjectProductUpdateAfter i actionObjectProductDeleteAfter. Nowe audio powstaje przy kolejnym odsłuchu, z aktualną treścią. Po poprawieniu opisu nie trzeba nic robić ręcznie.

Lokalizacja plików

Pliki MP3 są przechowywane w var/dfaudioproduct/, w katalogu głównym PrestaShop, celowo poza katalogiem modułu: aktualizacja modułu nie niszczy więc pamięci podręcznej. Katalog jest zabezpieczony plikiem .htaccess oraz index.php, a pliki są dostępne wyłącznie przez kontroler modułu, nigdy bezpośrednio.

Zarządzanie pamięcią podręczną w panelu

Strona konfiguracji wyświetla u góry panel statystyk: liczbę plików w pamięci podręcznej, zajętą przestrzeń dyskową i łączną liczbę odtworzeń.

Przycisk Przeglądaj pliki w pamięci podręcznej otwiera zakładkę Katalog > DF Audio Product, która wymienia każdy plik z identyfikatorem produktu, jego nazwą, językiem, silnikiem, głosem, rozmiarem, liczbą odtworzeń i datą wygenerowania. Możesz usunąć pojedynczy plik, zaznaczone pliki lub wyczyścić wszystko przyciskiem Wyczyść wszystko na pasku narzędzi.

Przycisk Wyczyść pamięć podręczną audio na stronie konfiguracji działa tak samo: usuwa pliki z dysku i opróżnia tabelę. Nagrania zostaną po prostu wygenerowane ponownie na żądanie.

Odtwarzacz po stronie sklepu

Odtwarzacz składa się z przycisku „Odsłuchaj opis”, paska postępu, licznika czasu i przycisku prędkości.

• Silniki serwerowe: pasek postępu jest klikalny i pozwala przewijać nagranie, a licznik pokazuje czas, który upłynął, oraz czas całkowity.
• Silnik przeglądarki: pasek postępu jest orientacyjny (przesuwa się słowo po słowie), a licznik jest ukryty, ponieważ Web Speech API nie podaje długości nagrania.

Zmiana prędkości w trakcie odtwarzania jest obsługiwana w obu przypadkach. Przy silniku przeglądarki synteza nie może zmienić prędkości w locie, więc moduł uruchamia ją po cichu ponownie od ostatniego wypowiedzianego słowa, a wznowienie jest niezauważalne. Mechanizm podtrzymania obchodzi także przerywanie długich syntez po kilkunastu sekundach w przeglądarkach opartych na Chromium.

Odtwarzacz resetuje się automatycznie przy zmianie wariantu przez AJAX, nasłuchując zdarzenia updatedProduct motywu.

Dostępność

Odtwarzacz został zaprojektowany tak, aby mógł z niego korzystać każdy, w duchu europejskiej dyrektywy o dostępności (European Accessibility Act):

• Przycisk odtwarzania ze stanem aria-pressed odzwierciedlającym trwające odtwarzanie
• Obszar komunikatów aria-live sygnalizujący czytnikom ekranu wczytywanie, odtwarzanie lub błąd
• Pełna obsługa i aktywacja z klawiatury, z widocznym pierścieniem fokusu
• Pasek postępu z etykietą, obsługiwany z klawiatury
• Poszanowanie systemowej preferencji prefers-reduced-motion (spowolnienie animacji wczytywania)
• Duże obszary dotykowe i układ dopasowany do małych ekranów

Odsłuch treści produktowej jest konkretną odpowiedzią na wymagania dostępności. Ogólna zgodność Twojego sklepu zależy jednak od wszystkich stron: motywu, procesu zakupowego i treści redakcyjnych.

Wielojęzyczność i multistore

Tekst jest pobierany w języku odwiedzającego, więc każdy język generuje własny plik audio, z dopasowanym głosem. W trybie multistore pamięć podręczna jest dodatkowo rozdzielona per sklep, co pozwala na różne opisy w poszczególnych sklepach.

Etykiety interfejsu odtwarzacza („Odsłuchaj opis”, „Pauza”, „Wznów”, „Wczytywanie”) są tłumaczalne w sekcji Międzynarodowe > Tłumaczenia > Tłumaczenia modułów.

Personalizacja stylu

Odtwarzacz korzysta ze zmiennych CSS, które możesz nadpisać w arkuszu stylów motywu potomnego, bez modyfikowania modułu:

.dfap-player {
  --dfap-accent: #2b6cb0;
  --dfap-accent-hover: #1f4f85;
  --dfap-muted: #718096;
  --dfap-bg: #ffffff;
}

Przydatne klasy to .dfap-player (kontener), .dfap-play (przycisk główny), .dfap-progress (pasek), .dfap-speed (przycisk prędkości) oraz stan .dfap-is-playing.

Koszty i dobre praktyki

• Zacznij od silnika przeglądarki. Jest bezpłatny i pozwala sprawdzić zainteresowanie funkcją wśród Twoich odbiorców przed jakąkolwiek inwestycją.
• Dostosuj limit znaków. Zejście z 3 000 do 1 200 znaków dzieli rachunek za API na pół i w większości opisów w zupełności wystarcza.
• Czytaj tylko opis krótki, jeśli Twoje opisy długie są bardzo gęste lub zawierają tabele techniczne słabo nadające się do odsłuchu.
• Rozgrzej pamięć podręczną, odwiedzając swoje bestsellery po zmianie silnika: pierwsi odwiedzający nie będą wtedy czekać na generowanie.

Rozwiązywanie problemów

Odtwarzacz się nie wyświetla

Sprawdź, czy moduł jest włączony w konfiguracji, czy pozycja wyświetlania odpowiada hookowi obecnemu w Twoim motywie i czy karta zawiera co najmniej dwadzieścia znaków czytelnego tekstu. Następnie wyczyść pamięć podręczną PrestaShop.

Przycisk zwraca błąd po kliknięciu (silniki serwerowe)

Użyj przycisku Testuj połączenie API: pokazuje dokładny komunikat błędu zwrócony przez dostawcę. Najczęstsze przyczyny to nieprawidłowy lub wygasły klucz API, przekroczony limit, nieistniejący głos (zwłaszcza błędny Voice ID w ElevenLabs) lub wyłączone rozszerzenie cURL. Błędy są też zapisywane w Parametry zaawansowane > Dzienniki, z przedrostkiem dfaudioproduct.

Nic się nie dzieje przy silniku przeglądarki

Niektóre przeglądarki wymagają interakcji użytkownika przed uruchomieniem syntezy mowy, co jest tu spełnione, bo odtwarzanie startuje po kliknięciu. Sprawdź następnie, czy w systemie odwiedzającego zainstalowany jest głos dla danego języka. Na komputerze z Windows bez polskiego pakietu głosowego przeglądarka może nie mieć dostępnego żadnego głosu; moduł przełącza się wtedy na pierwszy zgodny głos albo pozostaje cichy. Web Speech API wymaga też połączenia HTTPS w większości przeglądarek.

Błąd zapisu pamięci podręcznej

Katalog var/dfaudioproduct/ musi być zapisywalny przez użytkownika PHP. Sprawdź uprawnienia katalogu var/ oraz dostępne miejsce na dysku.

Audio nie aktualizuje się po zmianie produktu

Unieważnianie jest automatyczne. Jeśli stare nagranie się utrzymuje, chodzi o pamięć podręczną przeglądarki odwiedzającego: ponieważ plik jest serwowany z Cache-Control na jeden dzień, wymuszone przeładowanie (Ctrl+F5) rozwiązuje sprawę. Nowy ETag zastępuje potem stary dla wszystkich.

Odinstalowanie

Odinstalowanie usuwa tabelę pamięci podręcznej, zakładkę administracyjną, wszystkie ustawienia oraz wszystkie wygenerowane pliki MP3, wraz z katalogiem var/dfaudioproduct/. Na serwerze nie pozostają żadne resztki.

Wsparcie

Masz pytanie, znalazłeś błąd lub chcesz zgłosić rozwinięcie funkcji? Skontaktuj się z zespołem DataFirefly przez stronę wsparcia. Podaj wersję PrestaShop, wersję PHP, używany silnik oraz, jeśli to możliwe, treść dziennika błędów.