Joomla System Plugin pro kompletni server-side mereni pro e-shopy na Joomla 4/5 + VirtueMart 4.x/5.x. Nahrazuje client-side JS snippety a odesila data primo ze serveru do mericich platforem pres jejich API.

Parametr	Hodnota
Identifikator	plg_system_semakin_sst
CMS	Joomla 4.x / 5.x
E-commerce	VirtueMart 4.x+
PHP	8.1+
Aktualni verze	1.0.4

Podporovane platformy: GA4, Google Ads, Sklik.cz, Zbozi.cz, Heureka Overeno zakazniky, Heureka OCM, Google Customer Reviews.

---

1. Pozadavky

• Joomla 4.x nebo 5.x
• VirtueMart 4.x nebo novejsi
• PHP 8.1 nebo novejsi
• MySQL 5.7+ / MariaDB 10.3+
• GDPR komponenta: StoreJExtensions GDPR, Sema Cookie Consent nebo CookieYes (nebo manualni rezim)

2. Instalace

Ziskani balicku

Stahnete soubor plg_system_semakin_sst-1.0.4.zip ze SemaHub (semakin.cz).

Postup instalace

1. Prihlaste se do administrace Joomla.
2. Prejdete do System > Install > Extensions.
3. Nahrajte ZIP soubor plg_system_semakin_sst-1.0.4.zip.
4. Po instalaci plugin vytvori dve databazove tabulky: #__semakin_sst_log a #__semakin_sst_queue.

Upgrade: Stejny postup jako instalace. Joomla pouzije method="upgrade". Data v tabulkach zustanou zachovana.

3. Aktivace pluginu

Po instalaci je nutne plugin rucne povolit:

1. Prejdete do System > Manage > Plugins.
2. Vyhledejte semakin_sst nebo Server-Side Tracking.
3. Kliknete na nazev pluginu a nastavte Status = Enabled.
4. Nastavte parametry pluginu (viz dalsi sekce).

4. Zakladni nastaveni

Otevrete nastaveni: System > Plugins > klik na nazev pluginu.

Zalozka: Zakladni nastaveni

Parametr	Vychozi	Popis
Tracking povolen	Ano	Globalni vypinac veskereho trackingu.
Testovaci rezim	Ne	GA4 eventy jdou na debug endpoint. V produkci VZDY vypnout.
GDPR komponenta	StoreJExtensions	Zdroj souhlasu uzivatele (viz sekce 5).
Vychozi vrstva souhlasu	0 (Anonymni)	Pouzije se, kdyz souhlas nelze precist nebo je zvolen manualni rezim.
Uchovavani logu (dny)	90	Zaznamy starsi nez zadany pocet dnu budou automaticky smazany.
Uchovavani fronty (dny)	30	Zpracovane/neuspesne zaznamy starsi nez zadany pocet dnu budou smazany.
Inline zpracovani fronty (%)	5	Pravdepodobnost zpracovani retry fronty na kazdem requestu. Nastavte na 0 pri pouziti Task Scheduleru.

5. GDPR a souhlas uzivatelu

Plugin pouziva trivrstvy model souhlasu:

Vrstva	Nazev	Co se odesila
L0	Anonymni	Anonymizovane eventy: zkracena IP, docasne UUID, zadne cookies
L1	Analytics	GA4 s client_id, session_id, GCR widget
L2	Marketing	Konverze GA4/Ads/Sklik/Zbozi/Heureka; hashovany email/telefon

Podporovane GDPR komponenty

Komponenta	Metoda detekce
StoreJExtensions GDPR (com_gdpr)	JS bridge cte Local Storage, nastavuje cookie semakin_sst_cl
Sema Cookie Consent	JS bridge cte Local Storage (scc_cookie_consent), nastavuje cookie semakin_sst_cl
CookieYes	Prime cteni cookie cookieyes-consent
Manualni	Pevny consent level (bez detekce)

Dulezite: Kategorie cookie

