Dokumentace pluginu Toret Ads for AI

Nacházíte se na stránkách dokumentace WooCommerce pluginu Ads for AI. Plugin zakoupíte zde: Toret Ads for AI pro WooCommerce.

Co plugin umí

Plugin propojí váš WooCommerce e-shop s reklamním systémem ChatGPT Ads od OpenAI. Skládá se ze tří samostatných částí, které můžete používat společně i jednotlivě:

1. Produktový feed – plugin automaticky generuje soubor s produkty ve formátu, který vyžaduje Ads Manager, a vystavuje ho na tajné adrese. Tu stačí vložit do Ads Manageru.
2. OpenAI Pixel – měřicí kód na webu, který zaznamenává nákupní chování návštěvníků (zobrazení produktu, přidání do košíku, zahájení pokladny, nákup).
3. Conversions API – odesílání dokončených objednávek přímo ze serveru. Konverze se tak změří i tehdy, když návštěvník používá blokátor reklam nebo nezobrazí děkovnou stránku.

Pixel i Conversions API posílají objednávku se stejným ID události, takže OpenAI duplicitní konverze automaticky sloučí a žádná objednávka se nezapočítá dvakrát.

⚠️ Reklamní účet, schválení feedu, kampaně a další nastavení v Ads Manageru spravujete přímo u OpenAI. Plugin zajišťuje propojení e-shopu s Ads Managerem, samotný reklamní účet ani kampaně nezakládá.

Minimální požadavky

• WordPress 6.0 nebo vyšší
• WooCommerce 9.2 nebo vyšší
• PHP 8.1 nebo vyšší
• MySQL 5.0 nebo vyšší
• Účet v ChatGPT Ads (Ads Manager) od OpenAI

Plugin je kompatibilní s ukládáním objednávek HPOS (High-Performance Order Storage) i s blokovou pokladnou WooCommerce.

Instalace pluginu

1. V administraci WordPressu přejděte na Pluginy → Instalace pluginů → Nahrát plugin.
2. Vyberte stažený ZIP soubor pluginu a klikněte na Instalovat.
3. Po instalaci plugin aktivujte.

Plugin můžete nahrát také ručně – rozbalenou složku toret-ai-ads zkopírujte přes FTP do adresáře /wp-content/plugins/ a poté plugin aktivujte v sekci Pluginy.

Po aktivaci najdete nastavení v menu Toret plugins → Ads for AI. Nastavení je rozdělené do čtyř záložek: Nastavení, Produktový feed, Měření a Log.

Aktivace licence

1. Přejděte do Toret plugins → Ads for AI.
2. Do pole Licenční klíč vložte klíč, který najdete na Toret.cz v sekci Můj účet.
3. Klikněte na Ověřit licenci.

Po úspěšném ověření se zobrazí Licence je aktivní a zpřístupní se zbytek nastavení. Bez platné licence plugin nezobrazí žádné další volby.

⚠️ Plugin vyžaduje aktivní WooCommerce. Pokud WooCommerce není aktivní, nastavení feedu a měření se nezobrazí.

Základní nastavení

Na záložce Nastavení vyplňte přístupové údaje z Ads Manageru a zapněte plugin.

Stav pluginu

• Plugin je aktivní – hlavní vypínač. Když je plugin vypnutý, pixel se do webu nevkládá, konverze se neodesílají a soubor feedu se smaže a dál negeneruje.

Přístupové údaje Ads Manageru

• Pixel ID – najdete ho v Ads Manageru (Konverze > Zdroj dat).
• Klíč Conversions API – vytvoříte ho v Ads Manageru (Konverze > Klíče pro konverze). Klíč se ukládá pouze na serveru a nikdy se neodesílá do prohlížeče. Po uložení se v poli zobrazují jen poslední čtyři znaky. Pokud chcete klíč zachovat, nechte pole prázdné. Pro smazání klíče zaškrtněte Odstranit klíč.

Plugin klíč ověřuje u OpenAI po uložení, každých 12 hodin a při každé odeslané konverzi. U pole se zobrazuje jeho stav:

