Advanced Newsletter Suite pentru Magento 2 - instrucțiuni de instalare și configurare

Scopul documentului

Acest document descrie instalarea și configurarea pachetului magento-2-package-advanced-newsletter-suite. Este un pachet complet de newsletter și email marketing pentru Magento 2, care include audiențe, capture, campanii, conținut, trimitere, tracking, panou operațional și puncte frontend de înscriere.

Cerințe preliminare

Înainte de implementare pregătiți:

• Magento Open Source 2.4.x,
• Composer,
• acces CLI la bin/magento,
• cont de administrator Magento,
• date de acces pentru SMTP,
• cron Magento configurat,
• disponibilitatea de a porni consumatorii de coadă,
• mediu de test pentru verificarea înscrierii, campaniilor și trimiterilor.

Ce instalează pachetul

Pachetul include:

• Kowal_MarketingCore,
• Kowal_EmailTransport,
• Kowal_EmailSmtp,
• Kowal_EmailEvents,
• Kowal_EmailTemplateStudio,
• Kowal_NewsletterAudience,
• Kowal_NewsletterCapture,
• Kowal_NewsletterCampaigns,
• Kowal_NewsletterConsole,
• Kowal_NewsletterFrontend.

Acesta este cel mai înalt nivel de agregare din ecosistemul modulelor de email marketing pentru Magento.

Instalare

1. Instalarea pachetului Composer

composer config repositories.kowal.package.advanced.newsletter.suite vcs https://github.com/kowalco/package-advanced-newsletter-suitecomposer config repositories.kowal.module.email.events vcs https://github.com/kowalco/module-email-eventscomposer config repositories.kowal.module.email.smtp vcs https://github.com/kowalco/module-email-smtpcomposer config repositories.kowal.module.email.template.studio vcs https://github.com/kowalco/module-email-template-studiocomposer config repositories.kowal.module.email.transport vcs https://github.com/kowalco/module-email-transportcomposer config repositories.kowal.module.marketing.core vcs https://github.com/kowalco/module-marketing-corecomposer config repositories.kowal.module.newsletter.audience vcs https://github.com/kowalco/module-newsletter-audiencecomposer config repositories.kowal.module.newsletter.campaigns vcs https://github.com/kowalco/module-newsletter-campaignscomposer config repositories.kowal.module.newsletter.capture vcs https://github.com/kowalco/module-newsletter-capturecomposer config repositories.kowal.module.newsletter.console vcs https://github.com/kowalco/module-newsletter-consolecomposer config repositories.kowal.module.newsletter.frontend vcs https://github.com/kowalco/module-newsletter-frontendcomposer config --global --auth github-oauth.github.com composer require kowal/package-advanced-newsletter-suite

2. Activarea modulelor în Magento

bin/magento module:enable \ Kowal_MarketingCore \ Kowal_EmailTransport \ Kowal_EmailSmtp \ Kowal_EmailEvents \ Kowal_EmailTemplateStudio \ Kowal_NewsletterAudience \ Kowal_NewsletterCapture \ Kowal_NewsletterCampaigns \ Kowal_NewsletterConsole \ Kowal_NewsletterFrontendbin/magento setup:upgradebin/magento cache:flush

În modul de producție executați suplimentar:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -f

Configurare

1. Secțiunea administrativă

Configurația de bază ar trebui să fie disponibilă în:

Kowal / Email Marketing

Conform specificației, grupurile de setări așteptate sunt:

• general,
• transport,
• smtp,
• campaigns,
• double_opt_in,
• events.

2. Configurarea trimiterii

Mai întâi configurați baza delivery:

• activitatea modulului,
• tipul implicit de transport,
• logarea trimiterilor,
• contul sau conturile SMTP,
• routing-ul mesajelor,
• fallback pentru conturile de rezervă, dacă este utilizat.

Implementarea pachetului complet necesită în continuare un strat SMTP și de transport funcțional.

3. Configurarea audienței și a înscrierilor

Apoi confirmați configurația stratului de audiență:

• integrarea cu newsletter_subscriber,
• liste de mailing,
• segmente,
• statusuri de abonare,
• metadate suplimentare ale abonatului,
• surse de achiziție,
• consimțăminte de marketing.