Bridge cookie semakin_sst_cl musi byt zarazena jako Nezbytna (kategorie 1) ve vasi consent komponente, NE jako Analyticka nebo Marketingova. Je to technicka cookie pro komunikaci consent stavu z JS do PHP – sama o sobe nic netrackuje.

Timing: Cookie se projevi az na dalsim requestu (JS nastavi cookie, PHP ji precte na nasledujicim pozadavku). Pro purchase eventy je timing vzdy OK – zakaznik nacte minimalne 2 stranky pred checkoutem.

6. Google Analytics 4

Zalozka: GA4

Parametr	Popis
GA4 povolen	Zapne odesilani eventu pres Measurement Protocol v2.
Measurement ID	Format G-XXXXXXXXXX. Najdete v GA4 > Spravce > Datove streamy.
API Secret	Tajny klic Measurement Protocol. GA4 > Datove streamy > Measurement Protocol API secrets.
Nazev _ga cookie	Vychozi _ga. Mente jen pri pouziti vlastniho nazvu cookie.
Odesilat anonymni eventy (L0)	Odesila zakladni eventy i bez souhlasu (anonymizovane). Doporuceno: Ano.
Deduplikace s klientem	Pridava event_id proti dvojitemu pocitani pri soucasnem pouziti gtag.js.

Sledovane eventy

Event	Detekce	Min. souhlas
session_start	Prvni stranka v session	L0
page_view	Kazda frontend stranka	L0
view_item	URL s view=productdetails	L0
view_item_list	URL s view=category	L0
add_to_cart	VM hook plgVmOnAddToCart	L0
begin_checkout	URL s view=cart	L0
purchase	VM hook + DB polling (OPC)	L0

Fallback client_id

Bez gtag.js neexistuje cookie _ga. Plugin automaticky vytvori nahradni cookie semakin_sst_cid s GA4-kompatibilnim formatem (expirace 2 roky).

7. Google Ads

Zalozka: Google Ads

Parametr	Popis
Google Ads povoleny	Zapne upload konverzi pres Conversion API v23.
Conversion ID	Format AW-XXXXXXXXX (pro referenci).
Conversion Action ID	Numericke ID konverzni akce (ne AW- format).
Developer Token	Z Google Ads API Center.
Customer ID	ID klientskeho uctu (format XXX-XXX-XXXX).
MCC Customer ID	Volitelne. ID manazerskeho uctu pri pouziti MCC.
OAuth Client ID	Z Google Cloud Console.
OAuth Client Secret	Vkladejte do textarea (password pole mohou oriznou).
OAuth Refresh Token	Vkladejte do textarea. OAuth consent screen musi byt v rezimu Production.
Enhanced Conversions	Odesila hashovany email/telefon pro lepsi prirazovani.

Dulezite poznamky

• Typ konverzni akce: Musi byt „Import z kliknuti“ (ne „Webove stranky“). Typ Webove stranky je pro gtag.js.
• Duplicitni akce: Pokud e-shop pouzival webovou konverzni akci (z gtag.js), deaktivujte ji nebo prepnete na sekundarni.
• GCLID/GBRAID/WBRAID: Plugin zachytava vsechny tri typy click ID z URL parametru a uklada do cookies (90 dnu). Na zarizenich s omezenymi cookies (Safari, iOS) Google posila gbraid misto gclid.
• Enhanced Conversions for Leads: Musi byt zapnuto v Google Ads > Nastaveni > Rozsirene konverze pro potencialni zakazniky.
• Timeout: Google Ads API pouziva 5s timeout (ne 500ms jako GA4).

8. Sklik.cz

Zalozka: Sklik

Parametr	Popis
Sklik povolen	Zapne Sklik konverzni mereni a retargeting.
ID konverzniho cile	Numericke ID z vaseho Sklik konverzniho kodu (parametr id).
ID retargetingoveho seznamu	Volitelne. ID retargetingoveho publika.
Odesilat hashovany e-mail (EID)	SHA-256 hash emailu pro lepsi prirazovani (pouze L2).