• Klíč …XXXX ověřen u OpenAI – klíč je v pořádku.
• Klíč …XXXX uložen, zatím neověřen – ověření ještě neproběhlo.
• Klíč …XXXX odmítnut OpenAI – klíč je neplatný nebo byl zrušen. V Ads Manageru vytvořte nový klíč a vložte ho do pluginu.

Log

• Logování – zaznamenává generování feedu a požadavky na Conversions API do záložky Log.
• Maximum záznamů – kolik záznamů se v logu uchovává (50–2000). Starší záznamy se automaticky mažou.

Nastavení Souhlas s cookies na stejné záložce popisujeme v kapitole Souhlas s cookies.

Všechny změny uložíte tlačítkem Uložit nastavení.

Produktový feed

Feed je CSV soubor se seznamem produktů podle specifikace OpenAI. Každý jednoduchý produkt má ve feedu jeden řádek, variabilní produkt má jeden řádek za každou variantu. Nastavení najdete na záložce Produktový feed.

Stav feedu

• URL feedu – adresa, kterou vložíte do Ads Manageru v části Kanály → Vytvořit kanál → Hostovaná adresa URL . Tlačítkem Kopírovat ji zkopírujete, tlačítkem Otevřít si soubor stáhnete a zkontrolujete. Název souboru obsahuje tajný token, proto adresu nesdílejte.
• Poslední generování – čas posledního úspěšného vygenerování, počet řádků a produktů. Pokud generování skončilo chybou, zobrazí se zde její popis. Pod stavem vidíte také termín příštího automatického generování.
• Nejsou ve feedu – seznam produktů, které se do feedu při posledním generování nedostaly, rozdělený podle důvodu. Kliknutím na název produktu otevřete jeho úpravu.
• Vygenerovat nyní – tlačítko Vygenerovat feed spustí generování ihned. Generování probíhá po dávkách s ukazatelem průběhu, takže funguje i pro velké katalogy. Stránku nechte otevřenou, dokud generování neskončí.
• Nová URL feedu – tlačítko Vygenerovat novou tajnou URL použijte, pokud adresa feedu unikla. Stará adresa okamžitě přestane fungovat a novou je potřeba vložit do Ads Manageru.

⚠️ Položky, které Ads Manager v aktuálním feedu nenajde, po 14 dnech vyprší. Automatické generování proto nechte zapnuté.

Generování

• Automatické generování – feed se pravidelně přegeneruje přes WP-Cron. Ve výchozím stavu je zapnuto.
• Interval – Každou hodinu, Dvakrát denně nebo Jednou denně (výchozí). Ads Manager si feed stahuje podle vlastního plánu, obvykle jednou denně, takže denní interval zpravidla stačí. Interval feedu nemá vliv na pixel ani Conversions API.
• Velikost dávky – kolik produktů se zpracuje v jedné dávce (výchozí 200). Pokud generování na sdíleném hostingu končí chybou kvůli časovému limitu, hodnotu snižte.

Produkty

• Identifikátor položky – ID produktu / variace (doporučeno) nebo SKU (pokud je SKU prázdné, použije se ID). Stejný identifikátor plugin používá i v událostech pixelu a Conversions API, aby Ads Manager dokázal spárovat konverze s produkty.
• Popis – zda se do feedu posílá krátký popis (pokud chybí, použije se dlouhý) nebo dlouhý popis (pokud chybí, použije se krátký).
• Dostupnost
  • Zahrnout vyprodané produkty – vyprodané produkty zůstanou ve feedu označené jako out_of_stock. Doporučujeme nechat zapnuté: Ads Manager je sám přestane zobrazovat a po naskladnění je opět začne nabízet.
  • Přeskočit produkty skryté z katalogu – produkty s viditelností „Skryté“ se do feedu nedostanou.
• Vyřadit kategorie z reklam – produkty ve vybraných kategoriích (včetně podkategorií) zůstanou ve feedu, ale jsou označené jako nezpůsobilé pro reklamy (is_ads_eligible = false). Ads Manager je tak přestane nabízet.

⚠️ Identifikátor položky po spuštění kampaní neměňte. Konverze by se přestaly párovat s produkty v katalogu.

Prodejce a značka

