Jak zaktualizować cartridge Salesforce Commerce Cloud

Czego się dowiesz?

Dowiedz się, jak zaktualizować wkładkę Klaviyo Salesforce Commerce Cloud.

Czy korzystasz z wersji cartridge starszej niż 23.7.0? Zalecamy natychmiastową aktualizację do wersji 23.7.0 lub nowszej. Starsze wersje cartridge korzystają z interfejsów API Klaviyo w wersjach v1 i v2, które zostały wycofane i nie działają już zgodnie z oczekiwaniami. Zawsze zalecamy aktualizację do naszej najnowszej wersji (obecnie 25.7.0).

Kilka słów na początek

Wersja 23.7.0 zawiera szereg istotnych ulepszeń, z których część to zmiany architektoniczne dotyczące sposobu wyzwalania zdarzeń. Szczególne kwestie związane z uaktualnieniem z dowolnej wersji poniżej 23.70 do dowolnej wersji powyżej tej wersji opisano poniżej.

Poznaj stan obecnej integracje

Ważne jest, aby znać swoją obecną integrację SFCC oraz to, jakie zmiany lub dostosowania mogły zostać wprowadzone specjalnie dla Twojej witryny. Co najważniejsze, rozważ, czy konkretne dane zdarzeń, które wysyłasz do Klaviyo, zostały zmodyfikowane lub rozszerzone, oraz czy dodano jakiekolwiek zdarzenia niestandardowe.

Zalecamy porównanie kodu, który składa dane zdarzeń, z poprzednią wersją kartridża Klaviyo, dostępną na Githubie Klaviyo. Jeśli integracje nie zostały w dużym stopniu dostosowane, bieżące funkcje składania danych znajdziesz w int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js, a w przypadku Potwierdzenia zamówienia w int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Zanotuj wszystkie dostosowania, aby móc zastosować je ponownie po zainstalowaniu nowego kartridża.

Połącz piaskownicę SFCC z kontem testowym Klaviyo

Jeśli nie utworzono jeszcze dodatkowego konta Klaviyo do testów, oddzielnego od konta powiązanego ze środowiskiem produkcyjnym SFCC, zrób to. Następnie połącz środowisko piaskownicy SFCC z nowym kontem. Zalecamy wykonanie tego kroku przy użyciu wcześniejszej wersji cartridge’a Klaviyo, aby zweryfikować, że zdarzenia są prawidłowo wysyłane do dodatkowego konta Klaviyo i odbierane przez nie, zanim przejdziesz do aktualizacji bazy kodu do nowego cartridge’a Klaviyo.

Usuń poprzedni kod wkładu Klaviyo

Jeśli integracje nie były w dużym stopniu dostosowywane, większość poprzedniej integracji Klaviyo będzie można usunąć, po prostu kasując dwa foldery cartridge Klaviyo: int_klaviyo_core oraz int_klaviyo (dla Site Genesis) lub int_klaviyo_sfra (dla SFRA) z bazy kodu. Trzeba jednak również usunąć wszelki kod specyficzny dla Klaviyo, który mógł zostać dodany do plików szablonów, a być może także do plików JavaScript.

Dla Site Genesis

Standard integracje dla Site Genesis będą miały następujący kod dodany do footer_UI.isml:

<isinclude template="components/footer/klaviyoFooter"/>

Do minicart.isml zostanie też dodany następujący blok, cart.isml oraz wszelkich innych plików isml „cart”:

<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction
  == 'update'}">
   <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
</isif>

Dla SFRA

Standard integracje dla SFCC będą miały następujący kod dodany do pageFooter.isml:

<isinclude template="klaviyo/klaviyoFooter"/>

Będą też mieć dodany następujący kod do trasy AddProduct w kontrolerze Cart.js:

 if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
   var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/klaviyoUtils');
 KlaviyoUtils.trackAddToCart();
}

Zarówno w przypadku Site Genesis, jak i SFRA, po usunięciu folderów cartridge i wyżej wymienionych wycinków kodu źródłowego zaleca się przeszukanie bazy kodu pod kątem słowa „Klaviyo”. Zanim usuniesz pozostały w bazie kodu kod powiązany z Klaviyo, upewnij się, że wiesz, co robi, ponieważ te bloki mogą stanowić dostosowania, które trzeba będzie przywrócić po zainstalowaniu nowego cartridge.