Configurați de asemenea procesul de înscriere:

• formulare și puncte de înscriere,
• double opt-in,
• șablonul mesajului de confirmare,
• durata de valabilitate a tokenului de confirmare.

4. Configurarea campaniilor

În secțiunea campaigns setați:

• batch_size,
• max_retry_count,
• send_rate_limit_per_run,
• watchdog_timeout_minutes.

Pachetul suportă:

• definirea campaniilor,
• programarea,
• coada de destinatari,
• batch processing pentru trimitere,
• istoricul execuției campaniei,
• trimiteri de test.

5. Configurarea Template Studio

Dacă implementarea include lucrul cu conținutul newsletterului, configurați EmailTemplateStudio conform domeniului MVP:

• lucrul pe șabloanele native de newsletter Magento,
• selectarea layout-urilor de produs,
• salvarea secțiunii generate în șablonul nativ,
• importul conținutului pregătit în campanie.

6. Configurarea evenimentelor email

În secțiunea events configurați:

• procesarea evenimentelor,
• retenția payload-urilor,
• politica de acceptare a evenimentelor duplicate de la furnizori.

Stratul EmailEvents este responsabil pentru observabilitatea procesului de livrare și asocierea evenimentelor cu logurile de transport și campaniile.

7. Configurarea panoului administrativ și a frontendului

Pachetul complet include:

• Kowal_NewsletterConsole ca panou operațional,
• Kowal_NewsletterFrontend ca strat pentru formulare frontend și widget-uri de înscriere.

După instalare verificați:

• disponibilitatea dashboard-ului,
• scurtăturile către configurație și modulele operaționale,
• vizualizarea ultimelor erori și trimiteri,
• prezența formularelor de înscriere în frontendul magazinului.

Cron și consumatorii de coadă

Pachetul complet necesită procesare asincronă activă.

1. Cron Magento

bin/magento cron:install

Cron ar trebui să fie responsabil pentru:

• planificarea campaniilor,
• recuperarea task-urilor,
• watchdog operațional.

2. Queue consumers

Consumatorii de coadă ar trebui să fie responsabili pentru procesarea efectivă a batch-urilor de trimitere. Numele consumatorilor trebuie preluate din fișierele actuale etc/queue_consumer.xml ale modulelor implementate.

În mediul de producție asigurați:

• rularea consumers în fundal,
• autostart după restartul serverului,
• monitorizarea avariilor,
• logarea erorilor.

Pași după instalare

După implementare, efectuați lista completă de verificare:

1. Configurați și testați contul SMTP.
2. Verificați routing-ul mesajelor.
3. Verificați înscrierea abonatului și double opt-in.
4. Confirmați compatibilitatea cu newsletterul nativ Magento.
5. Creați o listă sau un segment de test.
6. Pregătiți o campanie de test.
7. Efectuați un test send.
8. Verificați planificarea campaniei prin cron.
9. Verificați procesarea cozii de către consumers.
10. Confirmați înregistrarea logurilor și a evenimentelor email.
11. Verificați dashboard-ul administrativ.
12. Verificați formularele frontend și widget-urile de înscriere.

Test de acceptanță după implementare

Pachetul este implementat corect dacă:

• modulele se instalează corect în Magento 2.4.x,
• trimiterea SMTP funcționează la nivel de conturi și routing,
• înscrierea abonatului rămâne compatibilă cu newsletterul nativ Magento,
• campania este planificată de cron și procesată de queue consumer,
• statusurile de livrare actualizează logurile și evenimentele email,
• panoul administrativ afișează datele operaționale de bază,
• punctele frontend de înscriere funcționează corect,
• după dezactivarea modulelor, mecanismul de bază Magento_Newsletter poate funcționa în continuare.

Observații de implementare

• Pachetul complet merită implementat împreună cu o configurație verificată de SMTP și tracking.
• Datele extinse trebuie stocate în propriile tabele, fără duplicarea tabelului nativ newsletter_subscriber.
• Documentația operațională a implementării ar trebui să includă suplimentar procedura de gestionare a cozilor, webhook-urilor și a testelor de regresie pentru configurația administrativă.

Amazon SES - creare cont și configurare pentru integrarea trimiterii

Scopul documentului