• Název prodejce – pokud pole nevyplníte, použije se název webu.
• URL prodejce – pokud pole nevyplníte, použije se úvodní stránka webu.
• Zdroj značky – značka je ve feedu povinná. Vyberte taxonomii WooCommerce Značky nebo globální atribut produktu, ve kterém značku produktu evidujete. Možnost — pevný text níže — použije pro všechny produkty text z pole Náhradní značka.
• Náhradní značka – použije se u produktů, které značku nemají vyplněnou. Pokud pole nevyplníte, použije se název webu.

Země, vrácení a způsobilost

• Cílové země – ISO kódy zemí oddělené čárkou, např. CZ,SK. Pokud pole nevyplníte, použije se země obchodu z nastavení WooCommerce.
• URL podmínek vrácení – veřejná stránka s podmínkami vrácení zboží. Po vyplnění plugin označí produkty jako vratné.
• Lhůta pro vrácení (dny) – počet dní na vrácení zboží. Hodnota 0 znamená, že se lhůta neposílá.
• Způsobilost pro vyhledávání – označí produkty jako vhodné i pro vyhledávání v ChatGPT. Vyřazené produkty jsou vždy nezpůsobilé pro reklamy i vyhledávání. V době betaverze ChatGPT Ads se produkty z feedu používají pouze v reklamách.

Co se do feedu nedostane

Produkt, který nesplňuje povinné údaje, plugin do feedu nezahrne a uvede ho v přehledu Nejsou ve feedu.

Důvod	Řešení
Nulová cena	Produkty zdarma nebo sety bez pevné ceny. Vyplňte u produktu Cenu pro ChatGPT Ads.
Chybí obrázek produktu	Nahrajte k produktu hlavní obrázek.
Vyprodáno	Zobrazí se, jen když je vypnutá volba Zahrnout vyprodané produkty.
Skryté z katalogu	Zobrazí se, jen když je zapnutá volba Přeskočit produkty skryté z katalogu.
Seskupený produkt	Seskupený produkt se do feedu neposílá, jednotlivé produkty ve skupině ve feedu jsou.
Odebráno vlastním filtrem	Produkt vyřadil vlastní kód na webu (filtr pro vývojáře).

Produkty vyřazené z reklam (kategorií nebo zaškrtávacím políčkem u produktu) v tomto přehledu nejsou – ve feedu zůstávají, jen označené jako nezpůsobilé pro reklamy.

Ceny se do feedu přenášejí tak, jak se zobrazují zákazníkům v e-shopu (s DPH nebo bez DPH podle nastavení WooCommerce). Pokud má produkt akci, posílá se běžná i akční cena. GTIN (EAN) se přebírá z pole GTIN, UPC, EAN nebo ISBN v nastavení produktu.

Nastavení u produktu, varianty a kategorie

U jednotlivých produktů najdete nastavení v úpravě produktu na záložce Data produktu → Pokročilé.

• Vyřadit z ChatGPT Ads – produkt (včetně všech jeho variant) se pošle do feedu jako nezpůsobilý pro reklamy.
• Cena pro ChatGPT Ads – nepovinná cena, která se pošle do feedu místo ceny z WooCommerce. Hodí se pro produkty, které mají ve WooCommerce cenu 0, například sety oceňované podle jednotlivých položek. Zadejte ji stejně jako běžnou cenu produktu. Platí pro všechny varianty.
• Původní cena pro ChatGPT Ads – nepovinná cena před slevou. Pokud je vyšší než Cena pro ChatGPT Ads, reklama zobrazí produkt jako zlevněný.

U variabilních produktů najdete políčko Vyřadit z ChatGPT Ads také u každé varianty zvlášť. Vyřadit tak můžete jen vybrané varianty.

Celé kategorie vyřadíte v nastavení pluginu na záložce Produktový feed → Produkty → Vyřadit kategorie z reklam.

TIP: Ads Manager si feed stahuje zpravidla jednou denně. Změny ve vyřazení produktů se v něm projeví až po dalším načtení feedu.

Externí cron (REST API)

WP-Cron se spouští jen při návštěvě webu, a na málo navštěvovaných webech proto nemusí běžet spolehlivě. Generování feedu můžete místo toho spouštět serverovým cronem nebo externí cron službou. Adresy najdete na záložce Produktový feed v části Externí cron (REST API).