Usuń usługi

Poprzednia integracja utworzyła KlaviyoTrackService, KlaviyoTrackProfile oraz KlaviyoTrackCredentials w sekcji Administration > Operations > Service. Wszystkie trzy można bezpiecznie usunąć, ponieważ proces integracji nowego wkładu Klaviyo utworzy nowe usługi o innych nazwach.

Nie jest krytyczne, aby stare usługi zostały usunięte, ale zaleca się je wyczyścić, aby uniknąć przyszłych nieporozumień.

Sprawdź preferencje witryny

Proces integracji nowego wkładu Klaviyo zachowa niektóre z poprzednich preferencji witryny Klaviyo, a także doda kilka nowych. Sprawdź preferencje witryny w grupie preferencji Klaviyo w sekcji Narzędzia sprzedawcy > Preferencje witryny > Preferencje niestandardowe > klaviyo i sprawdź, czy dodano jakiekolwiek preferencje niestandardowe specyficznie dla Twojej witryny. Jeśli dostosowano wkład, aby dodać własne ustawienia, warto je zachować. Dla porównania poniżej przedstawiamy cztery preferencje witryny, które są wbudowane w poprzednią integracje Klaviyo:

• Klaviyo włączone (ID: klaviyo_enabled)
  Flaga wskazująca, czy Klaviyo jest włączone czy wyłączone.
• Konto Klaviyo (ID: klaviyo_account)
  Twój publiczny klucz API Klaviyo lub identyfikator witryny (Site ID).
• Prywatny klucz API Klaviyo (ID: klaviyo_api_key)
  Prywatny klucz API Klaviyo.
• Typ obrazu dla Klaviyo (ID: klaviyo_image_size)
  Duży, mały, miniatura itp.

Przed skonfigurowaniem nowego kartridża zalecamy wykonanie kopii zapasowej bieżących preferencji witryny przez wyeksportowanie ich w sekcji Administracja > Rozwój witryny > Import i eksport witryny. Rozwiń Witryny, a następnie Nazwę witryny, i zaznacz pole Preferencje witryny przed wprowadzeniem nazwy pliku, do którego chcesz je wyeksportować. Twoje aktualne preferencje w Klaviyo nie powinny zostać negatywnie naruszone, gdy później zainstalujesz nowy cartridge, ale warto wykonać ich kopię zapasową na przyszłość.

Usuń moduły Klaviyo ze ścieżki modułu

Usuń int_klaviyo_core oraz int_klaviyo (Site Genesis) albo int_klaviyo_sfra (SFRA) ze ścieżki cartridge w Administracja > Witryny > Zarządzaj witrynami > [Nazwa witryny] > Ustawienia. Jeśli nie wykonasz tego kroku, pojawią się błędy wynikające z tego, że SFCC szuka cartridge’ów do załadowania, które już nie istnieją.

Sprawdź konsolę deweloperską i dziennik po stronie serwera pod kątem błędów

W tym momencie nie powinno już być żadnego kodu Klaviyo w Twojej bazie kodu. Zalecamy sprawdzenie frontendu, odwiedzenie stron takich jak wyniki wyszukiwania, PLP i PDP oraz wykonanie działań takich jak dodawanie produktów do koszyka, rozpoczęcie i ukończenie realizacji zakupu. Podczas wykonywania tych czynności obserwuj Konsolę deweloperską, aby sprawdzić, czy generowane są nowe błędy. Zrób to samo z dziennikiem żądań. Jeśli widzisz nowe błędy związane z Klaviyo, jest duża szansa, że nie usunięto w pełni całego poprzedniego kodu Klaviyo. Ważne jest, aby znaleźć źródło wszelkich nowych błędów i zanotować je przed ich usunięciem.

Zainstaluj nowy moduł Klaviyo

Wykonaj czynności opisane w Pierwsze kroki z Salesforce Commerce Cloud, aby zintegrować nowy cartridge z bazą kodu. Mogą występować kroki, których nie trzeba wykonywać — na przykład instancja SFCC może mieć (lub nie mieć) już skonfigurowane połączenia dla części OCAPI — ale ogólnie należy wykonać każdy krok integracji. Zdecydowanie trzeba będzie wymienić oba wkłady Klaviyo i ponownie dodać wycinki kodu źródłowego.

