Asystent odzyskiwania koszyka oparty na sztucznej inteligencji dla Magento 2

Moduł Magento 2 do odzyskiwania porzuconych koszyków z funkcjami:

• wykrywania porzuconych koszyków
• scoringu koszyka z użyciem AI lub heurystyki
• generowania wiadomości e-mail odzyskujących koszyk
• opcjonalnego generowania kuponów
• rozmów z asystentem zakupowym AI
• panelu administracyjnego i analityki
• endpointów REST API oraz komend CLI

Przegląd

Moduł pomaga odzyskiwać porzucone koszyki w Magento 2 poprzez wykrywanie nieaktywnych koszyków, ocenę intencji zakupowej i wysyłkę wiadomości e-mail z bezpiecznym linkiem do przywrócenia koszyka. W zależności od konfiguracji może działać w dwóch trybach:

• tryb heuristic, bez zewnętrznego AI
• tryb OpenAI, z analizą AI, generowaniem treści e-maili i rozmowami z asystentem

Typowy przebieg działania:

1. Klient dodaje produkty do koszyka.
2. Klient opuszcza sklep bez złożenia zamówienia.
3. Po upływie skonfigurowanego czasu bezczynności koszyk zostaje oznaczony jako porzucony.
4. Moduł nadaje koszykowi scoring.
5. Jeśli wynik jest wystarczająco wysoki, wysyłany jest e-mail odzyskujący.
6. E-mail może zawierać kupon rabatowy oraz link do strony asystenta AI.
7. Jeśli klient wróci i złoży zamówienie, koszyk zostaje oznaczony jako odzyskany.

Wymagania

Przed instalacją upewnij się, że sklep spełnia poniższe wymagania:

• Magento 2 z dostępem do CLI
• poprawnie działający cron Magento
• skonfigurowana wysyłka e-maili transakcyjnych w Magento
• włączony HTTPS na storefrontcie
• jeśli używany jest tryb AI: konto OpenAI API z aktywnym billingiem i kluczem API

Zalecenia operacyjne:

• tryb produkcyjny dla sklepu live
• przetestowany szablon e-mail i poprawnie ustawiony nadawca
• polityka prywatności uwzględniająca korzystanie z usług AI, jeśli włączony jest tryb OpenAI

Instalacja

* = na produkcji użyj opcji --keep-generated

Typ: Composer

1. Dodaj repozytorium Composer do konfiguracji:

   

   composer config repositories.ai.abandoned.cart vcs https://github.com/kowalco/ai-abandoned-cart
   

2. Dodaj token dostępu do prywatnego repozytorium GitHub:

   

   composer config --global --auth github-oauth.github.com <YOUR_TOKEN>
   

3. Zainstaluj moduł przez Composer:

   

   composer require kowal/module-ai-abandoned-cart
   

Następnie uruchom:

bin/magento module:enable Kowal_AiAbandonedCart
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Checklista po instalacji

Po instalacji sprawdź:

• czy moduł jest włączony w Magento
• czy schemat bazy danych został zainstalowany przez setup:upgrade
• czy cron Magento działa poprawnie
• czy sklep wysyła e-maile transakcyjne
• czy storefront używa poprawnych adresów HTTPS

Przydatne komendy weryfikacyjne:

bin/magento module:status Kowal_AiAbandonedCart
bin/magento cron:run
bin/magento cache:flush

Konfiguracja

Magento Admin:

Stores -> Configuration -> Kowal -> AI Abandoned Cart

Strony administracyjne:

Marketing -> AI Abandoned Cart

Pola konfiguracyjne

Najważniejsze ustawienia:

• Enable Module Włącza lub wyłącza cały moduł.

• Cart Inactivity Threshold (minutes) Określa, po ilu minutach bezczynności aktywny koszyk ma zostać uznany za porzucony.

• AI Provider Dostępne wartości:

  • Heuristic Fallback
  • OpenAI

• OpenAI API Key Wymagane tylko wtedy, gdy AI Provider jest ustawiony na OpenAI.

• Minimum Intent Score Tylko koszyki z wynikiem równym lub wyższym od tej wartości kwalifikują się do wysyłki e-maila odzyskującego.

• Enable Dynamic Coupons Włącza generowanie jednorazowych kuponów dla wybranych porzuconych koszyków.

• Maximum Coupon Discount Określa górny limit automatycznie generowanego rabatu procentowego.

• Maximum Failed Email Attempts Określa, ile nieudanych prób wysyłki jest dozwolonych, zanim moduł przestanie ponawiać wysyłkę.

• Email Address for Message Copies Opcjonalny odbiorca BCC dla wiadomości odzyskujących.

• Enable AI Assistant Link Jeśli opcja jest włączona, wiadomość e-mail odzyskująca będzie zawierać bezpieczny link do strony asystenta AI.