Acest document descrie cum să pregătiți contul AWS și serviciul Amazon SES astfel încât să poată fi realizată integrarea trimiterii cu modulele acestui proiect.

Instrucțiunea include:

• crearea contului AWS,
• activarea Amazon SES,
• verificarea domeniului și a expeditorului,
• ieșirea din sandbox,
• pregătirea acreditărilor,
• două variante de integrare cu Magento:
  • prin Amazon SES API,
  • prin Amazon SES SMTP.

Notă importantă pentru acest proiect

În codul proiectului sunt disponibile două căi de integrare cu Amazon SES:

1. SES API în Kowal_EmailTransport cu tipul de transport ses.
2. SES SMTP în Kowal_EmailSmtp cu tipul de transport smtp.

Asta înseamnă că merită să pregătiți o singură dată contul AWS și SES, însă modul final de conectare la Magento depinde de varianta de implementare aleasă.

Ipoteze preliminare

Înainte de a începe, pregătiți:

• domeniul din care vor fi trimise mesajele, de exemplu example.com,
• acces la DNS-ul acestui domeniu,
• adresa expeditorului, de exemplu newsletter@example.com,
• card bancar sau metodă de facturare activă în AWS,
• decizia privind regiunea în care va funcționa SES, de exemplu eu-central-1 sau us-east-1.

1. Crearea contului AWS

1. Intrați în panoul AWS: https://aws.amazon.com/
2. Creați un cont AWS.
3. Activați MFA pentru contul root.
4. Nu folosiți cheile de acces ale contului root pentru integrarea aplicației.

Pentru integrarea Magento pregătiți un utilizator IAM separat sau acreditări SMTP separate, în funcție de varianta aleasă.

2. Activarea Amazon SES

1. Autentificați-vă în AWS Console.
2. Deschideți serviciul Amazon Simple Email Service.
3. Alegeți regiunea în care doriți să desfășurați trimiterea.

Acest lucru este important, deoarece în SES regiunea are relevanță operațională:

• identitățile expeditorului sunt menținute per regiune,
• statusul sandbox/production access se aplică per regiune,
• datele de configurare Magento trebuie să indice aceeași regiune,
• acreditările SMTP în SES sunt unice per regiune.

Dacă magazinul operează internațional, cel mai bine este să stabiliți de la început regiunea țintă pentru piața respectivă sau pentru întreaga organizație și să o păstrați consecvent.

3. Verificarea domeniului sau a adresei expeditorului

Cea mai bună practică pentru un magazin este verificarea întregului domeniu, nu doar a unei singure adrese email.

Variantă recomandată

Verificați domeniul, de exemplu example.com.

Datorită acestui lucru:

• puteți trimite din mai multe adrese ale domeniului respectiv,
• puteți trece mai ușor la trimiterea de producție,
• vă pregătiți mai bine pentru campanii, tranzacții și mai mulți expeditori,
• puteți gestiona mai ușor mai multe magazine, limbi și branduri într-un singur ecosistem.

Pași

1. În SES mergeți la Identities.
2. Selectați Create identity.
3. Alegeți tipul Domain.
4. Introduceți domeniul de trimitere.
5. Activați Easy DKIM dacă nu aveți un motiv să folosiți propriile chei DKIM.
6. Adăugați în zona DNS înregistrările indicate de AWS.
7. Așteptați statusul Verified.

Set minim de DNS

În practică veți avea nevoie cel puțin de:

• înregistrări de verificare SES,
• înregistrări DKIM,
• opțional o înregistrare pentru custom MAIL FROM.

4. Ieșirea din sandbox-ul SES

Un cont SES nou funcționează de obicei inițial în sandbox.

Asta înseamnă, printre altele, că:

• puteți trimite doar din identități verificate,
• și destinatarii trebuie să fie verificați,
• nu veți putea efectua trimitere normală de producție către clienții magazinului.

Pași

1. În SES deschideți Account dashboard sau ecranul inițial de configurare.
2. Selectați opțiunea Request production access.
3. Completați formularul conform scopului sistemului:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Descrieți că trimiterea va fi realizată din propriul Magento pentru un magazin online.
5. Trimiteți cererea.