Jak to funguje

Sklik nema server-side API. Plugin injektuje JavaScript snippety (rc.js) pred </body>:

• Retargeting (rc.retargetingHit) na kazde strance (L0+)
• Konverze (rc.conversionHit) pri nakupu (L0+)
• Parametr consent: Dynamicky – consent:0 bez marketingoveho souhlasu, consent:1 se souhlasem
• EID a Zbozi.cz parametry: Pouze pri L2

CSP: Pokud web pouziva Content-Security-Policy, pridejte https://c.seznam.cz do script-src, connect-src a img-src. Pridejte https://h.seznam.cz do connect-src. Viz CSP poznamka v nastaveni pluginu.

9. Zbozi.cz

Zalozka: Zbozi.cz

Parametr	Popis
Zbozi.cz povoleny	Zapne backend konverzni API.
Shop ID	Alfanumericky identifikator obchodu z administrace Zbozi.cz.
PRIVATE_KEY	Tajny klic pro backend API. Najdete v Zbozi.cz admin > Konverze > API klic.

Jak to funguje

Zbozi.cz pouziva dvouslozkove mereni:

1. Backend (ZboziSender): HTTP POST na https://www.zbozi.cz/action/{SHOP_ID}/conversion/backend s PRIVATE_KEY v JSON tele.
2. Frontend (pres SklikSender): rc.conversionHit() s parametry zboziId a zboziType. Sdili stejny rc.js jako Sklik.

Obe slozky jsou nutne. Bez frontend JS Zbozi.cz hlasi chybu ORPHANED_BACKEND.

Odesilaji se pouze purchase eventy, pouze pri L2.

10. Heureka – Overeno zakazniky

Zalozka: Heureka (prvni sekce)

Parametr	Popis
Overeno zakazniky povoleno	Zapne registraci objednavek pro dotaznik spokojenosti.
Tajny klic	API klic pro Overeno zakazniky (v2 API).
Varianta Heureky	CZ (heureka.cz) nebo SK (heureka.sk). Sdilena s OCM.
Odesilat e-mail zakaznika	Nutne pro zaslani dotazniku. Odesila se v plaintextu (vyzaduje L2).
Odesilat produkty	Odesila ID produktu pro produkt-specificke otazky v dotazniku.

Opt-out checkbox

Parametr	Popis
Zobrazit opt-out checkbox	Automaticky vlozi checkbox do VirtueMart checkout formulare.
Text checkboxu	Konfigurovatelny text. Vychozi dle doporuceni Heureky.
Kod pro rucni vlozeni	HTML/JS kod pro rucni vlozeni do sablony, pokud automaticke vlozeni nefunguje.

Checkbox pouziva opt-out model: nezaskrtnuty = zakaznik souhlasi; zaskrtnuty = zakaznik se odhlasuje. Cookie semakin_sst_heureka_optout=1 (expirace 2 hodiny).

GDPR: E-mail zakaznika se odesila v plaintextu do Heureky. Do logu pluginu se nikdy neuklada.

11. Heureka – OCM (Mereni konverzi)

Zalozka: Heureka (sekce OCM)

Parametr	Popis
Heureka OCM povoleno	Zapne mereni konverzi pres Heureka OCM SDK.
API klic	OCM API klic (odlisny od klice Overeno zakazniky!). Najdete v Heureka admin > Statistiky > Mereni konverzi.

Jak to funguje

• Stranky produktu: SDK s page=product_detail nastavi atribucni cookie (hg_ocm_id, 30 dnu).
• Dekovaci stranka: SDK s page=thank_you odesle data objednavky (ID produktu, ceny, mnozstvi, celkem, mena).
• Pouze pri L2 souhlasu. Podpora cross-request session pro platebni brany.

12. Google Customer Reviews

Zalozka: Google Customer Reviews