• URL pro generování – voláním této adresy (GET nebo POST) spustíte nebo prodloužíte generování feedu. Jedno volání generuje feed nejvýše 45 sekund. U velkého katalogu může být potřeba adresu zavolat vícekrát – odpověď pak obsahuje stav running. Délku jednoho běhu můžete změnit parametrem budget (5–300 sekund).
• URL stavu – vrací aktuální stav, čas posledního generování a počet řádků. Hodí se pro monitoring.
• Nový token – tlačítko Vygenerovat nový token REST API vytvoří nový tajný token. Původní adresy okamžitě přestanou fungovat.

Příklad záznamu pro serverový cron, který generuje feed každých 6 hodin:

0 */6 * * * curl -s -o /dev/null "URL_PRO_GENEROVÁNÍ"

Token můžete místo parametru v adrese poslat také v hlavičce X-Toret-AI-Ads-Token.

TIP: Pokud používáte externí cron, můžete vypnout Automatické generování přes WP-Cron.

OpenAI Pixel

OpenAI Pixel měří chování návštěvníků přímo v prohlížeči. Nastavení najdete na záložce Měření v části OpenAI Pixel (prohlížeč).

⚠️ Pixel funguje jen s vyplněným Pixel ID na záložce Nastavení. Bez něj se zobrazí upozornění a pixel se do webu nevloží.

• Vkládat OpenAI Pixel do webu – zapne nebo vypne vkládání pixelu.
• Události – vyberte, které události se mají měřit. Ve výchozím stavu jsou zapnuté všechny.
• Pokročilé párování – na děkovné stránce a u přihlášených zákazníků předá pixelu hashované údaje zákazníka (e-mail, telefon, jméno, adresu). Údaje se hashují algoritmem SHA-256 už na serveru, do prohlížeče se nikdy nedostanou v čitelné podobě. Zpřesňuje to přiřazení konverzí ke kampaním, když chybí identifikátor kliknutí.
• Ladicí režim – vypisuje aktivitu pixelu do konzole prohlížeče. Používejte jen při testování.

Měřené události

Událost	Kdy se odešle
contents_viewed	Zobrazení detailu produktu
items_added	Přidání do košíku (klasické i AJAXové, včetně blokových šablon)
checkout_started	Zobrazení pokladny s neprázdným košíkem
order_created	Zobrazení děkovné stránky po dokončení objednávky

Když návštěvník přijde na web z reklamy v ChatGPT, obsahuje adresa parametr oppref (identifikátor kliknutí). Pixel ho uloží do cookie a plugin ho při dokončení objednávky uloží i k objednávce. Díky tomu OpenAI přiřadí nákup ke správné kampani.

TIP: Fungování pixelu ověříte zapnutím Ladicího režimu. Otevřete web v anonymním okně, povolte marketingové cookies a v konzoli prohlížeče (klávesa F12) sledujte odesílané události. Po otestování ladicí režim vypněte.

Conversions API

Conversions API odesílá informaci o objednávce (událost order_created) přímo ze serveru e-shopu do OpenAI. Na rozdíl od pixelu nezávisí na blokátorech reklam v prohlížeči zákazníka ani na tom, zda zákazník zobrazí děkovnou stránku. Respektuje přitom souhlas s marketingovými cookies stejně jako pixel (viz kapitola Souhlas s cookies). Nastavení najdete na záložce Měření v části Conversions API (server).

⚠️ Pro odesílání musí být na záložce Nastavení vyplněné Pixel ID i Klíč Conversions API.

• Odesílat order_created ze serveru – zapne nebo vypne odesílání objednávek. Pokud OpenAI klíč odmítne, zobrazí se u přepínače Klíč odmítnut OpenAI.
• Odeslat když
  • Objednávka je vytvořena (výchozí) – objednávka se odešle hned po dokončení v pokladně. Doporučujeme pro dobírku a bankovní převod.
  • Objednávka je zaplacena – objednávka se odešle po přijetí platby nebo při změně stavu na Zpracovává se nebo Dokončeno.