Înainte de a trimite cererea este bine să aveți deja domeniul verificat. Acest lucru accelerează de obicei aprobarea.

5. Configurarea deliverability

Acesta nu este minimul obligatoriu pentru primul test, dar este puternic recomandat înainte de producție.

DKIM

Dacă folosiți Easy DKIM, SES semnează automat mesajele după configurarea corectă a DNS.

Custom MAIL FROM

Dacă doriți să îmbunătățiți controlul asupra expeditorului tehnic și deliverability:

1. Deschideți domeniul verificat în SES.
2. Configurați Custom MAIL FROM domain, de exemplu mail.example.com.
3. Adăugați în DNS:
   • înregistrare MX,
   • înregistrare SPF/TXT pentru MAIL FROM.

Acest lucru este deosebit de potrivit pentru magazinele care derulează email marketing regulat și doresc să limiteze problemele legate de reputația expeditorului.

6. Varianta A - integrare prin Amazon SES API

Această variantă utilizează tipul de transport ses disponibil în Kowal_EmailTransport.

Când să alegeți această variantă

Alegeți SES API dacă:

• doriți să folosiți direct Amazon SES ca provider,
• doriți să mențineți un cont de transport de tip ses,
• doriți să faceți routing pentru mesaje prin Kowal_EmailTransport.

6.1. Crearea utilizatorului IAM pentru trimitere

Nu folosiți contul root.

Pregătiți un utilizator IAM separat, de exemplu:

• magento-ses-sender

Apoi atribuiți-i o politică cu drepturi minime pentru trimitere.

Exemplu de politică minimă

{ 'Version': '2012-10-17', 'Statement': [ { 'Effect': 'Allow', 'Action': [ 'ses:SendEmail', 'ses:SendRawEmail' ], 'Resource': '*' } ]}

Dacă doriți, o puteți extinde cu citirea limitelor sau a statisticilor, însă pentru trimiterea în sine aria de mai sus este punctul de plecare.

6.2. Crearea Access Key și Secret Key

1. Deschideți IAM.
2. Accesați Users.
3. Deschideți utilizatorul pregătit.
4. Intrați în fila Security credentials.
5. În secțiunea Access keys selectați Create access key.
6. Salvați:
   • Access Key ID
   • Secret Access Key

Secretul va fi afișat o singură dată. Dacă îl pierdeți, trebuie să creați o cheie nouă.

6.3. Date necesare pentru Magento în varianta API

Pentru contul de transport ses din Magento pregătiți:

• provider_region, de exemplu eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email opțional,
• store_id, dacă contul trebuie să funcționeze doar pentru un anumit store view.

6.4. Mapare în panoul Magento

În Kowal / Email Marketing:

1. Adăugați un cont nou de transport.
2. Setați:
   • Transport Type = Amazon SES,
   • Region = regiunea SES,
   • Access Key = cheia IAM,
   • Secret Key = secretul IAM.
3. Salvați contul.
4. Asociați contul cu routing-ul mesajelor.
5. Efectuați un test de trimitere din contul de transport.

7. Varianta B - integrare prin Amazon SES SMTP

Această variantă utilizează Kowal_EmailSmtp.

Când să alegeți această variantă

Alegeți SES SMTP dacă:

• doriți să implementați Amazon SES ca sursă SMTP,
• folosiți pachetul Advance Email Delivery,
• doriți să păstrați un model de integrare mai simplu în Magento.

7.1. Crearea acreditărilor SMTP în SES

1. Deschideți Amazon SES.
2. Accesați SMTP settings.
3. Selectați Create SMTP credentials.
4. AWS vă va ghida prin crearea unui utilizator IAM pentru SMTP.
5. Salvați:
   • SMTP username
   • SMTP password

Acestea nu sunt chei AWS obișnuite. Sunt acreditări SMTP separate pentru SES.

7.2. Endpoint SMTP

Pentru SES folosiți host-ul în formatul:

email-smtp..amazonaws.com

Exemplu:

email-smtp.eu-central-1.amazonaws.com

7.3. Port și criptare

Cele mai frecvent utilizate setări:

• port 587 + STARTTLS,
• sau port 465 + TLS Wrapper / SSL.

În practică, pentru Magento cel mai sigur punct de pornire este:

• host: email-smtp..amazonaws.com
• port: 587
• security: STARTTLS

7.4. Date necesare pentru Magento în varianta SMTP

Pregătiți:

• host SMTP,
• port,
• tipul de criptare,
• login SMTP,
• parola SMTP,
• adresa expeditorului conformă cu verified identity din SES.

7.5. Mapare în panoul Magento

În Kowal / Email Marketing:

1. În secțiunea smtp setați global:
   • enabled = Yes,
   • host = endpoint SES,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = adresa pentru test.
2. Salvați configurația.
3. Efectuați Send Test Email.

Dacă utilizați mai multe conturi sau mai multe store view, puteți configura și un cont de transport separat de tip smtp cu date de conexiune dedicate.

8. Ce să alegeți în acest proiect

Alegeți SES API dacă:

• doriți să folosiți conturi de transport ses,
• doriți să faceți routing al trimiterii per cont și provider,
• doriți să dezvoltați transportul fără a baza totul pe stratul SMTP.

Alegeți SES SMTP dacă:

• vă doriți o primă implementare mai rapidă,
• doriți să tratați SES ca pe un server SMTP extern,
• implementați în principal pachetul delivery bazat pe Kowal_EmailSmtp.

9. Checklist minim înainte de testul de trimitere

Înainte de primul test confirmați:

1. Contul AWS există și are facturarea activă.
2. Regiunea SES a fost aleasă.
3. Domeniul sau adresa expeditorului au status Verified.
4. Contul SES are production access sau testați doar în condiții de sandbox.
5. DKIM este configurat.
6. Magento are date corecte ale expeditorului.
7. Varianta de integrare a fost aleasă:
   • API,
   • sau SMTP.
8. Acreditările sunt stocate în siguranță.
9. Testul a fost trimis și livrarea mesajului a fost confirmată.

10. Cele mai frecvente erori

Contul este încă în sandbox

Simptom:

• mesajul nu ajunge la destinatari normali.

Cauză:

• lipsa production access.

Domeniul nu este verificat

Simptom:

• eroare a expeditorului sau respingerea trimiterii.

Cauză:

• lipsa unei verified identity pentru domeniu sau adresa expeditorului.

Regiune greșită

Simptom:

• datele par corecte, dar trimiterea tot nu funcționează.

Cauză:

• identitatea este verificată într-o altă regiune decât cea utilizată de integrare.

Confuzie între cheile API și acreditările SMTP

Simptom:

• autentificarea SMTP nu funcționează.

Cauză:

• în SMTP au fost introduse cheile IAM în loc de SMTP username și SMTP password.

Utilizarea contului root

Simptom:

• lipsă de separare a securității și rotație mai dificilă a acreditărilor.

Cauză:

• integrarea se bazează pe datele root în locul unui utilizator IAM separat sau al unor acreditări SMTP separate.

11. Linkuri către documentația oficială AWS

• Set up your SES account: https://docs.aws.amazon.com/ses/latest/dg/setting-up.html
• Creating and verifying identities: https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html
• Verified identities: https://docs.aws.amazon.com/ses/latest/dg/verify-addresses-and-domains.html
• Request production access: https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html
• SMTP credentials: https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html
• SMTP endpoint connection: https://docs.aws.amazon.com/ses/latest/dg/smtp-connect.html
• Custom MAIL FROM: https://docs.aws.amazon.com/ses/latest/dg/mail-from.html
• SES regions: https://docs.aws.amazon.com/ses/latest/dg/regions.html
• SES credentials overview: https://docs.aws.amazon.com/ses/latest/dg/send-email-concepts-credentials.html
• IAM access keys: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

12. Datele care trebuie transmise pentru implementare

La final, persoana care creează SES ar trebui să transmită pentru implementare exact acest set:

Pentru varianta SES API

• regiunea SES,
• verified domain,
• access key,
• secret key,
• adresa expeditorului,
• reply-to, dacă trebuie să fie diferit,
• informația dacă contul trebuie să funcționeze global sau per store view.

Pentru varianta SES SMTP

• regiunea SES,
• host SMTP,
• port,
• security mode,
• SMTP username,
• SMTP password,
• adresa expeditorului,
• adresa de test pentru verificare.