Parametr	Popis
GCR povolen	Zapne Survey Opt-In Widget.
Merchant Center ID	Numericke ID z Google Merchant Center.
Pocet dnu do doruceni	Odhadovana doba doruceni (vychozi 5 dnu).
Zeme doruceni	ISO 3166-1 alpha-2 kod (nebo automaticky dle jazyka).
Jazyk pruzkumu	BCP 47 kod jazyka (napr. cs, sk, en).
Poloha opt-in dialogu	Stred / rohy obrazovky.

GCR vyzaduje pouze L1 (Analytics) souhlas – nejde o reklamu. E-mail zakaznika se vlozi do widgetu jen pri L2.

13. Retry fronta a Task Scheduler

Kdyz API volani selze, event se ulozi do tabulky #__semakin_sst_queue pro automaticky retry s exponencialnim backoffem (1 min > 5 min > 15 min).

Dva zpusoby zpracovani

Zpusob	Konfigurace
Inline zpracovani	Nastavte „Inline zpracovani fronty“ na 5–10 %. Zpracovava se na nahodnych HTTP requestech. Vhodne pro weby bez cronu.
Joomla Task Scheduler	Vytvorte ulohy v System > Naplanovane ulohy. Nastavte inline zpracovani na 0 %.

Nastaveni Task Scheduleru

1. Prejdete do System > Naplanovane ulohy > Nova.
2. Vytvorte „Semakin SST: Zpracovat retry frontu“ – spoustet kazdych 15 minut.
3. Vytvorte „Semakin SST: Uklid starych zaznamu“ – spoustet jednou denne.
4. V nastaveni pluginu nastavte inline zpracovani na 0 %.
5. Overeni: tlacitko „Spustit test“ – kod ukonceni 0 = OK.

Task Scheduler vyzaduje cron job nebo „lazy cron“. Pro spolehlivy provoz nastavte server cron:

*/5 * * * * php /cesta/k/joomla/cli/joomla.php scheduler:run > /dev/null 2>&1

14. Logovani a diagnostika

Zalozka: Logovani a fronta

Parametr	Popis
Logovani povoleno	Globalni vypinac logovani.
Uroven logu	Minimalni uroven pro souborovy log. DB log zapisuje VZDY bez ohledu na toto nastaveni.
Logovat do databaze	Zapis do #__semakin_sst_log. Doporuceno: vzdy zapnuto (nutne pro deduplikaci).
Logovat do souboru	Zapis do logs/semakin_sst.php ve slozce Joomla logs.
Max. pocet opakovani	Maximalni pocet pokusu (vychozi 3).

Kontrola DB logu

SELECT event_name, platform, consent_level, status, http_status, created_at
FROM #__semakin_sst_log
ORDER BY id DESC
LIMIT 20;

Nahradte #__ vasim prefixem tabulek.

• consent_level by mel byt 2 pro purchase eventy (pokud ma zakaznik marketingovy souhlas).
• status by mel byt sent pro uspesna odeslani.

15. Odinstalace

1. Prejdete do System > Manage > Extensions.
2. Vyhledejte semakin_sst.
3. Oznacte a odinstalujte.

