Plugin najdete na Adobe Commerce Marketplace pod názvem Ecomail Email Marketing nebo proklikem zde.
Některé pokročilé e-commerce funkce, například behaviorální tracking, práce s objednávkami a opuštěným košíkem, mohou vyžadovat odpovídající tarif Ecomailu.
Co v článku najdete?
1. Co plugin umí
Synchronizuje přihlášení a odhlášení kontaktů mezi Magento newsletterem a vybraným seznamem v Ecomailu.
Přenáší nové kontakty a volitelné údaje zákazníka.
Může vytvářet nebo aktualizovat kontakt podle údajů z objednávky.
Odesílá nové i historické objednávky jako transakce.
Přenáší obsah košíku pro práci s opuštěným košíkem.
Sleduje návštěvy stránek a zobrazení produktů.
Umí respektovat nativní souhlas s cookies v Magentu.
Vloží do obchodu formulář vytvořený v Ecomailu.
Přenáší jazyk obchodu do vlastního pole
MAGENTO_LANGUAGE.Přenáší štítky
magento,magento_newslettera volitelně zákaznickou skupinu.Nabízí webhook pro zpětný přenos stavu přihlášení z Ecomailu do Magenta.
Umožňuje spustit počáteční synchronizaci existujících zákazníků a objednávek na pozadí.
Zobrazuje stav synchronizace a poslední požadavky na Ecomail API.
2. Jaká data se přenášejí
Podle zapnutých nastavení může plugin do Ecomailu odesílat:
e-mailovou adresu;
jméno a příjmení;
společnost, telefon a poštovní adresu;
datum narození;
zákaznickou skupinu ve formě štítku;
jazykovou mutaci obchodu;
zdroj kontaktu;
stav přihlášení k newsletteru;
objednávky a jejich položky;
obsah nákupního košíku;
návštěvy stránek a zobrazení produktů.
Přenášejte pouze údaje, které skutečně potřebujete a pro které máte odpovídající právní titul nebo souhlas.
Štítky kontaktů
Plugin může přidat tyto štítky:
Štítek | Kdy se přidá |
| Ke kontaktům přeneseným z Magenta. |
| Pokud je kontakt přihlášený k Magento newsletteru. |
Zákaznická skupina | Pokud zapnete Customer groups to tags. Mezery se nahradí podtržítky; například |
Při běžné synchronizaci jednoho kontaktu plugin nejprve načte jeho stávající štítky v Ecomailu a nové štítky k nim přidá. Při hromadné počáteční synchronizaci je přenos štítků samostatně volitelný, protože může nahradit stávající štítky kontaktu v Ecomailu.
3. Požadavky před instalací
Připravte si:
obchod s Magento Open Source nebo Adobe Commerce 2.4.x;
PHP ve verzi podporované vaší instalací Magenta;
aktivní PHP rozšíření cURL;
účet v Ecomailu, API klíč a alespoň jeden seznam kontaktů;
přístup k souborům obchodu a příkazové řádce SSH;
funkční Magento cron;
aktuální zálohu souborů a databáze.
Instalaci na produkčním obchodě doporučujeme svěřit správci Magenta nebo vývojáři. Před instalací vždy vytvořte zálohu.
4. Instalace pluginu
Magento od verze 2.4 používá pro instalaci rozšíření příkazovou řádku. Po získání bezplatného pluginu na Adobe Commerce Marketplace použijte přístupové klíče Marketplace spojené s danou instalací Magenta.
Instalace přes Composer
V terminálu přejděte do hlavní složky Magenta a spusťte:
composer require ecomailcz/magento2-ecomail php bin/magento module:enable Ecomail_Ecomail php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f php bin/magento cache:flush
Pokud na vašem serveru funguje bin/magento jako spustitelný soubor, můžete příkazy zadat také bez php:
bin/magento module:enable Ecomail_Ecomail bin/magento setup:upgrade bin/magento setup:di:compile bin/magento setup:static-content:deploy -f bin/magento cache:flush
Pokud se zobrazí Permission denied, používejte variantu začínající php bin/magento nebo úplnou cestu k PHP, kterou vám sdělí hosting.
Ruční nahrání souborů
Pokud jste instalační balíček získali přímo od podpory Ecomailu, nahrajte jeho obsah do:
app/code/Ecomail/Ecomail
Poté spusťte Magento příkazy z předchozí části, počínaje module:enable.
5. Základní propojení s Ecomailem
V administraci Magenta otevřete:
Stores > Configuration > Customers > Ecomail
Nastavte Enabled na Yes.
Vložte API Key z Ecomailu. Najdete jej v Ecomailu v části Správa účtu > Pro vývojáře. Podrobnosti najdete také v článku API pro práci s Ecomailem.
Nastavení uložte.
Klikněte na Load Subscriber Lists.
Vyberte seznam v poli Subscriber List.
Upravte další volby podle potřeb vašeho obchodu.
Klikněte na Save Config.
Po úspěšném propojení se v poli Status zobrazí aktivní spojení.
Pokud používáte více webů nebo pohledů obchodu, zkontrolujte v levém horním přepínači Store View, pro kterou úroveň konfiguraci ukládáte. Jednotlivé obchody mohou používat odlišný API klíč, seznam i další volby.
6. Přehled všech nastavení
General
Nastavení | Vysvětlení |
Status | Ověří, zda je plugin zapnutý a zda se s uloženým API klíčem podařilo spojit s Ecomailem. |
Enabled | Zapne nebo vypne komunikaci pluginu s Ecomailem. |
API Key | API klíč vašeho Ecomail účtu. Magento jej po uložení uchovává v šifrované podobě. |
Subscriber List | Seznam v Ecomailu, do kterého se budou kontakty synchronizovat. Nově vytvořený seznam se může v nabídce objevit se zpožděním. |
Load Subscriber Lists | Znovu načte dostupné seznamy z Ecomailu. Použijte po vložení API klíče nebo vytvoření nového seznamu. |
Skip Double opt-in | Při nastavení Yes přeskočí u běžně přidávaných kontaktů potvrzovací e-mail. Zapněte pouze tehdy, pokud máte souhlas kontaktu vyřešený jiným způsobem. |
Trigger Autoresponders | U nového jednotlivého přihlášení dovolí spustit navázané automatizace. Hromadná počáteční synchronizace automatizace nespouští. |
Contact source | Zdroj uložený u kontaktu v Ecomailu. Výchozí hodnota je |
Allow initial sync | Bezpečnostní přepínač, který zpřístupní počáteční synchronizaci existujících zákazníků a objednávek. |
Update existing contacts during initial sync | Určuje, zda počáteční synchronizace smí aktualizovat kontakty, které již ve vybraném seznamu existují. |
Send tags during initial sync | Přenese při počáteční synchronizaci štítky z Magenta. U existujících kontaktů může dojít k nahrazení jejich současných štítků v Ecomailu. |
Subscriber sync batch size | Počet kontaktů v jednom API požadavku: 100, 250, 500, 1000 nebo 3000. Výchozí a maximální hodnota je 3000. |
Transaction sync batch size | Počet objednávek v jednom API požadavku: 100, 250, 500 nebo 1000. Výchozí a maximální hodnota je 1000. |
Initial Sync | Panel pro spuštění synchronizace a sledování stavu, průběhu, počtu zpracovaných záznamů a času poslední změny. |
Webhook Token | Tajný náhodný řetězec, který chrání příchozí webhook. Vygenerujte jej tlačítkem a konfiguraci uložte. |
Webhook URL | Automaticky sestavená adresa pro zpětnou synchronizaci stavu kontaktu. Tlačítkem ji zkopírujete do Ecomailu. |
Checkout opt-out text | Text u checkboxu v pokladně, kterým zákazník odmítne přihlášení k newsletteru. Maximálně 160 znaků. |
Personal Information
Nastavení | Vysvětlení |
Customer name | Přenáší jméno a příjmení zákazníka. |
Customer address | Přenáší společnost, ulici, město, PSČ, zemi a telefon, pokud jsou k dispozici. |
Address type | Určuje, zda se použije doručovací nebo fakturační adresa. Pokud zvolená adresa není dostupná, plugin se pokusí použít dostupnou adresu objednávky. |
Customer DOB | Přenáší datum narození, pokud jej má zákazník v Magentu vyplněné. |
Send order transactions | Odesílá objednávky a jejich položky do Ecomailu jako transakce. |
Update contacts from order data | Při nové objednávce vytvoří nebo aktualizuje kontakt podle údajů z objednávky, pokud zákazník v pokladně neodmítl newsletter. |
Cart items | Odesílá obsah košíku známého kontaktu pro automatizaci opuštěného košíku. |
Customer groups to tags | Přidá zákaznickou skupinu jako štítek bez mezer. Skupina |
Store locale custom field | Uloží jazyk obchodu do vlastního pole |
Behavior Tracking
Nastavení | Vysvětlení |
Enabled | Zapne Ecomail tracking návštěv stránek. Vyžaduje správné App ID. |
Respect Magento cookie consent | Pokud je v Magentu zapnutý Cookie Restriction Mode, trackingové skripty se načtou až po souhlasu návštěvníka s cookies. Doporučujeme ponechat Yes. |
App ID | Název vašeho Ecomail účtu používaný trackingovým skriptem. Najdete jej také v URL po přihlášení do Ecomailu. |
Track product views | Na detailu produktu odesílá událost |
Enable Ecomail form widget | Zapne zobrazení formuláře vytvořeného v Ecomailu. |
Ecomail Form ID | Hodnota |
Ecomail Account Name | Název Ecomail účtu použitý v kódu formuláře. |
Logs
Nastavení | Vysvětlení |
Recent API Requests | Zobrazuje posledních 10 požadavků na Ecomail API, jejich čas, endpoint, výsledek, HTTP stav a dobu trvání. Neukládá API klíč ani celé odesílané údaje. |
7. Jak funguje průběžná synchronizace
Po uložení konfigurace plugin reaguje na nové události v obchodě:
Přihlášení k newsletteru: kontakt se přidá do zvoleného seznamu v Ecomailu.
Odhlášení z newsletteru: změna se odešle do Ecomailu.
Úprava účtu nebo adresy: pokud je kontakt přihlášený k newsletteru, aktualizují se povolené údaje.
Nová objednávka: plugin může aktualizovat kontakt a odeslat transakci s položkami objednávky.
Změna košíku: u známého kontaktu se odešle aktuální obsah košíku.
Návštěva stránky nebo produktu: při zapnutém trackingu se odešlou behaviorální události.
Pokud zákazník v pokladně zaškrtne checkbox s odmítnutím newsletteru, plugin z dané objednávky nevytvoří ani neaktualizuje newsletterový kontakt. Odeslání objednávky jako transakce se řídí samostatným nastavením Send order transactions.
Při běžném přidání nebo aktualizaci kontaktu plugin zachová jeho existující štítky v Ecomailu a doplní k nim štítky z Magenta.
8. Jak funguje počáteční synchronizace
Počáteční synchronizace slouží k přenosu zákazníků a objednávek, které v Magentu existovaly už před instalací pluginu.
Spuštění
Ověřte, že na serveru pravidelně běží Magento cron.
Nastavte Allow initial sync na Yes.
Zvolte, zda se mají aktualizovat existující kontakty a odesílat štítky.
Nastavte velikost dávky kontaktů a transakcí.
Uložte konfiguraci.
V panelu Initial Sync vyberte požadovaná data a klikněte na Start Sync.
Zpracování na pozadí
Synchronizaci zpracovává Magento cron, takže stránku můžete zavřít nebo obnovit.
Při jednom spuštění cron úlohy se zpracuje jedna dávka kontaktů nebo jedna dávka objednávek.
Nejprve se zpracují kontakty, poté objednávky.
Výchozí dávka obsahuje až 3000 kontaktů nebo 1000 objednávek.
Na pomalejším hostingu lze nastavit menší dávky.
V jednu chvíli může běžet pouze jedna počáteční synchronizace.
Pokud hromadný požadavek odmítne jeden chybný záznam, plugin dávku automaticky rozdělí a pokusí se odeslat ostatní záznamy. Proto může při chybě vzniknout více API požadavků.
Stav a průběh zůstávají uložené i po obnovení administrační stránky.
Příklad: při 6 500 zákaznících a dávce 3 000 proběhnou nejméně tři cron průchody pro kontakty. Objednávky se začnou zpracovávat v některém z následujících průchodů. Pokud hosting spouští cron každých pět minut, bude každý další krok pokračovat přibližně po pěti minutách.
Stavy synchronizace
Stav | Význam |
| Úloha čeká na nejbližší spuštění Magento cronu. |
| Právě se zpracovává dávka. |
| Všechny vybrané záznamy byly zpracovány. |
| Synchronizaci zastavila chyba. Podrobnosti najdete v poslední zprávě a v logu. |
Hromadný import transakcí nespouští automatizace Ecomailu s triggerem „Provedl nákup / Makes an order“.
9. Nastavení webhooku
Webhook zajišťuje zpětný přenos stavu přihlášení z Ecomailu do Magento newsletteru. Když se kontakt odhlásí v Ecomailu, může se změna propsat také do Magenta.
V nastavení pluginu klikněte na Generate Token.
Klikněte na Save Config. Bez uložení nebude nový token platný.
Klikněte na Copy URL.
V Ecomailu otevřete seznam kontaktů používaný pro Magento.
Přejděte do Nastavení seznamu > Nastavení webhooku.
Zapněte odesílání informací na webhook a vložte zkopírovanou URL.
Nastavení seznamu uložte.
Webhook upraví stav pouze u kontaktu, který už existuje v Magento newsletteru. Vygenerovaný token nikomu neposílejte ani jej nezveřejňujte.
10. Tracking, cookies a formuláře
Tracking
Po zapnutí Behavior Tracking plugin načítá Ecomail trackingový skript a odesílá návštěvy stránek. Volba Track product views přidává událost zobrazení produktu podle jeho SKU.
Cookies
Pokud používáte nativní Magento Cookie Restriction Mode, ponechte Respect Magento cookie consent nastavené na Yes. Ecomail skripty se potom načtou až po uložení souhlasu návštěvníka.
Pokud používáte cookie lištu třetí strany, ověřte její napojení na souhlas Magenta. Samotný plugin sleduje nativní cookie souhlasu user_allowed_save_cookie.
Formulář Ecomail
V Ecomailu vytvořte a publikujte formulář.
V jeho instalačním kódu najděte hodnotu
js.ida název účtu.V Magentu zapněte Enable Ecomail form widget.
Vyplňte Ecomail Form ID a Ecomail Account Name.
Konfiguraci uložte a vymažte Magento cache.
11. Kontrola funkčnosti a logy
Po nastavení doporučujeme provést tento test:
Přihlaste testovací e-mail k newsletteru v Magentu.
Zkontrolujte kontakt ve vybraném seznamu v Ecomailu.
Upravte jméno nebo adresu testovacího zákazníka.
Přidejte produkt do košíku jako známý kontakt.
Vytvořte testovací objednávku.
Otevřete produktovou stránku a ověřte tracking.
Otestujte odhlášení přes webhook.
V části Recent API Requests zkontrolujte poslední požadavky.
Plugin zobrazuje posledních 10 požadavků. Záznamy se uchovávají nejvýše sedm dní a databázový log je omezen na 10 000 řádků. Neukládají se celé payloady ani API klíče.
Pokud chyba vznikne ještě před odesláním API požadavku, nemusí se v panelu objevit. Správce obchodu ji může dohledat také ve standardních Magento logách ve složce var/log.
12. Aktualizace pluginu
Před aktualizací vytvořte zálohu souborů a databáze. V hlavní složce Magenta spusťte:
composer update ecomailcz/magento2-ecomail php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f php bin/magento cache:flush
Příkaz module:enable není při běžné aktualizaci potřeba, pokud modul nebyl vypnutý.
Po aktualizaci zkontrolujte konfiguraci, stav spojení, jeden testovací kontakt a jednu testovací objednávku.
13. Nejčastější potíže
Seznamy kontaktů se nenačtou
Ověřte API klíč.
Konfiguraci nejprve uložte a poté klikněte na Load Subscriber Lists.
Zkontrolujte, že server může komunikovat s Ecomail API.
Nově vytvořený seznam může být dostupný se zpožděním.
Počáteční synchronizace zůstává ve stavu Pending
Magento cron neběží nebo se spouští pod jinou verzí PHP než obchod. Požádejte hosting, aby ověřil pravidelné spouštění php bin/magento cron:run.
Synchronizace probíhá pomalu
Každý cron průchod zpracuje jednu dávku. Rychlost proto závisí na intervalu Magento cronu a nastavené velikosti dávky. Na stabilním hostingu použijte výchozí hodnoty 3000 kontaktů a 1000 transakcí.
Kontakt nebo objednávka se nepřenesly
Zkontrolujte Recent API Requests. Červený záznam obsahuje HTTP stav a zkrácenou chybovou zprávu. U lokální chyby zkontrolujte také Magento logy.
Webhook nezměnil stav kontaktu
Ověřte, že jste po vygenerování tokenu uložili konfiguraci.
Znovu zkopírujte celou URL.
Zkontrolujte správný seznam a Store View.
Kontakt musí už existovat v Magento newsletteru.
Tracking se nenačítá
Ověřte Behavior Tracking, App ID a nastavení cookies.
Po změně spusťte vyčištění cache a případně nasazení statického obsahu.
Pokud používáte jinou cookie lištu, ověřte, že nastavuje nativní souhlas Magenta.
Příkaz bin/magento vrací Permission denied
Použijte příkaz s PHP:
php bin/magento cache:flush
Na některých hostinzích je nutná úplná cesta k PHP, například /opt/alt/php82/usr/bin/php. Správnou cestu vám sdělí poskytovatel hostingu.
Kompilace nemůže smazat generated/code/Magento
Jde obvykle o oprávnění nebo vlastnictví souborů vytvořených jiným uživatelem či verzí PHP. Nepokračujte mazáním naslepo; požádejte správce serveru o opravu vlastnictví a bezpečné vyčištění složky generated.
Potřebujete poradit? Napište nám na chat nebo na support@ecomail.cz.