Pamiętaj, że po zaimportowaniu pliku metadata.zip będziesz mieć cztery nowe preferencje witryny, oprócz czterech, które zostały utworzone przez poprzednią wersję cartridge’a. Importowanie nowych preferencji nie powinno wpłynąć na poprzednie, ale zalecamy, aby przed kontynuowaniem jeszcze raz sprawdzić, czy wszystkie preferencje witryny Klaviyo są poprawne.

Ponieważ przechodzisz na nowszą wersję z kartridża sprzed wersji 23.7.0, nowe preferencje witryny Label Events as SFCC i Send Added To Cart Event as ‘Add To Cart’ powinny być ustawione odpowiednio na Nie i Tak. Spowoduje to dalsze wysyłanie zdarzeń bez etykiety metryki Salesforce Commerce Cloud oraz używanie typu zdarzenia Add To Cart (zamiast nowego Added to Cart). Nieprawidłowe ustawienie tych dwóch preferencji witryny spowoduje przerwanie raportowania i potencjalnie przerwanie istniejących sekwencji w Klaviyo.

Sprawdź, czy wszystkie gotowe zdarzenia działają

Zanim spróbujesz ponownie dodać jakiekolwiek dostosowania z poprzedniej integracji, upewnij się, że nowa instalacja modułu Klaviyo działa prawidłowo. Użyj frontend, aby wygenerować zdarzenia dla Wyszukiwanie w witrynie, Wyświetlenie kategorii, Wyświetlenie produktu, Dodanie do koszyka, Rozpoczęcie realizacji zakupu i Potwierdzenie zamówienia, a następnie sprawdź swoje konto Klaviyo, aby upewnić się, że te zdarzenia są poprawnie śledzone.

Sprawdź konsolę deweloperską pod kątem nowych błędów, które mogą być powiązane z integracjami, na wszystkich stronach generujących zdarzenia Klaviyo. Włącz szczegółowe rejestrowanie usług, zaznaczając pole wyboru Communication Log Enabled w sekcji Administration > Operations > Services > KlaviyoEventService - Details, a następnie przejrzyj pliki dzienników po stronie serwera, aby potwierdzić, że nie ma żadnych błędów oraz że dane zdarzeń są prawidłowo generowane dla każdego typu zdarzenia.

Porównaj dane zdarzeń ze środowiskiem produkcyjnym

Teraz porównaj dane zdarzeń na swoich kontach testowym i produkcyjnym Klaviyo, aby upewnić się, że niczego nie brakuje i że bieżące wartości odpowiadają oczekiwanemu typowi. Ważne jest, aby ustalić, czy nowa integracje wpłynie na jakiekolwiek raportowanie lub sekwencja. Zauważysz, że w porównaniu z poprzednią wersją cartridge są teraz ustawiane i wysyłane do Klaviyo dodatkowe właściwości.

Dodaj ponownie dostosowania specyficzne dla witryny

Teraz możesz ponownie zacząć dodawać dostosowania do swojego kodu Klaviyo. Ze względu na duże zmiany strukturalne i architektoniczne w najnowszym cartridge’u Klaviyo jest mało prawdopodobne, że uda się po prostu skopiować i wkleić kod niestandardowy bezpośrednio do cartridge’u Klaviyo.

Każdy typ zdarzenia w kartridżu Klaviyo ma funkcję getData, która znajduje się w osobnym pliku skryptu nazwanym zgodnie z typem zdarzenia. Te pliki można znaleźć w folderze int_klaviyo_core/cartridge/scripts/klaviyo/eventData i to najbardziej prawdopodobne miejsce, które zmodyfikujesz, aby dodać lub zaktualizować obiekty danych przekazywane dla każdego zdarzenia. Jeśli tworzysz nowe zdarzenia niestandardowe, zalecamy trzymanie się ustalonego wzorca polegającego na dodawaniu kodu do kontrolerów po stronie serwera (tj. bezpośrednio w SiteGen lub przez server.append w SFRA), który wywołuje funkcję getData z pliku skryptu dedykowanego nowemu zdarzeniu, a następnie używa funkcji trackEvent, aby wysłać te dane do Klaviyo przez KlaviyoEventService.

Rezultat

Ulepszono teraz zasobnik Klaviyo dla Salesforce Commerce Cloud.

Dodatkowe źródła