• Conversation Expiration Time (minutes) Określa, jak długo ważny pozostaje link do asystenta AI.

• Batch Size Definiuje, ile koszyków jest przetwarzanych w jednym przebiegu detekcji, scoringu i wysyłki e-maili.

• Cart Analysis Prompt Używany, gdy aktywny jest scoring AI.

• Email Generation Prompt Używany do generowania treści wiadomości e-mail w trybie AI.

• Conversation Prompt Używany przez asystenta AI podczas rozmowy z klientem.

Zalecana konfiguracja początkowa

Na start bezpiecznym zestawem ustawień jest:

• Enable Module: Yes
• Cart Inactivity Threshold (minutes): 30
• AI Provider: Heuristic Fallback lub OpenAI
• Minimum Intent Score: 0.45
• Enable Dynamic Coupons: Yes
• Maximum Coupon Discount: 5
• Maximum Failed Email Attempts: 3
• Enable AI Assistant Link: Yes
• Conversation Expiration Time (minutes): 1440
• Batch Size: 100

Tryb Heuristic vs Tryb OpenAI

Tryb Heuristic

Użyj tego trybu, jeśli chcesz zacząć bez integracji z zewnętrznym AI.

W tym trybie moduł:

• wykrywa porzucone koszyki
• oblicza intent score na podstawie wbudowanych reguł biznesowych
• wysyła e-maile odzyskujące
• może generować kupony
• może nadal udostępniać stronę asystenta, ale odpowiedzi będą oparte na wbudowanej logice zamiast na OpenAI

Tryb OpenAI

Użyj tego trybu, jeśli zależy Ci na większej personalizacji.

W tym trybie moduł może dodatkowo:

• analizować kontekst koszyka przy użyciu OpenAI
• generować bardziej spersonalizowaną treść e-maili
• obsługiwać rozmowy z asystentem AI o produktach z koszyka
• wykorzystywać opisy produktów, produkty powiązane, up-sell i cross-sell w odpowiedziach

Konfiguracja OpenAI

Aby włączyć tryb OpenAI:

1. Utwórz klucz API na koncie OpenAI Platform.
2. W Magento Admin przejdź do Stores -> Configuration -> Kowal -> AI Abandoned Cart.
3. Ustaw AI Provider na OpenAI.
4. Wklej klucz do pola OpenAI API Key.
5. Zapisz konfigurację.
6. Wyczyść cache Magento.

Ważne informacje:

• subskrypcje ChatGPT i billing API to osobne rzeczy
• użycie API jest rozliczane niezależnie przez OpenAI
• w trybie AI prompt i kontekst koszyka są wysyłane do OpenAI

Cron Jobs

Moduł korzysta z cronów Magento do automatycznego przetwarzania.

Skonfigurowane zadania cron:

• kowal_ai_abandoned_cart_detect
• kowal_ai_abandoned_cart_score
• kowal_ai_abandoned_cart_email

Ich działanie:

• detect: wyszukuje nieaktywne koszyki kwalifikujące się jako porzucone
• score: wylicza intent score i reason code
• email: wysyła e-maile odzyskujące i zapisuje logi

Jeśli cron Magento nie działa, moduł nie będzie automatycznie przetwarzał koszyków.

Pierwszy test po konfiguracji

Po instalacji i konfiguracji wykonaj pełny test end-to-end:

1. Otwórz storefront jako klient niezalogowany.
2. Dodaj jeden lub kilka produktów do koszyka.
3. Rozpocznij checkout i wpisz adres e-mail.
4. Opuść checkout bez składania zamówienia.
5. Poczekaj, aż minie skonfigurowany próg bezczynności.
6. Uruchom cron lub komendy CLI ręcznie.
7. Potwierdź, że koszyk pojawił się w panelu administracyjnym.
8. Potwierdź, że e-mail odzyskujący został wysłany.
9. Otwórz link przywracający koszyk z wiadomości.
10. Jeśli opcja jest włączona, otwórz link do asystenta AI i wyślij wiadomość testową.

Ręczna sekwencja CLI:

bin/magento kowal:ai:cart:detect
bin/magento kowal:ai:cart:score
bin/magento kowal:ai:cart:send-emails

Strony administracyjne

Moduł dodaje dedykowane strony administracyjne pod:

Marketing -> AI Abandoned Cart

Dostępne sekcje:

• Dashboard Przegląd wykrytych i odzyskanych koszyków.

• Recovery Analytics Statystyki skuteczności odzyskiwania i metryki operacyjne.

• Conversations Historia rozmów z asystentem AI powiązanych z porzuconymi koszykami.

• Email Logs Rejestr wysłanych i nieudanych wiadomości odzyskujących.

Te strony są szczególnie przydatne podczas wdrożenia, ponieważ pozwalają sprawdzić, czy poprawnie działają detekcja, scoring, wysyłka e-maili i śledzenie odzyskanych koszyków.