Odinstalator smaze obe tabulky (#__semakin_sst_log a #__semakin_sst_queue).

16. Reseni problemu

Zadne eventy v databazi

1. Overite, ze plugin je povoleny (Status = Enabled).
2. Zkontrolujte, ze services/provider.php existuje v adresari pluginu na serveru.
3. Overite, ze bridge cookie semakin_sst_cl je nastavena (DevTools > Application > Cookies).
4. Pokud cookie chybi, zkontrolujte konfiguraci GDPR komponenty a ze bridge JS neni stripovan.

consent_level je vzdy 0

• Bridge cookie semakin_sst_cl chybi nebo je blokovana.
• Zkontrolujte, ze semakin_sst_cl je zarazena jako Nezbytna v consent komponente (ne Analyticka/Marketingova).
• Na prvni strance po instalaci je consent vzdy L0 (bridge cookie potrebuje jeden page load pro inicializaci).

Google Ads konverze se nezobrazuji v dashboardu

1. Overite, ze konverzni akce je typu „Import z kliknuti“ (ne Webove stranky).
2. Zkontrolujte, ze GCLID/GBRAID je pritomen v payloadu v DB logu.
3. Overite, ze OAuth consent screen je v rezimu Production (ne Testing).
4. Zkontrolujte, ze Enhanced Conversions for Leads je zapnuto v nastaveni Google Ads.
5. Pokud je aktivni i webova konverzni akce, deaktivujte ji nebo prepnete na sekundarni.

Sklik kod se nespousti

• Overite, ze rc.js je nacteno jako synchronni <script> tag (zkontrolujte zdrojovy kod stranky).
• Pokud web pouziva CSP, pridejte pozadovane domeny (viz CSP poznamka v zalozce Sklik).
• Zkontrolujte konzoli prohlizece na chyby.

Zbozi.cz chyba ORPHANED_BACKEND

• Obe slozky (backend API i frontend JS rc.conversionHit s zboziId) jsou nutne.
• Overite, ze Sklik je povolen (Sklik rc.js obsluhuje frontend jak pro Sklik, tak pro Zbozi.cz).

Heureka HTTP 400 „Missing expected key email“

• Overite, ze „Odesilat e-mail zakaznika“ je zapnuto v nastaveni Heureky.
• E-mail vyzaduje L2 souhlas.

Purchase eventy se nedetekuji (OPC)

• One Page Checkout pluginy obchazeji VirtueMart hooky. Plugin pouziva DB polling (detectUnloggedPurchases) jako fallback.
• Overite, ze DB logovani je zapnuto (nutne pro deduplikaci).
• Zkontrolujte, ze requesty neprichazeji od botu (prazdne cookies = preskoceno).

---

Jak tracking funguje (prehled)

1. Navstevnik nacte stranku e-shopu.
2. Plugin detekuje typ stranky (produkt, kategorie, kosik atd.) z URL parametru.
3. Eventy se sesbiraji (page_view, view_item, begin_checkout atd.).
4. Uroven souhlasu se zjisti z GDPR komponenty (pres bridge cookie).
5. Eventy se anonymizuji dle urovne souhlasu.
6. Server-side sendery odeslou eventy do povolenych platforem (GA4, Google Ads, Zbozi, Heureka).
7. JavaScript sendery injektuji kod pred </body> (Sklik, Heureka OCM, GCR).
8. Pro nakupy: VM hook plgVmConfirmedOrder nebo DB polling (OPC) detekuje objednavku.
9. Neuspesna API volani se zaradi do fronty pro automaticky retry.

---

Kontrolni seznam pro spusteni

• Plugin nainstalovan a povolen
• GDPR komponenta vybrana a nastavena
• Bridge cookie semakin_sst_cl zarazena jako Nezbytna
• GA4: Measurement ID a API Secret nastaveny
• Google Ads: Konverzni akce vytvorena jako „Import z kliknuti“
• Google Ads: OAuth credentials v textarea polich, consent screen v rezimu Production
• Google Ads: Enhanced Conversions for Leads zapnuty
• Sklik: ID konverze a ID retargetingu nastaveny
• Zbozi.cz: Shop ID a PRIVATE_KEY nastaveny
• Heureka: API klic nastaven, opt-out checkbox povolen
• Heureka OCM: OCM API klic nastaven (odlisny od klice Overeno)
• GCR: Merchant Center ID nastaveno
• CSP hlavicky aktualizovany (pokud je to relevantni)
• DB logovani zapnuto
• Testovaci rezim VYPNUT
• Inline zpracovani fronty nastaveno (nebo Task Scheduler nakonfigurovan)
• Testovaci nakup proveden a overen v DB logu a dashboardech platforem