|
1 | | -# wordpress-conversion-plugin |
2 | | -WP plugin for simple conversion setup for FAPI |
| 1 | +# FAPI Signals |
| 2 | + |
| 3 | +Plugin pro rychle nasazeni pixelu, FAPI konverzi a volitelneho server-side PageView do WordPressu. Tento dokument je urceny pro vyvojare a popisuje architekturu, strukturu kodu a postupy vyvoje. |
| 4 | + |
| 5 | +## Rychly prehled |
| 6 | +- Vstupni bod pluginu je `fapi-signals.php`. |
| 7 | +- Inicializace bezi ve `src/Plugin.php`. |
| 8 | +- Pixely a konverzni skripty se vkladaji v `wp_head`, `fapi.js` ve `wp_footer`. |
| 9 | +- Server-side PageView bezi pres REST API `wp-json/fapi-signals/v1/pageview`. |
| 10 | +- Nastaveni se ukladaji do `wp_options` pod klicem `fapi_signals_settings` (s migraci z puvodniho klice). |
| 11 | + |
| 12 | +## Struktura projektu |
| 13 | +- `fapi-signals.php` hlavni soubor pluginu, registruje autoload a spousti `Plugin` |
| 14 | +- `src/Plugin.php` registrace hooku, assetu a REST rout |
| 15 | +- `src/Admin/SettingsPage.php` UI nastaveni |
| 16 | +- `src/Tracking/PixelInjector.php` generovani a injektovani pixelu, JS logika pro injekci |
| 17 | +- `src/Tracking/ConversionInjector.php` generovani a injektovani konverzniho skriptu |
| 18 | +- `src/Tracking/SnippetBuilder.php` stavba pixel snippetu a konverznich volani |
| 19 | +- `src/Tracking/FapiSdkInjector.php` vklada `fapi.js` do paticky |
| 20 | +- `src/Tracking/RewardsInjector.php` vklada FAPI Rewards script |
| 21 | +- `src/ServerSide/PageViewDispatcher.php` REST endpoint pro server-side PageView |
| 22 | +- `src/ServerSide/PayloadBuilder.php` mapovani platform -> payload |
| 23 | +- `src/Settings.php` defaults + nacitani/ukladani nastaveni |
| 24 | +- `src/Admin/ResetController.php` testovaci reset nastaveni pres REST |
| 25 | + |
| 26 | +## Runtime flow |
| 27 | +1) `PixelInjector` vytvori seznam pixel snippetu pres `SnippetBuilder`. |
| 28 | +2) `ConversionInjector` vygeneruje konverzni snippet (FAPI SDK callback). |
| 29 | +3) `FapiSdkInjector` vzdy vklada `https://web.fapi.cz/js/sdk/fapi.js` do paticky. |
| 30 | +4) `RewardsInjector` vklada FAPI Rewards script do hlavicky. |
| 31 | +5) JS config je dostupny pres `window.FapiSignalsConfig` a inicializuje injekce. |
| 32 | +6) Pro PageView se generuje `event_id`, ktere sdili Meta Pixel (client) a Meta CAPI (server). |
| 33 | +7) Server-side PageView se odesila s `event_id` i pro TikTok/Pinterest/LinkedIn. |
| 34 | +8) Pokud je uzivatel prihlaseny, do Meta CAPI PageView se doplnuje `user_data` |
| 35 | + (hashovane identifikatory + IP/UA) pro lepsi match. |
| 36 | + |
| 37 | +## Nastaveni a migrace |
| 38 | +- Klic v `wp_options`: `fapi_signals_settings` |
| 39 | +- UI pro nastaveni pouziva `Settings::OPTION_KEY` |
| 40 | + |
| 41 | +## Consent manager (aktualni stav) |
| 42 | +Consent logika je v `PixelInjector` (JS), ale momentalne je ignorovana a skripty se vkladaji okamzite. |
| 43 | +Kod je zachovany a jde snadno vratit zpet upravou `PixelInjector` a `ConversionInjector`. |
| 44 | + |
| 45 | +## Server-side PageView |
| 46 | +JS klient vola: |
| 47 | +`/wp-json/fapi-signals/v1/pageview` |
| 48 | + |
| 49 | +Backend generuje payloady v `PayloadBuilder` a odesila je pres `wp_remote_post`. |
| 50 | + |
| 51 | +## Jak pridat novy tool |
| 52 | +1) `src/Settings.php` |
| 53 | + - pridej default values (toggle + ID/keys) |
| 54 | +2) `src/Admin/SettingsPage.php` |
| 55 | + - pridej UI sekci nebo polozky do existujici sekce |
| 56 | +3) `src/Tracking/SnippetBuilder.php` |
| 57 | + - pridej pixel snippet do `buildPixelSnippets` |
| 58 | + - pridej konverzni call do `buildConversionSnippet` |
| 59 | +4) `src/ServerSide/PayloadBuilder.php` (pokud ma server-side podporu) |
| 60 | + - pridej novou platformu a payload |
| 61 | +5) `src/Tracking/PixelInjector.php` |
| 62 | + - pokud je potreba server-side prepinač, rozsirit `server_side` config |
| 63 | +6) Testy |
| 64 | + - uprav E2E v `e2e/*.spec.js` |
| 65 | + - uprav unit testy v `tests/` (pokud pokryvaji danou cast) |
| 66 | + |
| 67 | +## Vyvojove prostredi |
| 68 | +### Docker (WordPress + MySQL) |
| 69 | +1) `docker compose up -d` |
| 70 | +2) WordPress bezi na `http://localhost:8071` |
| 71 | +3) Plugin je namountovany do `wp-content/plugins/fapi-signals` |
| 72 | + |
| 73 | +### E2E testy (Playwright) |
| 74 | +1) `npm install` |
| 75 | +2) `WP_BASE_URL=http://localhost:8071 WP_ADMIN_USER=<user> WP_ADMIN_PASS=<pass> npm run test:e2e` |
| 76 | + |
| 77 | +Poznamka: testy pouzivaji REST reset endpoint `wp-json/fapi-signals/v1/reset`. |
| 78 | + |
| 79 | +### PHPUnit |
| 80 | +Pokud mas nainstalovane dependencies: |
| 81 | +- `php vendor/bin/phpunit` |
| 82 | + |
| 83 | +Nebo pres Docker service: |
| 84 | +- `docker compose --profile tools run --rm phpunit` |
| 85 | + |
| 86 | +## Deploy do WordPress.org SVN |
| 87 | +### Predpoklady |
| 88 | +- Schvaleny plugin na WordPress.org a prideleny slug |
| 89 | +- SVN pristup k repozitari `https://plugins.svn.wordpress.org/<slug>/` |
| 90 | +- Nastaveny `Stable tag` v `readme.txt` |
| 91 | + |
| 92 | +### 1) Priprava lokalniho balicku |
| 93 | +V repu uz je pripraveny `wporg/` adresar: |
| 94 | +- `wporg/trunk` obsahuje produkcni obsah pluginu |
| 95 | +- `wporg/assets` je urceny pro bannery/icony/screenshoty |
| 96 | + |
| 97 | +Pokud je potreba, znovu si `wporg/trunk` pripravis synchronizaci z rootu repa: |
| 98 | +``` |
| 99 | +mkdir -p wporg/trunk wporg/assets wporg/tags |
| 100 | +rsync -av --delete \ |
| 101 | + --exclude "wporg/" \ |
| 102 | + --exclude ".git/" \ |
| 103 | + --exclude ".cursor/" \ |
| 104 | + --exclude "node_modules/" \ |
| 105 | + --exclude "tests/" \ |
| 106 | + --exclude "e2e/" \ |
| 107 | + --exclude "test-results/" \ |
| 108 | + --exclude "docker-compose.yml" \ |
| 109 | + --exclude "Dockerfile" \ |
| 110 | + --exclude "README.md" \ |
| 111 | + --exclude "SPECIFICATION.md" \ |
| 112 | + --exclude "package.json" \ |
| 113 | + --exclude "package-lock.json" \ |
| 114 | + --exclude "playwright.config.js" \ |
| 115 | + --exclude "phpunit.xml" \ |
| 116 | + --exclude ".phpunit.result.cache" \ |
| 117 | + --exclude ".env" \ |
| 118 | + --exclude ".gitignore" \ |
| 119 | + --exclude ".cursorignore" \ |
| 120 | + ./ wporg/trunk/ |
| 121 | +``` |
| 122 | + |
| 123 | +### 2) SVN checkout |
| 124 | +``` |
| 125 | +svn checkout https://plugins.svn.wordpress.org/<slug>/ wporg-svn |
| 126 | +``` |
| 127 | + |
| 128 | +### 3) Nakopirovani trunku |
| 129 | +``` |
| 130 | +rsync -av --delete wporg/trunk/ wporg-svn/trunk/ |
| 131 | +``` |
| 132 | + |
| 133 | +### 4) Assets (volitelne) |
| 134 | +Pokud mas bannery/icony, nakopiruj je do `wporg-svn/assets/`. |
| 135 | + |
| 136 | +### 5) Commit do SVN |
| 137 | +``` |
| 138 | +cd wporg-svn |
| 139 | +svn status |
| 140 | +svn add --force . |
| 141 | +svn delete <smazane-soubory> |
| 142 | +svn commit -m "Release <verze>" |
| 143 | +``` |
| 144 | + |
| 145 | +### 6) Tagovani |
| 146 | +``` |
| 147 | +svn copy trunk tags/<verze> |
| 148 | +svn commit -m "Tag <verze>" |
| 149 | +``` |
| 150 | + |
| 151 | +### 7) Overeni |
| 152 | +- Zkontroluj, ze `readme.txt` ma spravny `Stable tag` |
| 153 | +- Po publikaci se zmeny projevi do par minut |
| 154 | + |
| 155 | +### GitHub -> WP SVN (automatizace) |
| 156 | +Pro automaticky deploy z GitHubu je bezne pouzivany action: |
| 157 | +- `10up/action-wordpress-plugin-deploy` |
| 158 | + |
| 159 | +Postup: |
| 160 | +- vytvoris `.github/workflows/deploy.yml` |
| 161 | +- do secrets pridas `SVN_USERNAME` a `SVN_PASSWORD` |
| 162 | +- deploy se spousti pri tagu nebo release |
| 163 | + |
| 164 | +## Dokumentace |
| 165 | +- Detailni specifikace je v `SPECIFICATION.md`. |
0 commit comments