Treść e-maili i doświadczenie klienta

Każdy e-mail odzyskujący może zawierać:

• spersonalizowany temat
• własną treść wiadomości
• podsumowanie produktów z koszyka
• wartość koszyka
• bezpieczny link do przywrócenia koszyka
• opcjonalny jednorazowy kupon rabatowy
• opcjonalny link do asystenta AI

Ścieżka klienta:

1. Klient otrzymuje e-mail.
2. Klient klika link przywracający i wraca do zapisanego koszyka.
3. Klient może opcjonalnie otworzyć stronę asystenta z wiadomości.
4. Asystent może odpowiadać na pytania o produkty, porównywać opcje i kierować klienta z powrotem do checkoutu.

Jak działają kupony

Jeśli dynamiczne kupony są włączone, moduł może wygenerować kupon, gdy:

• wartość koszyka jest wystarczająco wysoka
• intent score sugeruje, że rabat może pomóc
• wyliczony rabat nie przekracza skonfigurowanego maksimum

Obecne wbudowane zasady:

• koszyki poniżej 100 jednostek waluty sklepu nie otrzymują kuponu
• koszyki z wysokim intent score nie otrzymują kuponu
• koszyki o niższej intencji mogą otrzymać rabat, zwykle 3% lub 5%, ograniczony konfiguracją

Generowane kupony są:

• jednorazowe
• ograniczone per klient
• powiązane ze współdzieloną regułą koszykową Magento dla danego poziomu rabatu i sklepu

CLI

Możesz uruchamiać moduł ręcznie z poziomu CLI, szczególnie podczas testów i diagnostyki.

bin/magento kowal:ai:cart:detect
bin/magento kowal:ai:cart:score
bin/magento kowal:ai:cart:send-emails

Znaczenie komend:

• kowal:ai:cart:detect Wykrywa porzucone koszyki.

• kowal:ai:cart:score Nadaje koszykom scoring i reason code.

• kowal:ai:cart:send-emails Wysyła wiadomości odzyskujące dla kwalifikujących się koszyków.

Bezpieczeństwo

Linki do przywrócenia koszyka i asystenta używają podpisanych tokenów.

Payload tokena zawiera:

• quote_id
• email
• store_id
• expires_at

Token jest walidowany przez:

1. weryfikację podpisu
2. sprawdzenie daty wygaśnięcia
3. weryfikację własności koszyka

Dzięki temu klient otrzymuje bezpieczny link powiązany z konkretnym koszykiem i ograniczony czasowo.

Rozwiązywanie problemów

Koszyki nie są wykrywane

Sprawdź:

• czy quote nadal jest aktywny
• czy koszyk zawiera produkty
• czy quote nie ma powiązanego zakończonego zamówienia
• czy adres e-mail klienta został przechwycony
• czy minął próg bezczynności
• czy działa cron Magento

Koszyki są wykrywane, ale e-maile nie są wysyłane

Sprawdź:

• czy Enable Module jest włączone
• czy Minimum Intent Score nie jest ustawione zbyt wysoko
• czy wysyłka e-maili działa w Magento
• czy nie został osiągnięty limit Maximum Failed Email Attempts
• czy adres e-mail przypisany do koszyka jest poprawny

Tryb OpenAI jest włączony, ale wynik AI nie jest używany

Sprawdź:

• czy AI Provider jest ustawiony na OpenAI
• czy OpenAI API Key jest poprawnie uzupełniony
• czy serwer pozwala na połączenia wychodzące do API OpenAI
• czy konto OpenAI ma aktywny billing

Jeśli wywołanie OpenAI się nie powiedzie, moduł przełączy się na wbudowane zachowanie heurystyczne.

Link do asystenta AI otwiera się, ale odpowiedzi są ogólne

Sprawdź:

• czy aktywny jest tryb OpenAI
• czy prompt rozmowy jest poprawnie skonfigurowany
• czy link nadal jest ważny i nie wygasł

Uwagi do użycia produkcyjnego

Przed uruchomieniem na produkcji warto:

• sprawdzić treść wiadomości e-mail i branding
• przetestować politykę kuponową z realnymi regułami biznesowymi
• zweryfikować wymagania prywatności i compliance
• przetestować prompty AI na katalogu i tonie komunikacji sklepu
• monitorować pierwsze dni działania w Dashboard, Conversations i Email Logs

Informacje potrzebne przy zgłoszeniu supportowym

Przy zgłoszeniu problemu przygotuj:

• wersję Magento
• wersję PHP
• tryb sklepu: developer lub production
• informację, czy cron działa
• informację, czy problem występuje w trybie heuristic czy OpenAI
• przykładowy quote ID lub adres e-mail klienta, którego dotyczy problem
• odpowiednie wpisy z logów wyjątków lub logów systemowych Magento