• Údaje zákazníka – k objednávce se připojí hashovaný e-mail, telefon a jméno z fakturace, dále město, PSČ a země, IP adresa a identifikace prohlížeče. OpenAI tyto údaje doporučuje odesílat pro přesnější párování. Osobní údaje se hashují algoritmem SHA-256, jak vyžaduje API.
• Odesílání na pozadí – informace o tom, jak se požadavky odesílají. S Action Scheduler (součást WooCommerce) běží odesílání na pozadí a nezpomaluje pokladnu. Pokud Action Scheduler na webu není, použije se WP-Cron.

Každá objednávka se odešle jen jednou. Po úspěšném odeslání plugin přidá k objednávce poznámku ChatGPT Ads: konverze odeslána přes Conversions API.

Pokud odeslání selže kvůli výpadku spojení nebo dočasné chybě na straně OpenAI, plugin ho automaticky zopakuje – celkem až pětkrát s rostoucím odstupem (po 2 minutách, 10 minutách, 30 minutách a 2 hodinách). Když se odeslání nepodaří ani tak, nebo jde o chybu, kterou opakování nevyřeší (například neplatný klíč), plugin přidá k objednávce poznámku ChatGPT Ads: odeslání konverze selhalo s kódem chyby. Podrobnosti najdete v Logu.

Deduplikace s pixelem

Pixel na děkovné stránce i Conversions API posílají objednávku se stejným ID události ve tvaru order_{číslo objednávky}. OpenAI obě události pozná jako jednu konverzi a sloučí je. Pixel i Conversions API proto můžete mít zapnuté současně – a doporučujeme to.

Test Conversions API

Tlačítko Odeslat testovací událost (pouze validace) v části Test Conversions API odešle ukázkovou událost order_created v testovacím režimu. OpenAI zkontroluje klíč, Pixel ID a formát dat, ale nic neuloží – test se v Ads Manageru nezobrazí jako konverze. Výsledek se zobrazí v horní části stránky spolu s odpovědí OpenAI.

Tlačítko je aktivní, jen když máte vyplněné Pixel ID i klíč Conversions API.

Souhlas s cookies

Plugin umí načíst OpenAI Pixel a odesílat konverze až po souhlasu návštěvníka s marketingovými cookies. Nastavení najdete na záložce Nastavení v části Souhlas s cookies, pole Režim souhlasu.

⚠️ Ve výchozím stavu je nastaven režim Bez řešení souhlasu, kdy pixel měří vždy. Pokud váš web používá cookie lištu, zvolte jeden z následujících dvou režimů.

• Bez řešení souhlasu – pixel měří vždy – skript OpenAI se načte na každé stránce bez ohledu na souhlas. Použijte, jen pokud váš web souhlas s marketingovými nástroji nepotřebuje.
• WP Consent API (kategorie marketing) – skript OpenAI se nenačte vůbec, dokud návštěvník nepovolí kategorii marketing. Funguje přímo s pluginem Complianz (bez dalšího pluginu) a s každou cookie lištou, která podporuje plugin WP Consent API (např. CookieYes, propojení pro Cookiebot a další).
• Ručně – čekat na JavaScriptové volání z vaší cookie lišty – skript OpenAI se nenačte, dokud ho vaše cookie lišta sama nepovolí. Tento režim použijte pro lišty, které WP Consent API nepodporují.

V ručním režimu zavolejte po souhlasu návštěvníka s marketingovými cookies:

window.toretAiAdsConsent(true);   // souhlas udělen
window.toretAiAdsConsent(false);  // souhlas odvolán

Místo toho můžete vyvolat událost:

document.dispatchEvent(new CustomEvent("toret_ai_ads_consent", {detail: {granted: true}}));

O souhlasu se rozhoduje až v prohlížeči návštěvníka, takže nastavení správně funguje i s cache pluginy.

Režim souhlasu platí pro OpenAI Pixel i pro Conversions API. Pokud zákazník neudělil souhlas s marketingovými cookies, plugin jeho objednávku do OpenAI neodešle ani ze serveru.

Log

Na záložce Log najdete záznamy o generování feedu, odeslání konverzí přes Conversions API a ověřování licence. Záznamy se ukládají, jen když je na záložce Nastavení zapnuté Logování.

• Tlačítky Vše, Feed, Conversions API, Pixel a Licence záznamy filtrujete podle typu.
• U každého záznamu vidíte čas, typ, úroveň (info / error) a zprávu. Pod odkazem Detaily najdete technické údaje, například odpověď OpenAI nebo identifikátor kliknutí.
• Tlačítkem Vymazat log smažete všechny záznamy.

TIP: Když budete kontaktovat podporu kvůli chybě, přiložte prosím snímek obrazovky z Logu s rozbalenými detaily.

Odinstalování a smazání dat

Při deaktivaci pluginu se zastaví automatické generování feedu a naplánované odesílání konverzí. Nastavení zůstane zachované.

Při smazání pluginu v administraci WordPressu se odstraní všechna data pluginu:

• nastavení pluginu, licence a log,
• soubory feedu ve složce wp-content/uploads/toret-ai-ads,
• naplánované úlohy,
• údaje uložené u objednávek (identifikátory kliknutí, příznaky odeslání konverze),
• nastavení u produktů (Vyřadit z ChatGPT Ads, Cena pro ChatGPT Ads, Původní cena pro ChatGPT Ads).

⚠️ Smazání nelze vrátit. Pokud plugin jen dočasně nepotřebujete, stačí ho deaktivovat nebo vypnout volbou Plugin je aktivní.

Časté dotazy a řešení potíží

Feed se negeneruje automaticky.

Automatické generování běží přes WP-Cron, který se spouští jen při návštěvě webu. Zkontrolujte, že je zapnuté Automatické generování a že se na záložce Produktový feed zobrazuje termín příštího generování. Pokud WP-Cron na vašem webu nefunguje spolehlivě, nastavte externí cron.

Generování feedu končí chybou nebo se zasekne.

Na sdíleném hostingu může být překročen časový limit. Snižte Velikost dávky a feed vygenerujte znovu. Pokud se zobrazí chyba Do složky uploads nelze zapisovat, požádejte správce hostingu o kontrolu oprávnění složky wp-content/uploads.

Některý produkt ve feedu chybí.

Podívejte se na přehled Nejsou ve feedu na záložce Produktový feed. Nejčastějšími důvody jsou nulová cena a chybějící obrázek produktu. Seznam všech důvodů najdete v kapitole Co se do feedu nedostane.

Vyřadil jsem produkt z reklam, ale v Ads Manageru je stále aktivní.

Ads Manager si feed stahuje podle vlastního plánu, zpravidla jednou denně. Změna se projeví po dalším načtení feedu.

Konverze se neodesílají přes Conversions API.

Zkontrolujte postupně:

1. Na záložce Nastavení je vyplněné Pixel ID a u klíče se zobrazuje Klíč ověřen u OpenAI. Pokud byl klíč odmítnut, vytvořte v Ads Manageru nový.
2. Na záložce Měření je zapnuté Odesílat order_created ze serveru.
3. Tlačítko Odeslat testovací událost (pouze validace) vrátí úspěšný výsledek. Pokud používáte režim souhlasu, objednávky zákazníků bez souhlasu s marketingovými cookies se neodesílají – to je očekávané chování.
4. V poznámkách objednávky a v Logu (filtr Conversions API) najdete informaci o odeslání nebo chybě.

Objednávka vytvořená ručně v administraci se neodeslala.

Při volbě Odeslat když: Objednávka je vytvořena plugin odesílá jen objednávky dokončené zákazníkem v pokladně. Objednávky založené v administraci se odešlou při volbě Objednávka je zaplacena, až přejdou do stavu Zpracovává se nebo Dokončeno.

Nezapočítá se objednávka dvakrát, když mám zapnutý pixel i Conversions API?

Ne. Obě události mají stejné ID a OpenAI je sloučí do jedné konverze.

Pixel na webu neměří.

Zkontrolujte, že je vyplněné Pixel ID a zapnutá volba Vkládat OpenAI Pixel do webu. Pokud používáte režim souhlasu, pixel se načte až po povolení marketingových cookies. Zapněte Ladicí režim a v konzoli prohlížeče ověřte, zda se události odesílají. Měření může blokovat také blokátor reklam v prohlížeči.

Kde založím reklamní účet a kampaně?

Reklamní účet, schválení feedu i kampaně spravujete v Ads Manageru ChatGPT Ads od OpenAI. S nastavením účtu a kampaní vám poradit nemůžeme, pomoc najdete u podpory OpenAI.